First commit on a late git install

examples/integration_example/README.md

@@ -0,0 +1,186 @@
+# NOSTR Core Integration Example
+
+This directory contains a complete example showing how to integrate the NOSTR Core library into your own projects.
+
+## What This Example Demonstrates
+
+- **Library Initialization**: Proper setup and cleanup of the NOSTR library
+- **Identity Management**: Key generation, bech32 encoding, and format detection
+- **Event Creation**: Creating and signing different types of NOSTR events
+- **Input Handling**: Processing various input formats (mnemonic, hex, bech32)
+- **Utility Functions**: Using helper functions for hex conversion and error handling
+- **CMake Integration**: How to integrate the library in your CMake-based project
+
+## Building and Running
+
+### Method 1: Using CMake
+
+```bash
+# Create build directory
+mkdir build && cd build
+
+# Configure with CMake
+cmake ..
+
+# Build
+make
+
+# Run the example
+./my_nostr_app
+```
+
+### Method 2: Manual Compilation
+
+```bash
+# Compile directly (assuming you're in the c_nostr root directory)
+gcc -I. examples/integration_example/main.c nostr_core.c nostr_crypto.c cjson/cJSON.c -lm -o integration_example
+
+# Run
+./integration_example
+```
+
+## Expected Output
+
+The example will demonstrate:
+
+1. **Identity Management Demo**
+   - Generate a new keypair
+   - Display keys in hex and bech32 format
+
+2. **Event Creation Demo**
+   - Create a text note event
+   - Create a profile event
+   - Display the JSON for both events
+
+3. **Input Handling Demo**
+   - Process different input formats
+   - Show format detection and decoding
+
+4. **Utility Functions Demo**
+   - Hex conversion round-trip
+   - Error message display
+
+## Integration Patterns
+
+### Pattern 1: CMake Find Package
+
+If NOSTR Core is installed system-wide:
+
+```cmake
+find_package(nostr_core REQUIRED)
+target_link_libraries(your_app nostr_core::static)
+```
+
+### Pattern 2: CMake Subdirectory
+
+If NOSTR Core is a subdirectory of your project:
+
+```cmake
+add_subdirectory(nostr_core)
+target_link_libraries(your_app nostr_core_static)
+```
+
+### Pattern 3: pkg-config
+
+If using pkg-config:
+
+```cmake
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(NOSTR_CORE REQUIRED nostr_core)
+target_include_directories(your_app PRIVATE ${NOSTR_CORE_INCLUDE_DIRS})
+target_link_libraries(your_app ${NOSTR_CORE_LIBRARIES})
+```
+
+### Pattern 4: Direct Source Integration
+
+Copy the essential files to your project:
+
+```bash
+cp nostr_core.{c,h} nostr_crypto.{c,h} your_project/src/
+cp -r cjson/ your_project/src/
+```
+
+Then compile them with your project sources.
+
+## Code Structure
+
+### main.c Structure
+
+The example is organized into clear demonstration functions:
+
+- `demo_identity_management()` - Key generation and encoding
+- `demo_event_creation()` - Creating different event types
+- `demo_input_handling()` - Processing various input formats
+- `demo_utilities()` - Using utility functions
+
+Each function demonstrates specific aspects of the library while maintaining proper error handling and resource cleanup.
+
+### Key Integration Points
+
+1. **Initialization**
+   ```c
+   int ret = nostr_init();
+   if (ret != NOSTR_SUCCESS) {
+       // Handle error
+   }
+   ```
+
+2. **Resource Cleanup**
+   ```c
+   // Always clean up JSON objects
+   cJSON_Delete(event);
+   
+   // Clean up library on exit
+   nostr_cleanup();
+   ```
+
+3. **Error Handling**
+   ```c
+   if (ret != NOSTR_SUCCESS) {
+       printf("Error: %s\n", nostr_strerror(ret));
+       return ret;
+   }
+   ```
+
+## Customization
+
+You can modify this example for your specific needs:
+
+- Change the `app_config_t` structure to match your application's configuration
+- Add additional event types or custom event creation logic
+- Integrate with your existing error handling and logging systems
+- Add networking functionality using the WebSocket layer
+
+## Dependencies
+
+This example requires:
+- C99 compiler (gcc, clang)
+- CMake 3.12+ (for CMake build)
+- NOSTR Core library and its dependencies
+
+## Testing
+
+You can test different input formats by passing them as command line arguments:
+
+```bash
+# Test with mnemonic
+./my_nostr_app "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+
+# Test with hex private key
+./my_nostr_app "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+
+# Test with bech32 nsec
+./my_nostr_app "nsec1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+## Next Steps
+
+After studying this example, you can:
+
+1. Integrate the patterns into your own application
+2. Explore the WebSocket functionality for relay communication
+3. Add support for additional NOSTR event types
+4. Implement your own identity persistence layer
+5. Add networking and relay management features
+
+For more examples, see the other files in the `examples/` directory.