JTL-Platform Apps Core SDK

A lightweight, type-safe communication bridge for JTL Platform apps.

📦 Installation

Install the package using npm or yarn:

# 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:

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.

// 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.

// 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.

// 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.

// 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