Communication between GitHub and ungh-kt - The Kotlin driver for unjs/ungh
Tags: github, kotlin, ungh, jvm
Published: 2024-04-30 18:00:26

In this article I will introduce you to my Kotlin library `ungh-kt` and show you how to use it.

## What is unjs/ungh and what is it for?
UNGH gives each of us the opportunity to use the GitHub API on an "unlimited" basis. The public service provided by unjs opens many more doors to do some things related to GitHub.

[learn more about unjs/ungh here](https://github.com/unjs/ungh)

## How can we use the ungh-kt driver?
[Download the driver from Maven Central](https://central.sonatype.com/artifact/dev.gradienttim/ungh-kt)
Once we have implemented the driver, we can use the class `Ungh` to access all available functions.

### Get information about a user
```kotlin
val user: User? = Ungh.user("GradientTim")
if (user == null) {
    println("User 'GradientTim' not found")
    return
}
val id: Int = user.id
val username: String = user.username
val name: String? = user.name
val twitter: String? = user.twitter
val avatar: String? = user.avatar
```
### Receive all public repositories from a user
```kotlin
val repositories = Ungh.userRepositories("GradientTim")
repositories.forEach {
    println("Repository id: ${it.id}")
    println("Repository name: ${it.name}")
}
```
### Search for a user by email or name
```kotlin
val query: User? = Ungh.userQuery("pooya@pi0.io")
if (query != null) {
    println("User found!")
}
```

### Get the number of stars from repositories
```kotlin
val stars = Ungh.stars(listOf(
    "unjs/ungh",
    "unjs/nitro",
))
if (stars != null) {
    println("Total stars: ${stars.totalStars}")
    stars.stars.forEach { (key, value) ->
        println("$key has $value stars")
    }
}
```

### Receive information about an organization
```kotlin
val organization: Organization? = Ungh.organization("unjs")
if (organization == null) {
    println("Organization 'unjs' not found")
    return
}
val id: Int = organization.id
val name: String = organization.name
val description: String = organization.description
```
### Receive all public repositories from an organization
```kotlin
val repositories = Ungh.organizationRepositories("unjs")
repositories.forEach {
    println("Repository id: ${it.id}")
    println("Repository name: ${it.name}")
}
```

### Receive information about a repository
```kotlin
val repository: Repository? = Ungh.repository("unjs", "ungh")
if (repository == null) {
    println("Repository 'unjs/ungh' not found")
    return
}
val id: Int = repository.id
val name: String = repository.name
val repo: String = repository.repo
val description: String? = repository.description
val createdAt: String = repository.createdAt
val updatedAt: String = repository.updatedAt
val pushedAt: String = repository.pushedAt
val stars: Int = repository.stars
val watchers: Int = repository.watchers
val forks: Int = repository.forks
val defaultBranch: String = repository.defaultBranch
```
### Get all contributors from a repository
```kotlin
val contributors = Ungh.repositoryContributors("unjs", "ungh")
contributors.forEach {
    val id: Int = it.id
    val username: String = it.username
    val amount: Int = it.contributions
    println("$username has in this repository $amount contributions")
}
```
### List all files in a repository branch
```kotlin
val branchFiles = Ungh.repositoryBranchFiles("unjs", "ungh", "main")
if (branchFiles == null) {
    println("Branch or repository not found")
    return
}
val meta: FileMeta = branchFiles.meta
val files: MutableList<BranchFile> = branchFiles.files
val sha: String = meta.sha
files.forEach {
    val path: String = it.path
    val mode: String = it.mode
    val sha: String = it.sha
    val size: Int = it.size
}
```
### Receive file content in a repository branch
```kotlin
val branchFile = Ungh.repositoryBranchFile(
    "unjs", // organization name
    "ungh", // repository name
    "main", // repository branch
    "README.md" // path to file
)
val meta: SimpleFileMeta = branchFile.meta
val file: SimpleFile = branchFile.file
val url: String = meta.url
val markdownContent: String = file.contents
val htmlContent: String? = file.html
```
### Receive ReadMe from a repository
```kotlin
val readMe = Ungh.repositoryReadMe("unjs", "ungh")
if (readMe == null) {
    println("ReadMe file not found")
    return
}
val html: String = readMe.html
val markdown: String = readMe.markdown
```
### List all releases of a repository
```kotlin
val releases = Ungh.repositoryReleases("JetBrains", "Kotlin")
releases.forEach {
    val id: Int = it.id
    val tag: String = it.tag
    val author: String = it.author
    val name: String = it.name
    val draft: Boolean = it.draft
    val preRelease: Boolean = it.preRelease
    val createdAt: String = it.createdAt
    val publishedAt: String = it.publishedAt
    val markdown: String = it.markdown
    val html: String = it.html
}
```
### Receive the latest release from a repository
```kotlin
val release: Repository? = Ungh.repositoryLatestRelease(
    "JetBrains", // organization name
    "Kotlin" // repository name
)
if (release == null) {
    println("This repository has no releases")
    return
}
val id: Int = release.id
val tag: String = release.tag
val author: String = release.author
// ...
```
### List all branches from a repository
```kotlin
val branches = Ungh.repositoryBranches("unjs", "ungh")
branches.forEach {
    val name: String = it.name
    val protected: Boolean = it.protected
    val commit: BranchCommit = it.commit
    val commitSha: String = commit.sha
    val commitUrl: String = commit.url
}
```
These were all the functions provided by the library `ungh-kt`.
Enjoy and have fun 😊

Contact: [GitHub](https://github.com/GradientTim/ungh-kt) - [Twitter/X](https://x.com/GradientTim)