gitcaddy-server/sdk/java/README.md

# Gitea Java SDK

Official Java SDK for the Gitea API with chunked upload support for large files.

## Requirements

- Java 17 or later
- Maven or Gradle

## Installation

### Maven

```xml
<dependency>
    <groupId>io.gitea</groupId>
    <artifactId>gitea-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

### Gradle

```groovy
implementation 'io.gitea:gitea-sdk:1.0.0'
```

## Quick Start

```java
import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.models.*;

// Create client
var client = new GiteaClient("https://gitea.example.com", "your_token");

// Get current user
var user = client.getCurrentUser();
System.out.println("Logged in as " + user.getLogin());

// Get a repository
var repo = client.getRepository("owner", "repo");
System.out.println("Repository: " + repo.getFullName());
```

## Chunked Upload

Upload large files with progress tracking:

```java
import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.models.*;

import java.io.FileInputStream;

var client = new GiteaClient("https://gitea.example.com", "your_token");

// Upload a release asset with progress
try (var fileStream = new FileInputStream("large-file.tar.gz")) {
    var fileSize = new java.io.File("large-file.tar.gz").length();

    var result = client.uploadReleaseAsset(
        "myorg",
        "myrepo",
        123L,
        fileStream,
        "large-file.tar.gz",
        fileSize,
        new ChunkedUploadOptions()
            .setChunkSize(50 * 1024 * 1024) // 50MB chunks
            .setParallel(4)
            .setVerifyChecksum(true)
            .setOnProgress(p -> {
                System.out.printf("Progress: %.1f%%%n", p.getPercent());
                System.out.println("Speed: " + p.getSpeedFormatted());
                System.out.println("ETA: " + p.getEtaFormatted());
            })
    );

    System.out.println("Uploaded: " + result.getBrowserDownloadUrl());
}
```

## Using ChunkedUpload Directly

For more control over the upload process:

```java
import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.ChunkedUpload;
import io.gitea.sdk.models.*;

var client = new GiteaClient("https://gitea.example.com", "your_token");

var upload = client.createChunkedUpload("owner", "repo", 123L,
    new ChunkedUploadOptions()
        .setChunkSize(50 * 1024 * 1024)
        .setParallel(4)
        .setOnProgress(p -> System.out.printf("%.1f%%%n", p.getPercent()))
);

try (var stream = new FileInputStream("file.tar.gz")) {
    var fileSize = new java.io.File("file.tar.gz").length();
    var result = upload.upload(stream, "file.tar.gz", fileSize);
    System.out.println("Success: " + result.getBrowserDownloadUrl());
} catch (UploadException e) {
    // Upload failed, can retry later
    System.out.println("Resume with session: " + upload.getSession().getId());
}
```

## API Reference

### GiteaClient

#### Constructor

```java
// With token
var client = new GiteaClient("https://gitea.example.com", "your_api_token");

// With custom HttpClient
var httpClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(60))
    .build();
var client = new GiteaClient("https://gitea.example.com", "your_api_token", httpClient);
```

#### User Methods

- `getCurrentUser()` - Get authenticated user
- `getUser(username)` - Get user by username

#### Repository Methods

- `getRepository(owner, repo)` - Get repository
- `listUserRepositories(username)` - List user's repositories

#### Release Methods

- `getRelease(owner, repo, releaseId)` - Get release by ID
- `getReleaseByTag(owner, repo, tag)` - Get release by tag
- `listReleases(owner, repo)` - List all releases

#### Upload Methods

- `uploadReleaseAsset(...)` - Upload release asset with chunked upload
- `createChunkedUpload(owner, repo, releaseId, options)` - Create upload handler
- `getUploadSession(sessionId)` - Get upload session status
- `cancelUpload(sessionId)` - Cancel upload session

## Error Handling

```java
import io.gitea.sdk.GiteaClient;
import io.gitea.sdk.exceptions.*;

var client = new GiteaClient("https://gitea.example.com", "your_token");

try {
    var repo = client.getRepository("owner", "nonexistent");
} catch (NotFoundException e) {
    System.out.println("Repository not found: " + e.getMessage());
} catch (AuthenticationException e) {
    System.out.println("Authentication failed: " + e.getMessage());
} catch (UploadException e) {
    System.out.println("Upload failed: " + e.getMessage());
    System.out.println("Session: " + e.getSessionId() + ", Chunk: " + e.getChunkNumber());
} catch (ApiException e) {
    System.out.println("API error [" + e.getCode() + "]: " + e.getMessage());
} catch (GiteaException e) {
    System.out.println("Error: " + e.getMessage());
}
```

## Thread Safety

The `GiteaClient` is thread-safe and can be shared across multiple threads. Each `ChunkedUpload` instance should be used by a single thread at a time.

## License

MIT License - See LICENSE file for details.