// File: lib/clients/giteaclient/readme.md

giteaclient

This library provides a client for interacting with the Gitea API.

Configuration

You can configure the client using a HeroScript file:

!!giteaclient.configure
    name: 'default' // optional, 'default' is the default instance name
    url: 'https://git.ourworld.tf'
    secret: 'your-gitea-api-token'

Usage Example

Here's how to get the client and use its methods.

import incubaid.herolib.clients.giteaclient
import incubaid.herolib.core.base

fn main() ! {
    // Make sure hero is initialized
    base.init()!

 // Example configuration (can also be loaded from file)
 heroscript_config := '!!giteaclient.configure url:'https://gitea.com' secret:'...your_token...''
 mut plbook := playbook.new(text: heroscript_config)!
 giteaclient.play(mut plbook)!

 // Get the default configured client
 mut client := giteaclient.get()!

 // Get the authenticated user
 user := client.get_current_user()!
 println('Authenticated as: ${user.login}')

 // List repositories for the authenticated user
 repos := client.user_list_repos()!
 println('Found ${repos.len} repositories:')
 for repo in repos {
  println('- ${repo.full_name}')
 }

    // Get a specific repository's issues
    owner := 'gitea'
    repo_name := 'gitea'
    println('\nFetching issues for ${owner}/${repo_name}...')
    issues := client.list_repo_issues(owner, repo_name)!
    println('Found ${issues.len} issues.')
    for issue in issues[..5] { // print first 5 issues
        println('  #${issue.number}: ${issue.title}')
    }
}


#
- to see the admin api: https://git.ourworld.tf/api/swagger

fn delete(args ArgsGet) !

fn exists(args ArgsGet) !bool

does the config exists?

fn get(args ArgsGet) !&GiteaClient

fn heroscript_loads(heroscript string) !GiteaClient

///////////NORMALLY NO NEED TO TOUCH

fn list(args ArgsList) ![]&GiteaClient

if fromdb set: load from filesystem, and not from mem, will also reset what is in mem

fn new(args ArgsGet) !&GiteaClient

fn play(mut plbook PlayBook) !

fn set(o GiteaClient) !

register the config for the future

fn switch(name string)

switch instance to be used for giteaclient

struct APIError {
pub:
	message string
	url     string
}

struct AccessToken {
pub:
	id               i64
	name             string
	scopes           []string
	sha1             string
	token_last_eight string
}

struct ActionVariable {
pub:
	owner_id i64
	repo_id  i64
	name     string
	data     string
}

struct Activity {
pub:
	act_user    User
	act_user_id i64
	comment     Comment
	comment_id  i64
	content     string
	created     time.Time
	id          i64
	is_private  bool
	op_type     string
	ref_name    string
	repo        Repository
	repo_id     i64
	user_id     i64
}

struct AddCollaboratorOption {
pub:
	permission string
}

struct AddTimeOption {
pub:
	time      i64
	created   time.Time
	user_name string
}

struct AnnotatedTag {
pub:
	message      string
	object       AnnotatedTagObject
	sha          string
	tag          string
	tagger       CommitUser
	url          string
	verification PayloadCommitVerification
}

struct AnnotatedTagObject {
pub:
	sha string
	typ string @[json: 'type'] // `type` is a keyword in V
	url string
}

struct ArgsGet {
pub mut:
	name   string = 'default'
	fromdb bool // will load from filesystem
	create bool // default will not create if not exist
}

///////FACTORY

struct ArgsList {
pub mut:
	fromdb bool // will load from filesystem
}

struct Attachment {
pub:
	browser_download_url string
	created_at           time.Time
	download_count       i64
	id                   i64
	name                 string
	size                 i64
	uuid                 string
}

struct Badge {
pub:
	id          i64
	slug        string
	description string
	image_url   string
}

struct Branch {
pub:
	commit                           PayloadCommit
	effective_branch_protection_name string
	enable_status_check              bool
	name                             string
	protected                        bool
	required_approvals               i64
	status_check_contexts            []string
	user_can_merge                   bool
	user_can_push                    bool
}

