# PrivateBin API Library

A C++ library for interacting with PrivateBin servers via the JSON API v1.3.

## Features

- **Text Paste Creation**: Create encrypted text pastes with multiple formats
- **File Upload**: Upload files as encrypted pastes
- **Paste Retrieval**: Retrieve and decrypt pastes
- **Paste Deletion**: Delete pastes with deletion tokens
- **End-to-End Encryption**: Client-side encryption with AES-256-GCM
- **Cross-Platform**: Support for Windows and Linux
- **Complete API**: Implementation of all PrivateBin v1.3 API functions
- **Automated Builds**: Platform-specific build scripts for easy compilation
- **Text Formatting**: Support for plaintext, syntax highlighting, and markdown

## Text Formatting Support

The library supports multiple text formats as defined in the [PrivateBin API v1.3](https://github.com/PrivateBin/PrivateBin/wiki/API):

### Available Formats

- **`plaintext`** - Plain text (default format)
- **`syntaxhighlighting`** - Syntax highlighting for code snippets
- **`markdown`** - Markdown formatting for rich text

### Format Usage

```c
#include "privatebinapi.h"

// Plain text format
create_paste(server, content, password, expiration, "plaintext", 0, 0, &url, &token);

// Syntax highlighting for code
create_paste(server, code_content, password, expiration, "syntaxhighlighting", 0, 0, &url, &token);

// Markdown formatting
create_paste(server, markdown_content, password, expiration, "markdown", 0, 0, &url, &token);
```

## File Upload Functionality

The library includes an `upload_file` function that allows you to securely upload files to PrivateBin servers:

```c
int upload_file(const char* server_url, const char* file_path,
                const char* password, const char* expiration,
                int burn_after_reading, int open_discussion,
                char** paste_url, char** delete_token);
```

### File Upload Parameters

- **`server_url`**: The URL of the PrivateBin server
- **`file_path`**: The path to the file to upload
- **`password`**: Optional password for the paste (can be NULL)
- **`expiration`**: Expiration time ("5min", "10min", "1hour", "1day", "1week", "1month", "1year", "never")
- **`burn_after_reading`**: 1 for "burn after reading", 0 for "keep"
- **`open_discussion`**: 1 for allow discussion, 0 for disable discussion
- **`paste_url`**: Output parameter for the URL of the created paste
- **`delete_token`**: Output parameter for the deletion token

### File Upload Features

- **Binary Files**: Support for all file types
- **Size Limitation**: Maximum file size 100MB
- **Secure Encryption**: Same cryptography as text pastes
- **Compression**: Automatic zlib compression before encryption
- **Metadata**: File name, size, and type are added to metadata
- **Key Derivation**: PBKDF2-HMAC-SHA256 with 100,000 iterations

### How File Upload Works

1. **File Reading**: The file is read in binary mode
2. **Size Check**: Maximum file size is limited to 100MB
3. **Encryption**: 
   - Generation of a random 32-byte key
   - File compression with zlib
   - Encryption with AES-256-GCM
   - Key derivation with PBKDF2-HMAC-SHA256 (100,000 iterations)
4. **Metadata**: File name, size, and type are added to metadata
5. **Upload**: Encrypted data is sent to the PrivateBin server
6. **URL Generation**: The URL is created with the Base58-encoded key

## Build Scripts

The project includes several build scripts in the `scripts/` directory for different platforms and use cases.

### Windows Build Scripts

#### PowerShell Build (Recommended)
**File:** `scripts/build_windows.ps1`  
**Requirements:** PowerShell, Visual Studio 2022 Build Tools (C++), vcpkg (will be bootstrapped), Git

```powershell
# Run from project root
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1
```

This script:
- Automatically bootstraps vcpkg if not present
- Configures CMake with Visual Studio 2022 generator
- Builds the project in Release configuration
- Creates a Windows distribution package with all artifacts

#### Command Line Build
**File:** `scripts/build_thinkpad.bat`  
**Requirements:** Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg

```cmd
# Run from project root
scripts\build_thinkpad.bat
```

This script:
- Automatically detects and initializes Visual Studio environment
- Handles vcpkg bootstrapping
- Configures CMake with proper toolchain
- Builds the project using MSVC compiler

### Linux Build Scripts

#### Automated Build Script
**File:** `scripts/build.sh`  
**Requirements:** CMake, C++17 compiler, system packages

```bash
# Make executable and run from project root
chmod +x scripts/build.sh
./scripts/build.sh
```

This script:
- Automatically detects and installs required dependencies
- Configures CMake with Unix Makefiles
- Builds the project in Release configuration

#### Manual Linux Build (Recommended)
**Requirements:** CMake 3.10+, GCC/Clang with C++17 support, system packages

```bash
# Install dependencies (Fedora/RHEL/CentOS)
sudo dnf install cmake gcc-c++ libcurl-devel cryptopp-devel json-devel

# Install dependencies (Ubuntu/Debian)
sudo apt install cmake g++ libcurl4-openssl-dev libcrypto++-dev nlohmann-json3-dev

# Build the project
mkdir build
cd build
cmake ..
make -j$(nproc)

# Run tests
ctest --verbose

# Run example
./example/example
```

**Linux Dependencies:**
- **libcurl-devel** - HTTP client library
- **cryptopp-devel** - Cryptographic library
- **json-devel** - JSON parsing library
- **cmake** - Build system
- **gcc-c++** - C++17 compiler

### macOS Build Script
**File:** `scripts/build.sh`  
**Requirements:** CMake, C++17 compiler, Homebrew packages

```bash
# Install dependencies via Homebrew
brew install cmake cryptopp nlohmann-json curl

# Make executable and run from project root
chmod +x scripts/build.sh
./scripts/build.sh
```

This script:
- Bootstraps vcpkg if not present
- Configures CMake with Unix Makefiles
- Builds the project in Release configuration

## Installation

### Dependencies

- CMake 3.10+
- C++17 compatible compiler
- **Windows:** Crypto++ and nlohmann/json (via vcpkg)
- **Linux:** libcurl, cryptopp, and nlohmann-json (via system packages)
- **macOS:** libcurl, cryptopp, and nlohmann/json (via Homebrew)

### Compilation

#### Windows (PowerShell) - Build via scripts/build_windows.ps1
```powershell
# Requires: PowerShell, Visual Studio 2022 Build Tools (C++), vcpkg (will be bootstrapped), Git
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1
```

#### Windows (Command Line) - Build via scripts/build_thinkpad.bat
```cmd
# Requires: Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg
scripts\build_thinkpad.bat
```

#### Linux - Automated Build via scripts/build.sh
```bash
# Requires: CMake, C++17 compiler, system packages
chmod +x scripts/build.sh
./scripts/build.sh
```

#### Linux - Manual Build (Recommended)
```bash
# Install dependencies (Fedora/RHEL/CentOS)
sudo dnf install cmake gcc-c++ libcurl-devel cryptopp-devel json-devel

# Install dependencies (Ubuntu/Debian)
sudo apt install cmake g++ libcurl4-openssl-dev libcrypto++-dev nlohmann-json3-dev

# Build the project
mkdir build
cd build
cmake ..
make -j$(nproc)

# Run tests and examples
ctest --verbose
./example/example
```

#### macOS - Build via scripts/build.sh
```bash
# Install dependencies via Homebrew
brew install cmake cryptopp nlohmann-json curl

# Requires: CMake, C++17 compiler, Homebrew packages
chmod +x scripts/build.sh
./scripts/build.sh
```

#### Manual Build (All Platforms)
```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

**Note:** The manual build method requires you to have all dependencies properly configured. For most users, the platform-specific build scripts are recommended.

**Linux Compatibility:** The project has been tested and successfully builds on Fedora Linux with system packages. It automatically detects the platform and uses appropriate dependency resolution methods (vcpkg for Windows, system packages for Linux/macOS).

## Usage

### Text Paste with Formatting

The library supports multiple text formats as defined in the [PrivateBin API v1.3](https://github.com/PrivateBin/PrivateBin/wiki/API):

#### Available Formats

- **`plaintext`** - Plain text (default)
- **`syntaxhighlighting`** - Syntax highlighting for code
- **`markdown`** - Markdown formatting

#### Basic Example

```c
#include "privatebinapi.h"

char* paste_url = nullptr;
char* delete_token = nullptr;

int result = create_paste(
    "https://privatebin.net",
    "Hello, World!",
    NULL,           // no password
    "1day",         // expiration
    "plaintext",    // format
    0,              // don't burn after reading
    0               // no discussion
);

if (result == 0) {
    printf("Paste created: %s\n", paste_url);
    free_string(paste_url);
    free_string(delete_token);
}
```

#### Syntax Highlighting Example

```c
const char* code_content = R"(
#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}
)";

