@jtl-software/cloud-apps-core 0.0.0-dev.05de610

package/README.md

@@ -0,0 +1,227 @@
+# ![JTL logo](https://avatars.githubusercontent.com/u/31404730?s=25&v=4) JTL-Platform Apps Core SDK
+
+A lightweight, type-safe communication bridge for JTL Platform apps.
+
+## 📦 Installation
+
+Install the package using npm or yarn:
+
+```bash
+# Using npm
+npm install @jtl-software/cloud-apps-core
+
+# Using yarn
+yarn add @jtl-software/cloud-apps-core
+```
+
+## 🔍 Overview
+
+The JTL Platform Apps Core SDK provides a robust communication bridge between apps and the JTL Platform host application. It enables:
+
+- Bidirectional method calling between apps and host
+- Event-based publish/subscribe communication
+- Type-safe messaging with Zod validation
+- Promise-based async communication
+
+This package is the foundation for building apps that integrate seamlessly with the JTL Platform ecosystem.
+
+## 🚀 Usage
+
+### Creating a App Bridge
+
+To use the AppBridge in your React components, you'll need to initialize it and maintain its instance in your component's state. Typically, this is done within a useEffect hook:
+
+```typescript
+import { createAppBridge, AppBridge } from '@jtl-software/cloud-apps-core';
+import { useState, useEffect } from 'react';
+
+function YourAppComponent() {
+  // Store the AppBridge instance in component state
+  const [appBridge, setAppBridge] = useState<AppBridge | undefined>(undefined);
+
+  useEffect((): void => {
+    console.info('Creating bridge...');
+    createAppBridge().then(bridge => {
+      console.log('Bridge created!');
+
+      // Store the bridge instance in state for use throughout your component
+      setAppBridge(bridge);
+    });
+  }, []);
+
+  // Rest of your component...
+}
+```
+
+### Subscribe to Host Events
+
+The `subscribe` method allows your app to listen for specific events emitted by the host environment.
+
+```typescript
+// Listen for inventory updates
+const unsubscribe = appBridge.event.subscribe('inventory:updated', async data => {
+  console.info('Inventory updated:', data);
+});
+
+// Later, you can unsubscribe
+unsubscribe();
+```
+
+When the host system triggers an "inventory:updated" event, your callback function will execute with the provided data.
+
+### Publish events to the host
+
+The `publish` method sends data to the host environment under a specific topic.
+
+```typescript
+// Notify the host about completed action
+await appBridge.event.publish('order:verification:complete', {
+  orderId: 'ORD-12345',
+  verifiedBy: 'app-user',
+});
+```
+
+This is useful for informing the host about state changes or actions completed within your app.
+
+### Exposing Methods to the Host
+
+The `expose` function makes your app's functions callable by the host environment.
+
+```typescript
+// Make a function available to the host
+const disposer = appBridge.method.expose('calculateShippingCost', (weight, destination) => {
+  const baseCost = 5.99;
+  const zoneRate = destination === 'international' ? 2.5 : 1;
+  return baseCost + 0.1 * weight * zoneRate;
+});
+
+// Check if a method is exposed
+const isExposed = appBridge.method.isExposed('calculateShippingCost'); // true
+
+// Later, you can remove the exposed method
+disposer();
+```
+
+This allows the host environment to directly use functionality implemented in your app.
+
+### Calling Host Methods
+
+The `call` function allows your app to invoke functions provided by the host environment.
+
+```typescript
+// Get user information
+const userProfile = await appBridge.method.call('getUserProfile');
+
+// Call a method with parameters
+const orderDetails = await appBridge.method.call('getOrderDetails', 'ORD-5678');
+```
+
+## 📚 API Reference
+
+### AppBridge
+
+The main class that handles communication between the app and host. It provides access to different capabilities through the following properties:
+
+- `method`: AppBridgeMethodCapability - Handles method calling functionality
+- `event`: AppBridgeEventCapability - Handles event publish/subscribe functionality
+
+---
+
+### AppBridgeEventCapability
+
+Handles event-based communication between the app and host.
+
+#### `subscribe<TPayload>(topic: string, callback: EventListener<TPayload>): () => void`
+
+**Description:**  
+Registers a listener for a specific event emitted by the host environment. When the event is triggered, the callback is executed with the event data.
+
+**Parameters:**
+
+- `topic` (string): The name of the event to listen for.
+- `callback` (function): A function that handles the event data. Can be sync or async.
+
+**Returns:** `() => void` - A function that, when called, unsubscribes the listener.
+
+---
+
+#### `unsubscribe<TPayload>(topic: string, callback: EventListener<TPayload>): void`
+
+**Description:**  
+Removes a specific callback from the event listeners for a topic.
+
+**Parameters:**
+
+- `topic` (string): The topic name to unsubscribe from.
+- `callback` (function): The specific callback function to remove.
+
+**Returns:** `void`
+
+---
+
+#### `publish<TPayload>(topic: string, payload: TPayload): Promise<void>`
+
+**Description:**  
+Sends data to the host under a specific topic, typically to notify about an action or a state change.
+
+**Parameters:**
+
+- `topic` (string): The topic name under which the data should be published.
+- `payload` (`TPayload`): The data to be sent to the host.
+
+**Returns:** `Promise<void>`
+
+---
+
+### AppBridgeMethodCapability
+
+Handles method calling functionality between the app and host.
+
+#### `expose<TMethod>(methodName: string, method: TMethod): () => void`
+
+**Description:**  
+Makes a app method available for the host to call directly.
+
+**Parameters:**
+
+- `methodName` (string): The name under which the method should be exposed.
+- `method` (`TMethod`): The actual method implementation.
+
+**Returns:** `() => void` - A disposer function that removes the exposed method when called.
+
+---
+
+#### `isExposed(methodName: string): boolean`
+
+**Description:**  
+Checks whether a method with the given name has already been exposed to the host.
+
+**Parameters:**
+
+- `methodName` (string): The name of the method to check.
+
+**Returns:** `boolean`
+
+---
+
+#### `call<TResponse>(methodName: string, ...args: unknown[]): Promise<TResponse>`
+
+**Description:**  
+Calls a method provided by the host environment and returns the result.
+
+**Parameters:**
+
+- `methodName` (string): The name of the host method to call.
+- `...args` (unknown[]): The arguments to pass to the host method.
+
+**Returns:** `Promise<TResponse>`
+
+### Factories
+
+- `createAppBridge()`: Creates and initializes a AppBridge instance
+
+## 📦 Dependencies
+
+This package has minimal dependencies:
+
+- `zod`: For runtime type validation

