Fogu Library Documentation (fmp-js)

Overview

The Fogu library is a Node.js client for communicating with Fogu servers over TCP connections, providing real-time messaging, channels, acation, teams, and event handling.

Installation & Import

import { Fogu, fogu } from 'fmp-js';

// Or create a new instance explicitly:
const client = Fogu();

Main Class: Fogu

Connecting to the Server

// Connection URL format: fmp://username:password@host:port
await client.connect('fmp://user:pass@localhost:4222');

// Connection events
client.on('connected', () => {
  console.log('Connected to server');
});

client.on('error', (err) => {
  console.error('Connection error:', err);
});

client.on('close', () => {
  console.log('Connection closed');
});

Primary Methods

connect(url: string): Promise<void>

Establishes a connection to a Fogu server.

channel(name: string): FoguChannel

Creates and returns a channel instance with the given name.

team(name: string): OneTeam

Creates and returns a team/group instance.

close(): void

Closes the active connection.

Properties

• id: string – Client ID assigned by the server
• connected: boolean – Connection state

Class: FoguChannel

Channel Management

const channel = client.channel('my-channel');

// Create channel
await channel.create('Channel description');

// Update description
await channel.edit('New description');

// Remove channel
await channel.remove();

// Retrieve channel info
const info = await channel.info();

Publishing & Subscribing

Publish Messages

await channel.publish('my-topic', Buffer.from('Example message'));

Subscribe to Topics

await channel.subscribe('my-topic', (topic, message) => {
  console.log(`Received on topic ${topic}:`, message.toString());
});

acation & calls

Create a action

await channel.action('my-action', (message, reply) => {
  const response = Buffer.from('action response');
  reply(null, response);          // Success
  // reply(new Error('action error')); // Error
});

await channel.service([{
  name:'my-action',
 handle: (message, reply) => {
    const response = Buffer.from('action response');
    reply(null, response);          // Success
    // reply(new Error('action error')); // Error
  },
  info:""
}]);

Make a call

try {
  const response = await channel.call(
    'my-action',
    Buffer.from('call payload'),
    5000 // timeout (ms)
  );

  console.log('Response:', response.toString());
} catch (error) {
  console.error('call error:', error);
}

Query Methods

// List available acation
const acation = await channel.getacation();

// List events
const events = await channel.getEvents();

// List accessible channels
const channels = await channel.list();

Specialized Sub-channels

// WebSocket bridge
channel.ws().emit('event', Buffer.from('data'));

// MQTT bridge
channel.mqtt().publish('topic', Buffer.from('message'));

// Redis interface
channel.redis().set('key', Buffer.from('value'));

// Device APIs
channel.device();

// Application APIs
channel.app();

// Script APIs
channel.script();

Class: OneTeam

Team Management

const team = client.team('my-team');

// Create team
await team.create();

// Update team
await team.edit();

// List teams
await team.list();

// Remove team
await team.remove();

Member Management

const member = team.member();

// Add member
await member.create();

// Update member
await member.edit();

// List members
await member.list();

// Remove member
await member.remove();

Team Channel Management

const teamChannel = team.channel();

// Attach channel to team
await teamChannel.connect('channel-name');

// Detach channel
await teamChannel.disconnect('channel-name');

// List connected channels
await teamChannel.list();

Server Message Handling

Supported Server Commands

• INFO – Server information and client identification
• MSG – Published topic messages
• CH_REQ – Incoming action call
• RES / AUTH / CH_RES – call response frames
• OK – Operation acknowledgement
• ERROR – Server-side errors
• PING / PONG – Connection keep-alive

Complete Usage Example

import { Fogu } from 'fmp-js';

async function example() {
  const client = Fogu();

  try {
    // Connect
    await client.connect('fmp://user:pass@localhost:4222');

    // Create channel
    const channel = client.channel('example-channel');
    await channel.create('Example channel');

    // Subscribe
    await channel.subscribe('notifications', (topic, message) => {
      console.log(`Notification: ${message.toString()}`);
    });

    // Define a action
    await channel.action('calculator', (data, reply) => {
      const n = parseInt(data.toString(), 10);
      const result = n * 2;
      reply(null, Buffer.from(result.toString()));
    });

    // Publish message
    await channel.publish('notifications', Buffer.from('Hello world!'));

    // Make call
    const response = await channel.call('calculator', Buffer.from('5'), 3000);
    console.log(`Result: ${response.toString()}`); // "10"

  } catch (error) {
    console.error('Error:', error);
  } finally {
    client.close();
  }
}

example();

Error Handling

The library uses Promises and callback-based error handling:

try {
  await channel.publish('topic', payload);
} catch (error) {
  console.error('Publish failed:', error.message);
}

// action callbacks
channel.action('my-action', (message, reply) => {
  try {
    reply(null, result);
  } catch (error) {
    reply(error); // Sends error frame to caller
  }
});

Timeouts

All call operations support timeouts:

const response = await channel.call('action', data, 5000);

Buffer as Data Format

All data is transmitted as Buffers, giving full freedom over payload format:

// Text
Buffer.from('Simple text', 'utf8');

// JSON
Buffer.from(JSON.stringify({ key: 'value' }));

// Binary data
Buffer.from(arrayBuffer);