logos-delivery/library/README.md

# Logos Messaging API (LMAPI) Library

A C FFI library providing a simplified interface to Logos Messaging functionality.

## Overview

This library wraps the high-level API functions from `waku/api/api.nim` and exposes them via a C FFI interface, making them accessible from C, C++, and other languages that support C FFI.

## API Functions

### Node Lifecycle

#### `logosdelivery_create_node`
Creates a new instance of the node from the given configuration JSON.

```c
void *logosdelivery_create_node(
    const char *configJson,
    FFICallBack callback,
    void *userData
);
```

**Parameters:**
- `configJson`: JSON string containing node configuration
- `callback`: Callback function to receive the result
- `userData`: User data passed to the callback

**Returns:** Pointer to the context needed by other API functions, or NULL on error.

**Example configuration JSON:**
```json
{
  "mode": "Core",
  "preset": "logos.dev",
  "messagingOverrides": {
    "listen-address": "0.0.0.0",
    "tcp-port": 60000,
    "discv5-udp-port": 9000
  }
}
```

The configuration object has four optional top-level keys: `mode` (`"Core"` or
`"Edge"`, defaults to `"Core"`), `preset`, `messagingOverrides` (per-field node
config overrides), and `channelsOverrides` (reliable-channel overrides).
Override keys accept the config field name or its CLI switch name (e.g.
`"clusterId"` or `"cluster-id"`); unknown keys are rejected.
Use `"preset"` to select a network preset (e.g., `"twn"`, `"logos.dev"`,
`"status.prod"`) which auto-configures entry nodes, cluster ID, sharding, and
other network-specific settings.

Available presets:

| Preset | Cluster ID | RLN | Sharding | Network |
| --- | --- | --- | --- | --- |
| `twn` | 1 | on | auto (8 shards) | The Waku Network |
| `logos.dev` | 2 | off | auto (8 shards) | Logos Dev Network |
| `logos.test` | 2 | off | auto (8 shards) | Logos Test Network |
| `status.prod` | 16 | off | auto (1 shard) | Status Production Network |

#### `logosdelivery_start_node`
Starts the node.

```c
int logosdelivery_start_node(
    void *ctx,
    FFICallBack callback,
    void *userData
);
```

#### `logosdelivery_stop_node`
Stops the node.

```c
int logosdelivery_stop_node(
    void *ctx,
    FFICallBack callback,
    void *userData
);
```

#### `logosdelivery_destroy`
Destroys a node instance and frees resources.

```c
int logosdelivery_destroy(
    void *ctx,
    FFICallBack callback,
    void *userData
);
```

### Messaging

#### `logosdelivery_subscribe`
Subscribe to a content topic to receive messages.

```c
int logosdelivery_subscribe(
    void *ctx,
    FFICallBack callback,
    void *userData,
    const char *contentTopic
);
```

**Parameters:**
- `ctx`: Context pointer from `logosdelivery_create_node`
- `callback`: Callback function to receive the result
- `userData`: User data passed to the callback
- `contentTopic`: Content topic string (e.g., "/myapp/1/chat/proto")

#### `logosdelivery_unsubscribe`
Unsubscribe from a content topic.

```c
int logosdelivery_unsubscribe(
    void *ctx,
    FFICallBack callback,
    void *userData,
    const char *contentTopic
);
```

#### `logosdelivery_send`
Send a message.

```c
int logosdelivery_send(
    void *ctx,
    FFICallBack callback,
    void *userData,
    const char *messageJson
);
```

**Parameters:**
- `messageJson`: JSON string containing the message

**Example message JSON:**
```json
{
  "contentTopic": "/myapp/1/chat/proto",
  "payload": "SGVsbG8gV29ybGQ=",
  "ephemeral": false
}
```

Note: The `payload` field should be base64-encoded.

**Returns:** Request ID in the callback message that can be used to track message delivery.

### Events

