ForgejoKit/README.md

# ForgejoKit

A native Swift library for the [Forgejo](https://forgejo.org) API. ForgejoKit provides a typed, async/await interface for interacting with Forgejo instances from Swift applications on macOS and iOS.

## Features

- Authentication via username/password (with optional OTP), API tokens, or OAuth2 bearer tokens
- Repositories: search, list, create, fork, star, file contents, commits, branches, tags, releases
- Issues: create, edit, list, comment, manage labels and milestones
- Pull requests: create, edit, merge, review, diff
- Notifications: list, unread count, mark as read
- Self-signed certificate support

## Installation

Add ForgejoKit as a dependency in your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://codeberg.org/secana/ForgejoKit.git", from: "0.8.0"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: ["ForgejoKit"]
    ),
]
```

## Usage

```swift
import ForgejoKit

// Authenticate with a token
let client = ForgejoClient(serverURL: "https://codeberg.org", username: "user", token: "your-token")

// Or authenticate with an OAuth2 access token (sent as `Authorization: Bearer`)
let client = ForgejoClient(serverURL: "https://codeberg.org", username: "user", bearerToken: "oauth2-access-token")

// Or log in with username/password to create an API token
let result = try await ForgejoClient.login(serverURL: "https://codeberg.org", username: "user", password: "pass")
let client = result.client

// Fetch repositories
let repoService = RepositoryService(client: client)
let repos = try await repoService.searchRepositories(query: "swift")

// Work with issues
let issueService = IssueService(client: client)
let issues = try await issueService.fetchIssues(owner: "owner", repo: "repo")

// Check notifications
let notificationService = NotificationService(client: client)
let unread = try await notificationService.fetchUnreadCount()
```

## Development

### Prerequisites

Install [Nix](https://nixos.org/download) and enable [flakes](https://wiki.nixos.org/wiki/Flakes).

### Dev Shell

Enter the development shell with all required tools:

```sh
nix develop
```

This provides `swift`, `swiftformat`, and `just` on all platforms, plus `swiftlint` and `xcbeautify` on macOS.

### Building and Testing

The project uses [just](https://github.com/casey/just) as a command runner. Run `just` to see all available commands:

```sh
just          # list available commands
just build    # build the library
just test     # run tests
just lint     # lint sources with swiftlint
just format   # format sources with swiftformat
```

## Releasing a New Version

Make sure all changes are committed and pushed, then run:

```sh
just release 1.0.0
```

This will verify the tag doesn't already exist, update the version in `README.md`, commit, tag, and push. Swift Package Manager resolves versions from git tags, so no registry publication is needed.