struct BranchProtection {
pub:
	branch_name                       string
	rule_name                         string
	enable_push                       bool
	enable_push_whitelist             bool
	push_whitelist_usernames          []string
	push_whitelist_teams              []string
	push_whitelist_deploy_keys        bool
	enable_merge_whitelist            bool
	merge_whitelist_usernames         []string
	merge_whitelist_teams             []string
	enable_status_check               bool
	status_check_contexts             []string
	required_approvals                i64
	enable_approvals_whitelist        bool
	approvals_whitelist_username      []string
	approvals_whitelist_teams         []string
	block_on_rejected_reviews         bool
	block_on_official_review_requests bool
	block_on_outdated_branch          bool
	dismiss_stale_approvals           bool
	ignore_stale_approvals            bool
	require_signed_commits            bool
	protected_file_patterns           string
	unprotected_file_patterns         string
	created_at                        time.Time
	updated_at                        time.Time
}

struct ChangeFileOperation {
pub:
	operation string // "create", "update", "delete"
	path      string
	content   string // base64 encoded
	from_path string
	sha       string
}

struct ChangeFilesOptions {
pub:
	author     Identity
	branch     string
	committer  Identity
	dates      CommitDateOptions
	files      []ChangeFileOperation
	message    string
	new_branch string
	signoff    bool
}

struct ChangedFile {
pub:
	additions         i64
	changes           i64
	contents_url      string
	deletions         i64
	filename          string
	html_url          string
	previous_filename string
	raw_url           string
	status            string
}

struct Comment {
pub:
	assets             []Attachment
	body               string
	created_at         time.Time
	html_url           string
	id                 i64
	issue_url          string
	original_author    string
	original_author_id i64
	pull_request_url   string
	updated_at         time.Time
	user               User
}

struct Commit {
pub:
	author    User
	commit    RepoCommit
	committer User
	created   time.Time
	files     []CommitAffectedFiles
	html_url  string
	parents   []CommitMeta
	sha       string
	stats     CommitStats
	url       string
}

struct CommitAffectedFiles {
pub:
	filename string
	status   string
}

struct CommitDateOptions {
pub:
	author    time.Time
	committer time.Time
}

struct CommitMeta {
pub:
	created time.Time
	sha     string
	url     string
}

struct CommitStats {
pub:
	additions i64
	deletions i64
	total     i64
}

struct CommitUser {
pub:
	date  string
	email string
	name  string
}

struct CreateIssueOption {
pub:
	title     string
	assignee  string
	assignees []string
	body      string
	closed    bool
	due_date  time.Time
	labels    []i64
	milestone i64
	ref       string
}

struct CreateRepoOption {
pub:
	name               string
	auto_init          bool
	default_branch     string
	description        string
	gitignores         string
	issue_labels       string
	license            string
	object_format_name string // "sha1" or "sha256"
	private            bool
	readme             string
	template           bool
	trust_model        string // "default", "collaborator", "committer", "collaboratorcommitter"
}

struct GiteaClient {
pub mut:
	name   string = 'default'
	user   string
	url    string = 'https://git.ourworld.tf'
	secret string
}

fn (mut client GiteaClient) admin_list_users() ![]User

list_users lists all users

fn (mut client GiteaClient) create_current_user_repo(args CreateRepoOption) !Repository

Create a repository for the authenticated user.

fn (mut client GiteaClient) create_issue(owner string, repo string, args CreateIssueOption) !Issue

Create an issue

fn (mut client GiteaClient) get_current_user() !User

get_current_user gets the authenticated user

fn (mut client GiteaClient) get_issue(owner string, repo string, index i64) !Issue

Get an issue

fn (mut client GiteaClient) get_repo(owner string, repo string) !Repository

Get a repository

fn (mut client GiteaClient) get_user(username string) !User

get_user gets a user by username

fn (mut client GiteaClient) list_repo_issues(owner string, repo string) ![]Issue

List a repository's issues

fn (mut client GiteaClient) user_list_repos() ![]Repository

List a user's own repositories

struct Identity {
pub:
	email string
	name  string
}

struct InternalTracker {
pub:
	allow_only_contributors_to_track_time bool
	enable_issue_dependencies             bool
	enable_time_tracker                   bool
}

