# libnextcloud

Cross-platform C++17 library for Nextcloud connectivity on embedded devices and homebrew platforms.

## Overview

`libnextcloud` provides a clean, modern C++ API for interacting with Nextcloud servers. It's designed to work on resource-constrained devices like game console homebrew (Nintendo 3DS, Switch, Wii U) while also supporting desktop platforms.

**Status**: 🚧 In Development - Scaffolding complete, components being implemented

## Features (Planned)

- ✅ **Version Management**: Semantic versioning with compile-time and runtime queries
- ✅ **Type System**: Comprehensive error codes and data structures
- 🚧 **WebDAV Client**: HTTP/HTTPS communication with Nextcloud WebDAV API
- 🚧 **Authentication**: Basic Auth (OAuth2 planned)
- 🚧 **File Upload**: Streaming uploads with chunking and progress tracking
- 🚧 **Folder Management**: List, create, navigate remote folders
- 🚧 **Favorites & Recent**: Persistent user preferences

## Requirements

### Build Tools
- **CMake** 3.15 or later
- **C++17 compiler**: GCC 7+, Clang 5+, MSVC 2017+

### Dependencies

**Required** (when implementation complete):
- libcurl 7.68+
- mbedTLS 2.16+
- tinyxml2 9.0+

**Testing**:
- Google Test 1.11+

**Header-Only**:
- nlohmann/json 3.10+ (for configuration, future)

### Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| Linux | ✅ Development | Primary development platform |
| Nintendo 3DS | ✅ Planned | Via devkitARM in container |
| Nintendo Switch | 🔜 Planned | |
| Wii U | 🔜 Planned | |
| PlayStation Vita | 🔜 Planned | |
| Windows | 🔜 Planned | |
| macOS | 🔜 Planned | |

## Quick Start

### Building

```bash
# Configure (modern CMake style)
cmake -S . -B build

# Build
cmake --build build

# Run tests
cmake --build build --target test
# or with CTest for detailed output:
# ctest --test-dir build --output-on-failure
```

### Using in Your Project

#### CMake

```cmake
find_package(nextcloud REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app nextcloud::nextcloud)
```

#### pkg-config

```bash
g++ -std=c++17 main.cpp $(pkg-config --cflags --libs libnextcloud)
```

### Basic Usage

```cpp
#include <nextcloud/version.hpp>
#include <nextcloud/types.hpp>
#include <iostream>

int main() {
    // Get library version
    std::cout << "libnextcloud v" << nextcloud::getVersionString() << std::endl;
    
    // Check version compatibility
    if (nextcloud::isVersionAtLeast(0, 1, 0)) {
        std::cout << "Version is compatible!" << std::endl;
    }
    
    // Use error types
    nextcloud::NextcloudError error = nextcloud::NextcloudError::Success;
    std::cout << "Status: " << nextcloud::errorToString(error) << std::endl;
    
    return 0;
}
```

## Project Structure

```
shared/
├── CMakeLists.txt              # Build configuration
├── README.md                   # This file
├── libnextcloud.pc.in          # pkg-config template
├── nextcloudConfig.cmake.in    # CMake config template
├── include/
│   └── nextcloud/
│       ├── version.hpp         # Version information
│       ├── types.hpp           # Common types and errors
│       ├── webdav_client.hpp   # (Coming soon)
│       ├── auth.hpp            # (Coming soon)
│       ├── upload_manager.hpp  # (Coming soon)
│       ├── folder_manager.hpp  # (Coming soon)
│       └── config.hpp          # (Coming soon)
├── src/                        # Implementation files (future)
├── tests/
│   ├── CMakeLists.txt
│   └── smoke_test.cpp          # Basic tests
├── examples/                   # Usage examples (future)
└── docs/                       # Documentation (future)
```

## Building for Platforms

### Linux (Development)

```bash
mkdir build && cd build
cmake ..
make
make test
```

### Nintendo 3DS (Container)

```bash
# From project root
podman run --rm -v .:/project:z tomusan/devkitarm-3ds:latest \
  bash -c "cd /project/shared && mkdir -p build && cd build && cmake .. && make"
```

## API Documentation

### Version Information

```cpp
#include <nextcloud/version.hpp>

// Constants
nextcloud::VERSION_MAJOR        // 0
nextcloud::VERSION_MINOR        // 1
nextcloud::VERSION_PATCH        // 0
nextcloud::VERSION_STRING       // "0.1.0"

// Functions
std::string getVersionString();
void getVersion(int& major, int& minor, int& patch);
bool isVersionAtLeast(int major, int minor, int patch);
```

### Error Handling

```cpp
#include <nextcloud/types.hpp>

// Error codes
enum class NextcloudError {
    Success,
    NetworkError,
    AuthenticationFailed,
    ServerError,
    FileNotFound,
    // ... more error codes
};

// Convert to string
const char* errorToString(NextcloudError error);

// Result type
nextcloud::Result<int> result;
if (result.isSuccess()) {
    // Use result.value
} else {
    std::cerr << result.errorMessage() << std::endl;
}
```

### Data Structures

```cpp
// Upload progress
struct UploadProgress {
    std::string filename;
    uint64_t bytesUploaded;
    uint64_t totalBytes;
    float percentComplete;
    float bytesPerSecond;
    int secondsRemaining;
};

// File information
struct FileInfo {
    std::string name;
    std::string path;
    bool isDirectory;
    uint64_t size;
    std::time_t modifiedTime;
    std::string contentType;
};

// Folder information
struct FolderInfo {
    std::string path;
    std::string displayName;
    std::time_t lastUsed;
    bool isFavorite;
};
```

## Testing

```bash
# Run all tests
cd build
ctest --output-on-failure

# Or use the custom target
make run_tests

# Run specific test
./tests/smoke_test
```

## Development Status

- ✅ **Phase 1: Scaffolding** - Complete
  - Directory structure
  - CMake build system
  - Version and types headers
  - Google Test integration
  - Basic smoke tests

- 🚧 **Phase 2: WebDAV Client** - Not started
  - Issue #8

- 🚧 **Phase 3: Authentication** - Not started
  - Issue #9

- 🚧 **Phase 4: Upload Manager** - Not started
  - Issue #10

- 🚧 **Phase 5: Folder Management** - Not started
  - Issue #11

- 🚧 **Phase 6: Favorites & Recent** - Not started
  - Issue #12

- 🚧 **Phase 7: Testing & Docs** - Not started
  - Issue #13

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) in the project root.

## License

[License TBD - to be determined]

## Related Documentation

- [Project Plan](../.plans/CreateLibNextcloud.md)
- [Issue #25](https://git.tomusan.com/maj/nextcloud-share/issues/25) - Initialize libnextcloud

---

**Note**: This library is in active development. The API is subject to change until version 1.0.0.