int result = create_paste(
    "https://privatebin.net",
    code_content,
    NULL,                    // no password
    "1week",                 // expiration
    "syntaxhighlighting",    // syntax highlighting format
    0,                       // don't burn after reading
    0                        // no discussion
);
```

#### Markdown Example

```c
const char* markdown_content = R"(
# Header

This is **bold** and *italic* text.

## Code Block
```cpp
int x = 42;
std::cout << x << std::endl;
```

> This is a blockquote.
)";

int result = create_paste(
    "https://privatebin.net",
    markdown_content,
    NULL,           // no password
    "1month",       // expiration
    "markdown",     // markdown format
    0,              // don't burn after reading
    0               // no discussion
);
```

### File Upload

```c
char* paste_url = nullptr;
char* delete_token = nullptr;

int result = upload_file(
    "https://privatebin.net",
    "/path/to/file.txt",
    "mypassword",   // optional password
    "1week",        // expiration
    0,              // don't burn after reading
    0               // no discussion
);

if (result == 0) {
    printf("Successfully uploaded!\n");
    printf("URL: %s\n", paste_url);
    printf("Delete Token: %s\n", delete_token);
    
    // Free memory
    free_string(paste_url);
    free_string(delete_token);
}
```

## Examples

The library contains a comprehensive example program that demonstrates both text paste and file upload functionality:

### Running the Example

```bash
# Run basic example (tests all text formats)
./example