#### `logosdelivery_add_event_listener`
Registers a callback invoked whenever the named event fires (e.g., message received).
Listeners are registered per event name, so register once for each event you want
to observe.

```c
uint64_t logosdelivery_add_event_listener(
    void *ctx,
    const char *eventName,
    FFICallBack callback,
    void *userData
);
```

**Returns:** The listener id (> 0), or 0 if `callback` is NULL.

Event names: `onMessageSent`, `onMessageError`, `onMessagePropagated`,
`onMessageReceived`, `onConnectionStatusChange`, `onTopicHealthChange`,
`onConnectionChange`, `onChannelMessageReceived`, `onChannelMessageSent`,
`onChannelMessageError`, `onReceivedMessage`.

#### `logosdelivery_remove_event_listener`
Unregisters a previously added listener.

```c
int logosdelivery_remove_event_listener(
    void *ctx,
    uint64_t listenerId
);
```

**Returns:** `RET_OK` when a listener was removed, `RET_ERR` otherwise.

**Important:** The callback should be fast, non-blocking, and thread-safe.

## Building

The library follows the same build system as the main Logos Messaging project.

### Build the library

```bash
make liblogosdeliveryStatic    # Build static library
# or
make liblogosdeliveryDynamic   # Build dynamic library
```

## Return Codes

All functions that return `int` use the following return codes:

- `RET_OK` (0): Success
- `RET_ERR` (1): Error
- `RET_MISSING_CALLBACK` (2): Missing callback function

## Callback Function

All API functions use the following callback signature:

```c
typedef void (*FFICallBack)(
    int callerRet,
    const char *msg,
    size_t len,
    void *userData
);
```

**Parameters:**
- `callerRet`: Return code (RET_OK, RET_ERR, etc.)
- `msg`: Response message (may be empty for success)
- `len`: Length of the message
- `userData`: User data passed in the original call

## Example Usage

```c
#include "liblogosdelivery.h"
#include <stdio.h>

void callback(int ret, const char *msg, size_t len, void *userData) {
    if (ret == RET_OK) {
        printf("Success: %.*s\n", (int)len, msg);
    } else {
        printf("Error: %.*s\n", (int)len, msg);
    }
}

int main() {
    const char *config = "{"
        "\"logLevel\": \"INFO\","
        "\"mode\": \"Core\","
        "\"preset\": \"logos.dev\""
        "}";

    // Create node
    void *ctx = logosdelivery_create_node(config, callback, NULL);
    if (ctx == NULL) {
        return 1;
    }

    // Start node
    logosdelivery_start_node(ctx, callback, NULL);

    // Subscribe to a topic
    logosdelivery_subscribe(ctx, callback, NULL, "/myapp/1/chat/proto");

    // Send a message
    const char *msg = "{"
        "\"contentTopic\": \"/myapp/1/chat/proto\","
        "\"payload\": \"SGVsbG8gV29ybGQ=\","
        "\"ephemeral\": false"
        "}";
    logosdelivery_send(ctx, callback, NULL, msg);

    // Clean up
    logosdelivery_stop_node(ctx, callback, NULL);
    logosdelivery_destroy(ctx, callback, NULL);

    return 0;
}
```

## Architecture

The library is structured as follows:

- `liblogosdelivery.h`: C header file with function declarations
- `liblogosdelivery.nim`: Main library entry point
- `declare_lib.nim`: Library declaration and initialization
- `lmapi/node_api.nim`: Node lifecycle API implementation
- `lmapi/messaging_api.nim`: Subscribe/send API implementation

The library uses the nim-ffi framework for FFI infrastructure, which handles:
- Thread-safe request processing
- Async operation management
- Memory management between C and Nim
- Callback marshaling

## See Also

- Main API documentation: `waku/api/api.nim`
- Original libwaku library: `library/libwaku.nim`
- nim-ffi framework: `vendor/nim-ffi/`