struct Issue {
pub:
	id                 i64
	url                string
	html_url           string
	number             i64
	user               User
	original_author    string
	original_author_id i64
	title              string
	body               string
	ref                string
	labels             []Label
	milestone          Milestone
	assignee           User
	assignees          []User
	state              string // StateType
	is_locked          bool
	comments           i64
	created_at         time.Time
	updated_at         time.Time
	closed_at          time.Time
	due_date           time.Time
	pull_request       PullRequestMeta
	repository         RepositoryMeta
	assets             []Attachment
	pin_order          i64
}

struct Label {
pub:
	id          i64
	name        string
	exclusive   bool
	is_archived bool
	color       string
	description string
	url         string
}

struct Milestone {
pub:
	id            i64
	title         string
	description   string
	state         string // StateType
	open_issues   i64
	closed_issues i64
	created_at    time.Time
	updated_at    time.Time
	closed_at     time.Time
	due_on        time.Time
}

struct Organization {
pub:
	avatar_url                    string
	description                   string
	email                         string
	full_name                     string
	id                            i64
	location                      string
	name                          string
	repo_admin_change_team_access bool
	username                      string
	visibility                    string
	website                       string
}

struct PayloadCommit {
pub:
	added        []string
	author       PayloadUser
	committer    PayloadUser
	id           string
	message      string
	modified     []string
	removed      []string
	timestamp    time.Time
	url          string
	verification PayloadCommitVerification
}

struct PayloadCommitVerification {
pub:
	payload   string
	reason    string
	signature string
	signer    PayloadUser
	verified  bool
}

struct PayloadUser {
pub:
	email    string
	name     string
	username string
}

struct Permission {
pub:
	admin bool
	pull  bool
	push  bool
}

struct PullRequestMeta {
pub:
	merged    bool
	merged_at time.Time
	draft     bool
	html_url  string
}

struct RepoCommit {
pub:
	author       CommitUser
	committer    CommitUser
	message      string
	tree         CommitMeta
	url          string
	verification PayloadCommitVerification
}

struct RepoTransfer {
pub:
	doer      User
	recipient User
	teams     []Team
}

struct Repository {
pub:
	id                                i64
	owner                             User
	name                              string
	full_name                         string
	description                       string
	empty                             bool
	private                           bool
	fork                              bool
	template                          bool
	parent_id                         i64
	mirror                            bool
	size                              i64
	language                          string
	languages_url                     string
	html_url                          string
	url                               string
	link                              string
	ssh_url                           string
	clone_url                         string
	website                           string
	stars_count                       i64
	forks_count                       i64
	watchers_count                    i64
	open_issues_count                 i64
	open_pr_counter                   i64
	release_counter                   i64
	default_branch                    string
	archived                          bool
	created_at                        time.Time
	updated_at                        time.Time
	archived_at                       time.Time
	permissions                       Permission
	has_issues                        bool
	internal_tracker                  InternalTracker
	has_wiki                          bool
	has_pull_requests                 bool
	has_projects                      bool
	has_releases                      bool
	has_packages                      bool
	has_actions                       bool
	ignore_whitespace_conflicts       bool
	allow_merge_commits               bool
	allow_rebase                      bool
	allow_rebase_explicit             bool
	allow_squash_merge                bool
	allow_fast_forward_only_merge     bool
	allow_rebase_update               bool
	default_delete_branch_after_merge bool
	default_merge_style               string
	default_allow_maintainer_edit     bool
	avatar_url                        string
	internal                          bool
	mirror_interval                   string
	mirror_updated                    time.Time
	repo_transfer                     RepoTransfer
}

struct RepositoryMeta {
pub:
	id        i64
	name      string
	owner     string
	full_name string
}

struct Team {
pub:
	can_create_org_repo       bool
	description               string
	id                        i64
	includes_all_repositories bool
	name                      string
	organization              Organization
	permission                string
	units                     []string
	units_map                 map[string]string
}

struct User {
pub:
	id                  i64
	login               string
	full_name           string
	email               string
	avatar_url          string
	language            string
	is_admin            bool
	last_login          time.Time
	created             time.Time
	restricted          bool
	active              bool
	prohibit_login      bool
	location            string
	website             string
	description         string
	visibility          string
	followers_count     i64
	following_count     i64
	starred_repos_count i64
	username            string
}