package/dist/AppBridge.d.ts

@@ -0,0 +1,7 @@
+import { AppBridgeEventCapability, AppBridgeMethodCapability } from './capabilities';
+import { AppBridgeInfrastructure, AppBridgeMessagePort } from './core';
+export default class AppBridge extends AppBridgeInfrastructure {
+    readonly method: AppBridgeMethodCapability;
+    readonly event: AppBridgeEventCapability;
+    constructor(appBridgeMessagePort: AppBridgeMessagePort);
+}

package/dist/capabilities/event/AppBridgeEventCapability.d.ts

@@ -0,0 +1,10 @@
+import { AppBridgeCapability, AppBridgeMessagePort } from '../../core';
+import { EventListener } from './types';
+export default class AppBridgeEventCapability extends AppBridgeCapability<'event'> {
+    private readonly _eventListeners;
+    constructor(appBridgeMessagePort: AppBridgeMessagePort);
+    subscribe<TPayload>(topic: string, callback: EventListener<TPayload>): () => void;
+    unsubscribe<TPayload>(topic: string, callback: EventListener<TPayload>): void;
+    publish<TPayload>(topic: string, payload: TPayload): Promise<void>;
+    private handlePublishedEvent;
+}

package/dist/capabilities/event/AppBridgeEventCapability.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/event/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export { default as AppBridgeEventCapability } from './AppBridgeEventCapability';

package/dist/capabilities/event/types/EventListener.d.ts

