# GitStore

[![Package Version](https://img.shields.io/hexpm/v/git_store)](https://hex.pm/packages/git_store)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/git_store/)

A Gleam library for interacting with git forge repositiories like Codeberg, Forgejo and GitHub.  
GitStore provides a simple API to create, read, update, and delete files in forge repositories through their respective  
REST API.


## Installation

```sh
gleam add git_store
```

## Usage

First, create a config for your forge. For GitHub and Codeberg, provide the
repository owner, repository name, and a personal access token. For self-hosted
Forgejo instances, also supply the base URL of your instance.

```gleam
import git_store

// Codeberg
let config = git_store.new_codeberg_config("owner", "my-repo", "token...")

// GitHub
let config = git_store.new_github_config("owner", "my-repo", "ghp_token...")

// Self-hosted Forgejo
let config = git_store.new_forgejo_config("owner", "my-repo", "token...", "https://forgejo.example.com")
```

### CRUD Operations

All operations return `Result(PlatformResponse, GitStoreError)`. File content is
automatically base64-encoded on write and decoded on read.

```gleam
import git_store
import git_store/types

let config = git_store.new_codeberg_config("owner", "my-repo", "token...")

// Create a file
let assert Ok(types.CreateFileResponse(content: file, ..)) =
  git_store.create_file(config, "notes/hello.txt", "Hello, world!")

// Read a file
let assert Ok(types.GetFileResponse(content: text, ..)) =
  git_store.get_file(config, "notes/hello.txt")

// Update a file
let assert Ok(types.UpdateFileResponse(content: file, ..)) =
  git_store.update_file(config, "notes/hello.txt", "Updated content")

// Delete a file
let assert Ok(types.DeleteFileResponse(..)) =
  git_store.delete_file(config, "notes/hello.txt")

```

### Error Handling

```gleam
import git_store
import git_store/errors
import git_store/types

case git_store.get_file(config, "missing.txt") {
  Ok(types.GetFileResponse(content: text, ..)) -> io.println(text)
  Error(errors.NoFileFound(filename)) -> io.println("Not found: " <> filename)
  Error(errors.ForgeError(status, body)) -> io.println("API error " <> int.to_string(status))
  Error(errors.HTTPError(msg)) -> io.println("HTTP error: " <> msg)
  Error(errors.ParsingError(msg)) -> io.println("Parse error: " <> msg)
  _ -> io.println("Unexpected response type")
}
```

## Development

Pull requests gladly accepted for small bug fixes.

For anything larger, particularly new features, it's best to raise an issue to discuss ahead of commencing with any work.

### Testing

Gleeunit and Birdie are both used for testing.

For integration tests, you will need to set the following environment variables:

```
CODEBERG_REPO_NAME
CODEBERG_REPO_OWNER
CODEBERG_REPO_TOKEN
```

To get the values, you must create a repository on Codeberg. Your username will be the owner, and the name you set will be the repo name.
You can generate a token [here](https://codeberg.org/user/settings/applications). Repository read and write permissions are required.

## Documentation

Further documentation can be found at <https://hexdocs.pm/git_store>.