# Upload a file
./example --upload https://privatebin.net test.txt

# Upload with password and expiration
./example --upload https://privatebin.net test.txt mypassword 1week

# Upload with all options
./example --upload https://privatebin.net test.txt mypassword 1day 1 0
```

The basic example now demonstrates:
- **Plaintext format** - Simple text pastes
- **Syntax highlighting format** - Code with syntax highlighting
- **Markdown format** - Rich text formatting
- **Interactive format selection** - Shows available options

### Example Output

The example program demonstrates:
- Creating text pastes
- Retrieving paste content
- Deleting pastes
- File upload with various options
- Error handling for all operations

## API Reference

### Functions

- `create_paste()` - Creates a text paste with optional formatting
- `upload_file()` - Uploads a file
- `get_paste()` - Retrieves a paste
- `delete_paste()` - Deletes a paste
- `free_string()` - Frees memory

### Format Support

The `create_paste()` function supports the following formats as defined in the [PrivateBin API v1.3](https://github.com/PrivateBin/PrivateBin/wiki/API):

- **`plaintext`** - Default format for simple text
- **`syntaxhighlighting`** - Syntax highlighting for code snippets
- **`markdown`** - Markdown formatting for rich text

### Error Codes

- `0` - Success
- `1` - Network error
- `2` - Cryptographic error
- `3` - Invalid input (e.g., file not found or too large)
- `4` - Server error
- `5` - JSON parsing error

## Security

- **Client-Side Encryption**: All data is encrypted before upload
- **AES-256-GCM**: Modern encryption with authentication
- **PBKDF2**: Secure key derivation with 100,000 iterations
- **Random Keys**: Each paste receives a unique key
- **No Server Logs**: Server cannot read encrypted data
- **File Compression**: Automatic zlib compression before encryption
- **Binary Support**: All file types are treated as encrypted binary data

## Limitations

- **File Size**: Maximum file size is 100MB
- **File Type**: All file types are treated as binary data
- **Server Compatibility**: Works with PrivateBin v1.3+ servers
- **Format**: Files are always treated as "plaintext" (even if they are binary data)

## Error Handling

The library returns detailed error codes and logs errors to the console. Common errors:

- **File not found**: Check the file path
- **File too large**: Reduce file size or split it up
- **Network error**: Check server URL and internet connection
- **Server error**: The server might be temporarily unavailable

## License

See [LICENSE](LICENSE) for details.

## Changelog

### v0.1.1.6 (2025-08-28)
- **NEW**: Full Linux compatibility with system packages
- **NEW**: Automatic platform detection (Windows: vcpkg, Linux: system packages)
- **IMPROVED**: Enhanced Linux build documentation and instructions
- **IMPROVED**: Better dependency management for cross-platform builds
- **FIXED**: CMakeLists.txt now works on both Windows and Linux without manual configuration

### v0.1.1.5 (2025-08-28)
- **NEW**: Enhanced text format support (plaintext, syntax highlighting, markdown)
- **NEW**: Comprehensive format testing in examples and integration tests
- **IMPROVED**: Better API documentation with format examples
- **IMPROVED**: Enhanced test coverage for all supported formats

### v0.1.1.4 (2025-08-28)
- **NEW**: Automated release creation script (`scripts/create_release.ps1`)
- **NEW**: Build scripts moved to `scripts/` directory for better organization
- **IMPROVED**: Enhanced build documentation with platform-specific instructions
- **IMPROVED**: Better project structure and organization

### v0.1.1.1 (2025-08-28)
- **NEW**: Combined example program with both text and file upload functionality
- **IMPROVED**: Unified command-line interface for examples
- **IMPROVED**: Better error handling and user experience

### v0.1.1 (2025-08-28)
- **NEW**: File upload functionality added
- **NEW**: `upload_file()` function implemented
- **NEW**: Comprehensive example program
- **NEW**: Extended documentation for file upload
- **IMPROVED**: Better error handling
- **IMPROVED**: Cross-platform compatibility