# NOSTR WebSocket Library Export Guide

This guide explains how to use the NOSTR WebSocket library in other C projects.

## Library Structure

The NOSTR WebSocket library consists of these key files for export:

### Core Files (Required)
- `nostr_websocket_tls.h` - Header with all function declarations and constants
- `nostr_websocket_mbedtls.c` - Main implementation using mbedTLS for SSL/TLS
- `../cjson/cJSON.h` and `../cjson/cJSON.c` - JSON parsing (lightweight)

### Dependencies
- **mbedTLS** - For SSL/TLS support (wss:// connections)
- **Standard C libraries** - socket, networking, etc.

## Quick Integration

### 1. Copy Files to Your Project
```bash
# Copy the library files
cp nostr_websocket_tls.h your_project/
cp nostr_websocket_mbedtls.c your_project/
cp ../cjson/cJSON.h your_project/
cp ../cjson/cJSON.c your_project/
```

### 2. Install mbedTLS Dependency
```bash
# Ubuntu/Debian
sudo apt-get install libmbedtls-dev

# Or build from source (see mbedTLS documentation)
```

### 3. Compile Your Project
```bash
gcc -o my_nostr_app my_app.c nostr_websocket_mbedtls.c cJSON.c \
    -lmbedtls -lmbedx509 -lmbedcrypto -lm
```

## Basic Usage Example

```c
#include "nostr_websocket_tls.h"
#include "cJSON.h"
#include <stdio.h>

int main() {
    // Connect to relay
    nostr_ws_client_t* client = nostr_ws_connect("wss://relay.damus.io");
    if (!client) {
        printf("Failed to connect\n");
        return 1;
    }
    
    // Create subscription filter
    cJSON* filter = cJSON_CreateObject();
    cJSON* kinds = cJSON_CreateArray();
    cJSON_AddItemToArray(kinds, cJSON_CreateNumber(1)); // Text notes
    cJSON_AddItemToObject(filter, "kinds", kinds);
    cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber(10));
    
    // Send REQ message
    nostr_relay_send_req(client, "my-sub", filter);
    
    // Receive messages
    char buffer[8192];
    while (1) {
        int len = nostr_ws_receive(client, buffer, sizeof(buffer), 1000);
        if (len > 0) {
            printf("Received: %s\n", buffer);
            
            // Parse message type
            char* msg_type;
            cJSON* parsed;
            if (nostr_parse_relay_message(buffer, &msg_type, &parsed) == 0) {
                if (strcmp(msg_type, "EOSE") == 0) {
                    printf("End of subscription\n");
                    free(msg_type);
                    cJSON_Delete(parsed);
                    break;
                }
                free(msg_type);
                cJSON_Delete(parsed);
            }
        }
    }
    
    // Cleanup
    nostr_ws_close(client);
    cJSON_Delete(filter);
    return 0;
}
```

## API Reference

### Connection Management
- `nostr_ws_connect(url)` - Connect to relay (ws:// or wss://)
- `nostr_ws_close(client)` - Close connection and cleanup
- `nostr_ws_get_state(client)` - Get connection state

### Messaging
- `nostr_ws_send_text(client, message)` - Send raw text message
- `nostr_ws_receive(client, buffer, size, timeout)` - Receive message
- `nostr_ws_ping(client)` - Send ping frame

### NOSTR Protocol Helpers
- `nostr_relay_send_req(client, sub_id, filters)` - Send REQ message
- `nostr_relay_send_event(client, event)` - Send EVENT message  
- `nostr_relay_send_close(client, sub_id)` - Send CLOSE message
- `nostr_parse_relay_message(message, type, json)` - Parse relay message

### Error Handling
- `nostr_ws_strerror(error_code)` - Get error string
- Return codes: `NOSTR_WS_SUCCESS`, `NOSTR_WS_ERROR_*`

## Advanced Configuration

### Custom Timeouts
```c
nostr_ws_set_timeout(client, 30000); // 30 second timeout
```

### Multiple Transports
The library supports both TCP (`ws://`) and TLS (`wss://`) automatically based on URL scheme.

## Cross-Platform Notes

### Linux/Unix
- Works out of the box with standard development tools
- Requires: gcc, mbedTLS development headers

### Potential Windows Support
- Would need Winsock2 adaptations in transport layer
- mbedTLS is cross-platform compatible

### Embedded Systems
- Lightweight design suitable for embedded use
- Memory usage: ~4KB per client + message buffers
- No dynamic allocations in hot paths

## Library Design Benefits

### Modular Architecture
- Clean separation between WebSocket protocol and NOSTR logic
- Transport layer abstraction (easy to add new transports)
- No global state - multiple clients supported

### Performance Optimized
- Minimal memory allocations
- Efficient SSL buffer handling
- Fast WebSocket frame parsing

### Production Ready
- Proper error handling throughout
- Resource cleanup on all code paths
- Thread-safe design (no shared state)

## Migration from Other Libraries

### From libwebsockets
```c
// Old libwebsockets code:
// lws_client_connect_info info = {...};
// wsi = lws_client_connect(context, &info);

// New NOSTR WebSocket library:
client = nostr_ws_connect("wss://relay.example.com");
```

### From raw sockets
The library handles all WebSocket protocol details, SSL/TLS, and NOSTR message formatting automatically.

## Support

- Based on WebSocket RFC 6455
- Implements NOSTR WebSocket conventions
- SSL/TLS via proven mbedTLS library
- Tested with major NOSTR relays

This library provides a clean, efficient way to integrate NOSTR WebSocket functionality into any C project with minimal dependencies and maximum portability.