feat(lib): initialize libnextcloud C++17 library scaffolding (#25)

shared/include/nextcloud/types.hpp

@@ -0,0 +1,176 @@
+#ifndef NEXTCLOUD_TYPES_HPP
+#define NEXTCLOUD_TYPES_HPP
+
+#include <string>
+#include <cstdint>
+#include <ctime>
+
+namespace nextcloud {
+
+/**
+ * @brief Error codes for Nextcloud operations
+ */
+enum class NextcloudError {
+    Success = 0,
+    
+    // Network errors
+    NetworkError,
+    ConnectionFailed,
+    Timeout,
+    SSLError,
+    
+    // Authentication errors
+    AuthenticationFailed,
+    InvalidCredentials,
+    Unauthorized,
+    
+    // Server errors
+    ServerError,
+    ServiceUnavailable,
+    InsufficientStorage,
+    
+    // File/path errors
+    FileNotFound,
+    PathNotFound,
+    InvalidPath,
+    FileAlreadyExists,
+    PathAlreadyExists,
+    
+    // Operation errors
+    OperationFailed,
+    OperationCancelled,
+    InvalidOperation,
+    
+    // Parsing/format errors
+    ParseError,
+    InvalidResponse,
+    UnsupportedFormat,
+    
+    // Configuration errors
+    InvalidConfiguration,
+    MissingConfiguration,
+    
+    // Unknown
+    Unknown
+};
+
+/**
+ * @brief Convert error code to human-readable string
+ * @param error The error code
+ * @return String description of the error
+ */
+inline const char* errorToString(NextcloudError error) {
+    switch (error) {
+        case NextcloudError::Success: return "Success";
+        case NextcloudError::NetworkError: return "Network error";
+        case NextcloudError::ConnectionFailed: return "Connection failed";
+        case NextcloudError::Timeout: return "Operation timed out";
+        case NextcloudError::SSLError: return "SSL/TLS error";
+        case NextcloudError::AuthenticationFailed: return "Authentication failed";
+        case NextcloudError::InvalidCredentials: return "Invalid credentials";
+        case NextcloudError::Unauthorized: return "Unauthorized";
+        case NextcloudError::ServerError: return "Server error";
+        case NextcloudError::ServiceUnavailable: return "Service unavailable";
+        case NextcloudError::InsufficientStorage: return "Insufficient storage";
+        case NextcloudError::FileNotFound: return "File not found";
+        case NextcloudError::PathNotFound: return "Path not found";
+        case NextcloudError::InvalidPath: return "Invalid path";
+        case NextcloudError::FileAlreadyExists: return "File already exists";
+        case NextcloudError::PathAlreadyExists: return "Path already exists";
+        case NextcloudError::OperationFailed: return "Operation failed";
+        case NextcloudError::OperationCancelled: return "Operation cancelled";
+        case NextcloudError::InvalidOperation: return "Invalid operation";
+        case NextcloudError::ParseError: return "Parse error";
+        case NextcloudError::InvalidResponse: return "Invalid response";
+        case NextcloudError::UnsupportedFormat: return "Unsupported format";
+        case NextcloudError::InvalidConfiguration: return "Invalid configuration";
+        case NextcloudError::MissingConfiguration: return "Missing configuration";
+        case NextcloudError::Unknown: return "Unknown error";
+        default: return "Unrecognized error";
+    }
+}
+
+/**
+ * @brief Result type for operations that can fail
+ * @tparam T The success value type
+ */
+template<typename T>
+struct Result {
+    NextcloudError error;
+    T value;
+    
+    /**
+     * @brief Check if the operation was successful
+     * @return True if no error occurred
+     */
+    bool isSuccess() const { return error == NextcloudError::Success; }
+    
+    /**
+     * @brief Check if an error occurred
+     * @return True if an error occurred
+     */
+    bool isError() const { return error != NextcloudError::Success; }
+    
+    /**
+     * @brief Get error message
+     * @return Human-readable error description
+     */
+    const char* errorMessage() const { return errorToString(error); }
+};
+
+/**
+ * @brief Upload progress information
+ */
+struct UploadProgress {
+    std::string filename;        ///< Name of file being uploaded
+    uint64_t bytesUploaded;      ///< Number of bytes uploaded so far
+    uint64_t totalBytes;         ///< Total file size in bytes
+    float percentComplete;       ///< Completion percentage (0.0 - 100.0)
+    float bytesPerSecond;        ///< Current transfer speed
+    int secondsRemaining;        ///< Estimated seconds remaining (-1 if unknown)
+};
+
+/**
+ * @brief Information about a file or directory
+ */
+struct FileInfo {
+    std::string name;            ///< File or directory name
+    std::string path;            ///< Full path on server
+    bool isDirectory;            ///< True if this is a directory
+    uint64_t size;               ///< File size in bytes (0 for directories)
+    std::time_t modifiedTime;    ///< Last modification time (Unix timestamp)
+    std::string contentType;     ///< MIME type (e.g., "image/png")
+    std::string etag;            ///< ETag for change detection
+};
+
+/**
+ * @brief Information about a favorite or recent folder
+ */
+struct FolderInfo {
+    std::string path;            ///< Full path on server
+    std::string displayName;     ///< User-friendly name
+    std::time_t lastUsed;        ///< Last access time (Unix timestamp)
+    bool isFavorite;             ///< True if marked as favorite
+};
+
+/**
+ * @brief HTTP response information
+ */
+struct HttpResponse {
+    int statusCode;              ///< HTTP status code (e.g., 200, 404)
+    std::string body;            ///< Response body
+    std::string contentType;     ///< Content-Type header value
+    NextcloudError error;        ///< Error code if request failed
+    
+    /**
+     * @brief Check if response indicates success (2xx status code)
+     * @return True if status code is 200-299
+     */
+    bool isSuccess() const { 
+        return statusCode >= 200 && statusCode < 300 && error == NextcloudError::Success; 
+    }
+};
+
+} // namespace nextcloud
+
+#endif // NEXTCLOUD_TYPES_HPP

shared/include/nextcloud/version.hpp

@@ -0,0 +1,57 @@
+#ifndef NEXTCLOUD_VERSION_HPP
+#define NEXTCLOUD_VERSION_HPP
+
+#include <string>
+
+namespace nextcloud {
+
+// Semantic versioning
+constexpr int VERSION_MAJOR = 0;
+constexpr int VERSION_MINOR = 1;
+constexpr int VERSION_PATCH = 0;
+
+// Build metadata
+constexpr const char* VERSION_STRING = "0.1.0";
+constexpr const char* BUILD_DATE = __DATE__;
+constexpr const char* BUILD_TIME = __TIME__;
+
+/**
+ * @brief Get the library version as a string
+ * @return Version string in format "MAJOR.MINOR.PATCH"
+ */
+inline std::string getVersionString() {
+    return VERSION_STRING;
+}
+
+/**
+ * @brief Get the library version components
+ * @param major Output parameter for major version
+ * @param minor Output parameter for minor version
+ * @param patch Output parameter for patch version
+ */
+inline void getVersion(int& major, int& minor, int& patch) {
+    major = VERSION_MAJOR;
+    minor = VERSION_MINOR;
+    patch = VERSION_PATCH;
+}
+
+/**
+ * @brief Check if the library version is at least the specified version
+ * @param major Required major version
+ * @param minor Required minor version
+ * @param patch Required patch version
+ * @return True if current version >= required version
+ */
+inline bool isVersionAtLeast(int major, int minor, int patch) {
+    if (VERSION_MAJOR > major) return true;
+    if (VERSION_MAJOR < major) return false;
+    
+    if (VERSION_MINOR > minor) return true;
+    if (VERSION_MINOR < minor) return false;
+    
+    return VERSION_PATCH >= patch;
+}
+
+} // namespace nextcloud
+
+#endif // NEXTCLOUD_VERSION_HPP