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

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

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

---

Main Class: Fogu

$3

`javascript
// 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');
});
`

$3

#### connect(url: string): Promise

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.

$3

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

---

Class: FoguChannel

$3

`javascript
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();
`

---

$3

#### Publish Messages

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

#### Subscribe to Topics

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

---

$3

#### Create a action

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

`javascript
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

`javascript
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);
}
`

---

$3

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

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

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

---

$3

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

$3

`javascript
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();
`

---

$3

`javascript
const member = team.member();

// Add member
await member.create();

// Update member
await member.edit();

// List members
await member.list();

// Remove member
await member.remove();
`

---

$3

`javascript
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

$3

* 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

`javascript
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:

`javascript
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:

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

---

Buffer as Data Format

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

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

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

// Binary data
Buffer.from(arrayBuffer);
``

---