From 8752d8e7d29c675381a5cba3175318cb718e5c66 Mon Sep 17 00:00:00 2001 From: Mees van der Wijk Date: Thu, 14 Aug 2025 18:10:54 +0200 Subject: [PATCH] Added MSA introductions --- ModuleClientAPI.md | 2 +- ModuleClientAPIIntroduction.md | 2 +- ModuleServerAPIIntroduction.md | 81 ++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 ModuleServerAPIIntroduction.md diff --git a/ModuleClientAPI.md b/ModuleClientAPI.md index a0c7ef5..1541ffa 100644 --- a/ModuleClientAPI.md +++ b/ModuleClientAPI.md @@ -1,4 +1,4 @@ -# ModuleClientAPI - Main +# ModuleClientAPI - Documentation ## Sub Classes diff --git a/ModuleClientAPIIntroduction.md b/ModuleClientAPIIntroduction.md index b4732c0..0668be0 100644 --- a/ModuleClientAPIIntroduction.md +++ b/ModuleClientAPIIntroduction.md @@ -1,4 +1,4 @@ -# ModuleClientAPI - Introductions +# ModuleClientAPI - Introduction The **ModuleClientAPI** is the heart of every interactive Getiyo module's front-end experience. When users visit your channel and see your module in action, they're interacting with code powered by this comprehensive client-side interface. Think of it as your module's direct connection to the Getiyo ecosystem—enabling real-time communication with your server-side logic, responding instantly to property changes from the editor, and creating seamless user experiences that feel native to the platform. diff --git a/ModuleServerAPIIntroduction.md b/ModuleServerAPIIntroduction.md new file mode 100644 index 0000000..c88b87c --- /dev/null +++ b/ModuleServerAPIIntroduction.md @@ -0,0 +1,81 @@ +# ModuleServerAPI - Introduction + +Welcome to the **ModuleServerAPI** — the powerful server-side foundation that brings your Getiyo modules to life. Every module you create relies on this API to handle the complex orchestration between users, data, and the Getiyo platform itself. + +## What is the ModuleServerAPI? + +Think of the ModuleServerAPI as your module's command center. While users interact with your module's visual interface through the [`ModuleClientAPI`](./ModuleClientAPI), the real magic happens server-side. This is where you process data, manage business logic, store sensitive information, and coordinate real-time experiences for multiple users simultaneously. + +The ModuleServerAPI runs in a secure server environment, giving you access to powerful capabilities that would be impossible or unsafe to implement client-side. Whether you're building a simple display widget or a complex interactive experience, this API provides the tools to create responsive, scalable, and secure modules. + +## Core Capabilities + +**Real-time Communication**: Instantly send messages to all connected clients or target specific users with [`api.broadcast()`](./ModuleServerAPI#broadcast) and [`api.getClient()`](./ModuleServerAPI#getclient). Your modules can respond to user interactions in real-time, creating engaging collaborative experiences. + +**Secure Property Management**: Handle module properties defined in [`module.json`](./ModuleJSON) that remain exclusively server-side — perfect for API keys, authentication tokens, sensitive configuration data, and persistent module state. Access and update these properties using [`api.getModuleProperty()`](./ModuleServerAPI#getmoduleproperty) and monitor changes with [`api.onModulePropertyUpdate()`](./ModuleServerAPI#onmodulepropertyupdate). While reference properties exist for scene-specific client-side data, your server-side logic should primarily rely on module properties for secure, persistent data management. + +**Rich File Operations**: Read, write, and host files with full scope control through [`api.readJSON()`](./ModuleServerAPI#readjson), [`api.writeJSON()`](./ModuleServerAPI#writejson), and [`api.addHost()`](./ModuleServerAPI#addhost). Store module-specific data, share files across your channel, or serve static content directly to users. + +**Show Control Integration**: Seamlessly integrate with Getiyo's cue list system using triggers and conditions. Register [`api.onTrigger()`](./ModuleServerAPI#ontrigger) handlers to respond to automated cues, and use [`api.finishServerCondition()`](./ModuleServerAPI#finishservercondition) to control show flow based on your module's state. + +**External Service Integration**: Connect to databases, APIs, and external services using battle-tested libraries like WebSocket, Redis, and Axios through [`api.Libs`](./ModuleServerAPILibs). Build modules that bridge Getiyo with your existing infrastructure. + +## How It Works + +When your module loads, the ModuleServerAPI automatically connects to any [`ModuleClientAPI`](./ModuleClientAPI) instances viewing your module. This creates a persistent, bidirectional communication channel that stays synchronized across scene changes, user interactions, and show control events. + +Your server-side code registers event listeners to respond to messages from clients, module property updates from the admin interface, scene transitions, and triggers from cue lists. Meanwhile, you can push updates, broadcast changes, and maintain state that persists across user sessions. + +Here's a simple example that demonstrates the API's event-driven nature: + +```javascript +// Respond to messages from any connected client +api.on('userAction', (client, actionData) => { + console.log(`User ${client.getClientID()} performed action:`, actionData); + + // Process the action server-side + const result = processUserAction(actionData); + + // Send response back to the specific user + client.send('actionResult', result); + + // Broadcast the update to all other users + const otherClients = Object.values(api.getClients()).filter( + (c) => c.getClientID() !== client.getClientID() + ); + + otherClients.forEach((c) => { + c.send('userUpdate', { + user: client.getClientID(), + action: actionData, + }); + }); +}); + +// Handle module property changes from the admin interface +api.onModulePropertyUpdate('apiKey', (newKey) => { + console.log('API key updated, reconnecting to external service...'); + + // Update external service connection with new credentials + reconnectExternalService(newKey); + + // Notify all clients that service is reconnecting + api.broadcast('serviceStatus', 'reconnecting'); +}); + +// Respond to cue list triggers +api.onTrigger('startSequence', (finish, status, ...args) => { + status('Starting sequence...'); + + // Use module properties for configuration + const sequenceConfig = api.getModuleProperty('sequenceSettings').getValue(); + + // Perform the triggered action + performSequence(args, sequenceConfig).then(() => { + // Signal completion to continue the cue list + finish(); + }); +}); +``` + +This introduction establishes the ModuleServerAPI's role and capabilities in a more narrative, welcoming tone while still providing concrete examples and clear