@@ -0,0 +1,2 @@
+type EventListener<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;
+export default EventListener;

package/dist/capabilities/event/types/EventObject.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+declare const EventObject: z.ZodObject<{
+    topic: z.ZodString;
+    payload: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    topic: string;
+    payload?: unknown;
+}, {
+    topic: string;
+    payload?: unknown;
+}>;
+type EventObject = z.infer<typeof EventObject>;
+export default EventObject;

package/dist/capabilities/event/types/index.d.ts

@@ -0,0 +1,2 @@
+export type { default as EventListener } from './EventListener';
+export { default as EventObject } from './EventObject';

package/dist/capabilities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './event';
+export * from './method';

package/dist/capabilities/method/AppBridgeMethodCapability.d.ts

@@ -0,0 +1,10 @@
+import { Disposer, AppBridgeCapability, AppBridgeMessagePort } from '../../core';
+export default class AppBridgeMethodCapability extends AppBridgeCapability<'method'> {
+    private readonly _exposedMethods;
+    constructor(appBridgeMessagePort: AppBridgeMessagePort);
+    expose<TMethod>(methodName: string, method: TMethod): Disposer;
+    removeExposedMethod(methodName: string): void;
+    isExposed(methodName: string): boolean;
+    call<TResponse>(methodName: string, ...args: unknown[]): Promise<TResponse>;
+    private handleMethodCall;
+}

package/dist/capabilities/method/AppBridgeMethodCapability.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/method/index.d.ts

@@ -0,0 +1 @@
+export { default as AppBridgeMethodCapability } from './AppBridgeMethodCapability';

package/dist/capabilities/method/types/MethodCallBody.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+declare const MethodCallBody: z.ZodObject<{
+    methodName: z.ZodString;
+    args: z.ZodArray<z.ZodUnknown, "many">;
+}, "strip", z.ZodTypeAny, {
+    methodName: string;
+    args: unknown[];
+}, {
+    methodName: string;
+    args: unknown[];
+}>;
+type MethodCallBody = z.infer<typeof MethodCallBody>;
+export default MethodCallBody;

package/dist/capabilities/method/types/index.d.ts

@@ -0,0 +1 @@
+export { default as MethodCallBody } from './MethodCallBody';

package/dist/core/AppBridgeMessagePort.d.ts

@@ -0,0 +1,11 @@
+import { ChannelMessageHandler, SendAppBridgeMessageOptions } from './types';
+export default class AppBridgeMessagePort {
+    private readonly messagePort;
+    private static readonly DEFAULT_SEND_MESSAGE_TIMEOUT;
+    private readonly channelMessageHandlers;
+    private _messageLookup;
+    constructor(messagePort: MessagePort);
+    sendMessage<TBody, TResponse = void>(subject: string, body?: TBody, options?: SendAppBridgeMessageOptions): Promise<TResponse>;
+    registerMessageHandler(subject: string, handler: ChannelMessageHandler): void;
+    private handleMessage;
+}

package/dist/core/AppBridgeMessagePort.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/abstractions/AppBridgeCapability.d.ts

@@ -0,0 +1,9 @@
+import { default as IAppBridgeCapability } from './IAppBridgeCapability';
+import { default as AppBridgeMessagePort } from '../AppBridgeMessagePort';
+import { ChannelMessageHandler, SendAppBridgeMessageOptions } from '../types';
+export default abstract class AppBridgeCapability<NAME extends string> implements IAppBridgeCapability {
+    private readonly appBridgeMessagePort;
+    protected constructor(appBridgeMessagePort: AppBridgeMessagePort);
+    protected registerMessageHandler(subject: `${NAME}:${string}`, messageHandler: ChannelMessageHandler): void;
+    protected sendMessage<TBody, TResponse = void>(subject: `${NAME}:${string}`, body: TBody, options?: SendAppBridgeMessageOptions): Promise<TResponse>;
+}

package/dist/core/abstractions/AppBridgeInfrastructure.d.ts

