# 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