mirror of
https://codeberg.org/secana/ForgejoKit.git
synced 2026-06-16 05:13:53 -07:00
92 lines
2.6 KiB
Markdown
92 lines
2.6 KiB
Markdown
|
# 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) or API 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.1.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 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.
|