@@ -0,0 +1,9 @@
+import { default as IAppBridgeCapability } from './IAppBridgeCapability';
+import { default as AppBridgeMessagePort } from '../AppBridgeMessagePort';
+export default abstract class AppBridgeInfrastructure {
+    private readonly appBridgeMessagePort;
+    protected constructor(appBridgeMessagePort: AppBridgeMessagePort);
+    protected registerCapability<T>(capability: IAppBridgeCapability & {
+        new (appBridgeMessagePort: AppBridgeMessagePort): T;
+    }): T;
+}

package/dist/core/abstractions/IAppBridgeCapability.d.ts

@@ -0,0 +1,2 @@
+export default interface IAppBridgeCapability {
+}

package/dist/core/abstractions/index.d.ts

@@ -0,0 +1,3 @@
+export type { default as IAppBridgeCapability } from './IAppBridgeCapability';
+export { default as AppBridgeCapability } from './AppBridgeCapability';
+export { default as AppBridgeInfrastructure } from './AppBridgeInfrastructure';

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './abstractions';
+export * from './types';
+export { default as AppBridgeMessagePort } from './AppBridgeMessagePort';

package/dist/core/types/ChannelMessage.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+declare const ChannelMessage: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["HANDSHAKE", "REQUEST", "RESPONSE", "ERROR"]>;
+    subject: z.ZodString;
+    body: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "HANDSHAKE" | "REQUEST" | "RESPONSE" | "ERROR";
+    id: string;
+    subject: string;
+    body?: unknown;
+}, {
+    type: "HANDSHAKE" | "REQUEST" | "RESPONSE" | "ERROR";
+    id: string;
+    subject: string;
+    body?: unknown;
+}>;
+type ChannelMessage = z.infer<typeof ChannelMessage>;
+export default ChannelMessage;

package/dist/core/types/ChannelMessageHandler.d.ts

@@ -0,0 +1,3 @@
+import { default as ChannelMessage } from './ChannelMessage';
+type ChannelMessageHandler = (channelMessage: ChannelMessage) => unknown | Promise<unknown>;
+export default ChannelMessageHandler;

package/dist/core/types/Disposer.d.ts

@@ -0,0 +1,2 @@
+type Disposer = () => void;
+export default Disposer;

package/dist/core/types/IMessageLookup.d.ts

@@ -0,0 +1,6 @@
+export default interface IMessageLookup<TOutput> {
+    promise: {
+        resolve: (value?: TOutput | PromiseLike<TOutput>) => void;
+        reject: (reason?: unknown) => void;
+    };
+}

package/dist/core/types/MessageType.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+declare const MessageType: z.ZodEnum<["HANDSHAKE", "REQUEST", "RESPONSE", "ERROR"]>;
+type MessageType = z.infer<typeof MessageType>;
+export default MessageType;

package/dist/core/types/SendAppBridgeMessageOptions.d.ts

@@ -0,0 +1,8 @@
+type SendAppBridgeMessageOptions = {
+    /**
+     * Timeout in milliseconds for the message to be resolved.
+     * Default is 30 seconds.
+     */
+    timeout?: number;
+};
+export default SendAppBridgeMessageOptions;

package/dist/core/types/index.d.ts

@@ -0,0 +1,6 @@
+export { default as ChannelMessage } from './ChannelMessage';
+export { default as MessageType } from './MessageType';
+export type { default as ChannelMessageHandler } from './ChannelMessageHandler';
+export type { default as Disposer } from './Disposer';
+export type { default as IMessageLookup } from './IMessageLookup';
+export type { default as SendAppBridgeMessageOptions } from './SendAppBridgeMessageOptions';

package/dist/factories/createAppBridge.d.ts

@@ -0,0 +1,2 @@
+import { default as AppBridge } from '../AppBridge';
+export default function createAppBridge(): Promise<AppBridge>;

package/dist/factories/createAppBridge.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/factories/index.d.ts

@@ -0,0 +1 @@
+export { default as createAppBridge } from './createAppBridge';

package/dist/main.d.ts

@@ -0,0 +1,4 @@
+export * from './capabilities';
+export * from './core';
+export * from './factories';
+export { default as AppBridge } from './AppBridge';