|
|
@@ -0,0 +1,315 @@
|
|
|
+# QDR Temporary Shared Storage - .NET Client
|
|
|
+
|
|
|
+A comprehensive .NET client library and console application for uploading and managing files through the QDR Temporary Shared Storage WordPress plugin REST API.
|
|
|
+
|
|
|
+## Overview
|
|
|
+
|
|
|
+This project provides:
|
|
|
+- **REST Client Library** (`qdr.app.tss.client`) - Low-level HTTP client for API communication
|
|
|
+- **File Upload Service** - High-level service with chunked upload support and progress reporting
|
|
|
+- **Console Application** (`qdr.app.tss.client.console`) - Command-line tool for file uploads
|
|
|
+- **Complete DTO Models** - Strongly-typed request/response objects
|
|
|
+
|
|
|
+## Features
|
|
|
+
|
|
|
+- ✅ **Chunked File Uploads** - Efficient handling of large files with configurable chunk sizes
|
|
|
+- ✅ **Progress Reporting** - Real-time upload progress feedback
|
|
|
+- ✅ **Authentication** - API key-based authentication
|
|
|
+- ✅ **Error Handling** - Comprehensive error handling and user-friendly messages
|
|
|
+- ✅ **File Management** - Full CRUD operations for shared files
|
|
|
+- ✅ **Password Protection** - Secure file sharing with password requirements
|
|
|
+- ✅ **Expiration Dates** - Configurable file availability periods
|
|
|
+- ✅ **Reference Codes** - Custom reference values for file identification
|
|
|
+
|
|
|
+## Requirements
|
|
|
+
|
|
|
+- .NET 9.0 or later
|
|
|
+- QDR Temporary Shared Storage WordPress plugin installed and configured
|
|
|
+- Valid API key from the WordPress plugin
|
|
|
+
|
|
|
+## Installation
|
|
|
+
|
|
|
+### NuGet Package
|
|
|
+```bash
|
|
|
+# Install the client library
|
|
|
+dotnet add package qdr.app.tss.client
|
|
|
+```
|
|
|
+
|
|
|
+### Build from Source
|
|
|
+```bash
|
|
|
+git clone <repository-url>
|
|
|
+cd qdr.app.tss.client
|
|
|
+dotnet build
|
|
|
+```
|
|
|
+
|
|
|
+## Quick Start
|
|
|
+
|
|
|
+### Using the Console Application
|
|
|
+
|
|
|
+```bash
|
|
|
+# Upload a file with all options
|
|
|
+qdr.app.tss.client.console.exe upload \
|
|
|
+ -url:"https://your-wordpress-site.com/" \
|
|
|
+ -apiKey:"your-api-key-here" \
|
|
|
+ -file:"path/to/your/file.pdf" \
|
|
|
+ -pwd:"download-password" \
|
|
|
+ -descr:"File description" \
|
|
|
+ -msg:"Message for downloaders" \
|
|
|
+ -ref:"REF001" \
|
|
|
+ -activeFrom:"2025-05-22 10:00:00" \
|
|
|
+ -activeTo:"2025-06-22 10:00:00" \
|
|
|
+ -chunkSize:1048576
|
|
|
+```
|
|
|
+
|
|
|
+### Using the .NET Library
|
|
|
+
|
|
|
+```csharp
|
|
|
+using Quadarax.Application.TemporarySharedStorage.Client;
|
|
|
+using Quadarax.Application.TemporarySharedStorage.Client.Services;
|
|
|
+using Quadarax.Application.TemporarySharedStorage.Client.Dtos.Request;
|
|
|
+
|
|
|
+// Initialize the upload service
|
|
|
+var logger = new ConsoleLogger(LogSeverityEnum.Info, LogSeverityEnum.Debug, LogSeverityEnum.Error);
|
|
|
+var uploadService = new FileUploadService("https://your-site.com", "your-api-key", logger);
|
|
|
+
|
|
|
+// Create upload request
|
|
|
+var request = new UploadFileRequest
|
|
|
+{
|
|
|
+ FilePath = @"C:\path\to\file.pdf",
|
|
|
+ Description = "Important document",
|
|
|
+ Password = "secure123",
|
|
|
+ Message = "Please review this document",
|
|
|
+ Reference = "DOC001",
|
|
|
+ ActiveFrom = DateTime.Now,
|
|
|
+ ActiveTo = DateTime.Now.AddDays(30),
|
|
|
+ ChunkSize = 1048576 // 1MB chunks
|
|
|
+};
|
|
|
+
|
|
|
+// Upload the file
|
|
|
+await uploadService.UploadFileAsync(request);
|
|
|
+```
|
|
|
+
|
|
|
+## Console Application Usage
|
|
|
+
|
|
|
+### Command Line Arguments
|
|
|
+
|
|
|
+| Argument | Required | Description | Example |
|
|
|
+|----------|----------|-------------|---------|
|
|
|
+| `-url` | ✅ | WordPress site URL | `https://example.com/` |
|
|
|
+| `-apiKey` | ✅ | API key from plugin settings | `riyeVPRvz9QF1YmrhdSz9rgiVzhy3mSb` |
|
|
|
+| `-file` | ✅ | Path to file to upload | `C:\documents\file.pdf` |
|
|
|
+| `-pwd` | ✅ | Download password | `securePassword123` |
|
|
|
+| `-activeFrom` | ✅ | Start date/time | `"2025-05-22 10:00:00"` |
|
|
|
+| `-activeTo` | ✅ | End date/time | `"2025-06-22 10:00:00"` |
|
|
|
+| `-msg` | ✅ | Message for downloaders | `"Please review"` |
|
|
|
+| `-ref` | ✅ | Reference code | `REF001` |
|
|
|
+| `-descr` | ❌ | File description | `"Important document"` |
|
|
|
+| `-chunkSize` | ❌ | Chunk size in bytes | `1048576` (default: 1MB) |
|
|
|
+
|
|
|
+### Example Commands
|
|
|
+
|
|
|
+```bash
|
|
|
+# Minimal upload
|
|
|
+upload -url:"https://site.com/" -apiKey:"key123" -file:"doc.pdf" -pwd:"pass" -activeFrom:"2025-05-22" -activeTo:"2025-06-22" -msg:"Review please" -ref:"DOC01"
|
|
|
+
|
|
|
+# Upload with custom chunk size (5MB)
|
|
|
+upload -url:"https://site.com/" -apiKey:"key123" -file:"large-file.zip" -pwd:"pass" -activeFrom:"2025-05-22" -activeTo:"2025-06-22" -msg:"Download when ready" -ref:"ZIP01" -chunkSize:5242880
|
|
|
+```
|
|
|
+
|
|
|
+## .NET Library Usage
|
|
|
+
|
|
|
+### Direct REST Client Usage
|
|
|
+
|
|
|
+```csharp
|
|
|
+using var restClient = new QdrTssRestClient("https://your-site.com", "your-api-key");
|
|
|
+
|
|
|
+// Initialize upload
|
|
|
+var initRequest = new InitUploadRequest
|
|
|
+{
|
|
|
+ OriginalFileName = "document.pdf",
|
|
|
+ FileSize = fileInfo.Length
|
|
|
+};
|
|
|
+var initResponse = await restClient.InitializeUploadAsync(initRequest);
|
|
|
+
|
|
|
+// Upload chunks (example for single chunk)
|
|
|
+byte[] chunkData = File.ReadAllBytes("document.pdf");
|
|
|
+var chunkResponse = await restClient.UploadChunkAsync(
|
|
|
+ initResponse.UploadId,
|
|
|
+ 0, // chunk index
|
|
|
+ 1, // total chunks
|
|
|
+ chunkData
|
|
|
+);
|
|
|
+
|
|
|
+// Finalize upload
|
|
|
+var finalizeRequest = new FinalizeUploadRequest
|
|
|
+{
|
|
|
+ UploadId = initResponse.UploadId,
|
|
|
+ TotalChunks = 1,
|
|
|
+ OriginalFileName = "document.pdf",
|
|
|
+ Description = "Important document",
|
|
|
+ Password = "secure123",
|
|
|
+ ActiveFrom = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
|
|
|
+ ActiveTo = DateTime.Now.AddDays(30).ToString("yyyy-MM-dd HH:mm:ss")
|
|
|
+};
|
|
|
+var finalResult = await restClient.FinalizeUploadAsync(finalizeRequest);
|
|
|
+
|
|
|
+Console.WriteLine($"File uploaded! ID: {finalResult.FileId}");
|
|
|
+Console.WriteLine($"Download URL: {finalResult.Permalink}");
|
|
|
+```
|
|
|
+
|
|
|
+### File Management Operations
|
|
|
+
|
|
|
+```csharp
|
|
|
+using var restClient = new QdrTssRestClient("https://your-site.com", "your-api-key");
|
|
|
+
|
|
|
+// Get file details
|
|
|
+var fileDetails = await restClient.GetMediaAsync("file-id-123");
|
|
|
+
|
|
|
+// Update file properties
|
|
|
+var updateRequest = new UpdateMediaRequest
|
|
|
+{
|
|
|
+ Message = "Updated message",
|
|
|
+ Description = "Updated description",
|
|
|
+ ActiveTo = DateTime.Now.AddDays(60).ToString("yyyy-MM-dd HH:mm:ss")
|
|
|
+};
|
|
|
+await restClient.UpdateMediaAsync("file-id-123", updateRequest);
|
|
|
+
|
|
|
+// List files with filtering
|
|
|
+var files = await restClient.GetMediaListAsync(
|
|
|
+ page: 1,
|
|
|
+ perPage: 20,
|
|
|
+ orderBy: "upload_date",
|
|
|
+ order: "DESC",
|
|
|
+ originalFileName: "*.pdf"
|
|
|
+);
|
|
|
+
|
|
|
+// Delete file
|
|
|
+await restClient.DeleteMediaAsync("file-id-123");
|
|
|
+```
|
|
|
+
|
|
|
+## Configuration
|
|
|
+
|
|
|
+### API Key Setup
|
|
|
+1. Install the QDR Temporary Shared Storage plugin in WordPress
|
|
|
+2. Navigate to **Settings > Shared Storage**
|
|
|
+3. Generate or copy your API key
|
|
|
+4. Use the key in your application
|
|
|
+
|
|
|
+### Upload Limits
|
|
|
+- Maximum file size depends on your WordPress/server configuration
|
|
|
+- Chunked uploads help bypass PHP upload limits
|
|
|
+- Recommended chunk size: 1-5MB for optimal performance
|
|
|
+
|
|
|
+## Error Handling
|
|
|
+
|
|
|
+The library provides comprehensive error handling:
|
|
|
+
|
|
|
+```csharp
|
|
|
+try
|
|
|
+{
|
|
|
+ await uploadService.UploadFileAsync(request);
|
|
|
+}
|
|
|
+catch (FileNotFoundException ex)
|
|
|
+{
|
|
|
+ Console.WriteLine($"File not found: {ex.Message}");
|
|
|
+}
|
|
|
+catch (ArgumentException ex)
|
|
|
+{
|
|
|
+ Console.WriteLine($"Invalid argument: {ex.Message}");
|
|
|
+}
|
|
|
+catch (HttpRequestException ex)
|
|
|
+{
|
|
|
+ Console.WriteLine($"Network error: {ex.Message}");
|
|
|
+}
|
|
|
+catch (Exception ex)
|
|
|
+{
|
|
|
+ Console.WriteLine($"Unexpected error: {ex.Message}");
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## Build Scripts
|
|
|
+
|
|
|
+The project includes convenient build scripts:
|
|
|
+
|
|
|
+- `buildD.cmd` - Debug build
|
|
|
+- `buildR.cmd` - Release build
|
|
|
+- `publishD.cmd` - Debug build and publish to local NuGet
|
|
|
+- `publishR.cmd` - Release build and publish to local NuGet
|
|
|
+- `bootstrap.cmd` - Environment setup
|
|
|
+
|
|
|
+## Project Structure
|
|
|
+
|
|
|
+```
|
|
|
+qdr.app.tss.client/
|
|
|
+├── qdr.app.tss.client/ # Core library
|
|
|
+│ ├── Dtos/ # Data transfer objects
|
|
|
+│ │ ├── Request/ # Request models
|
|
|
+│ │ └── Response/ # Response models
|
|
|
+│ ├── Services/ # High-level services
|
|
|
+│ └── TssRestClient.cs # Low-level REST client
|
|
|
+├── qdr.app.tss.client.console/ # Console application
|
|
|
+│ ├── Commands/ # Command implementations
|
|
|
+│ └── Program.cs # Entry point
|
|
|
+└── Documentation/
|
|
|
+ └── rest-api-docs.md # Complete API documentation
|
|
|
+```
|
|
|
+
|
|
|
+## Dependencies
|
|
|
+
|
|
|
+- **qdr.fnd.core** (0.0.8-alpha) - Foundation library
|
|
|
+- **qdr.fnd.core.qconsole** (0.0.7-alpha) - Console framework
|
|
|
+- **System.IO.Abstractions** - File system abstraction
|
|
|
+- **.NET 9.0** - Target framework
|
|
|
+
|
|
|
+## API Endpoints
|
|
|
+
|
|
|
+The client supports all REST API endpoints:
|
|
|
+
|
|
|
+| Endpoint | Method | Description |
|
|
|
+|----------|--------|-------------|
|
|
|
+| `/upload/init` | POST | Initialize chunked upload |
|
|
|
+| `/upload/chunk` | POST | Upload file chunk |
|
|
|
+| `/upload/finalize` | POST | Complete upload |
|
|
|
+| `/media/{id}` | GET | Get file details |
|
|
|
+| `/media/{id}` | PUT | Update file properties |
|
|
|
+| `/media/{id}` | DELETE | Delete file |
|
|
|
+| `/media` | GET | List files with filtering |
|
|
|
+
|
|
|
+## WordPress Plugin Integration
|
|
|
+
|
|
|
+This client is designed to work with the QDR Temporary Shared Storage WordPress plugin. The plugin provides:
|
|
|
+
|
|
|
+- Secure file storage and management
|
|
|
+- Password-protected downloads
|
|
|
+- Expiration date handling
|
|
|
+- Download analytics
|
|
|
+- WordPress shortcode integration
|
|
|
+- Admin interface for file management
|
|
|
+
|
|
|
+## Contributing
|
|
|
+
|
|
|
+1. Fork the repository
|
|
|
+2. Create a feature branch
|
|
|
+3. Make your changes
|
|
|
+4. Add tests if applicable
|
|
|
+5. Submit a pull request
|
|
|
+
|
|
|
+## License
|
|
|
+
|
|
|
+Copyright © Quadarax 2025. All rights reserved.
|
|
|
+
|
|
|
+## Support
|
|
|
+
|
|
|
+For support and documentation:
|
|
|
+- Visit: https://www.quadarax.com/plugins/qdr-temporary-shared-storage
|
|
|
+- API Documentation: See `rest-api-docs.md`
|
|
|
+
|
|
|
+## Changelog
|
|
|
+
|
|
|
+### Version 1.0.0
|
|
|
+- Initial release
|
|
|
+- Chunked file upload support
|
|
|
+- Complete REST API client
|
|
|
+- Console application
|
|
|
+- Comprehensive error handling
|
|
|
+- Progress reporting
|
