# Gitea GitHub SDK Shim

A compatibility layer that provides GitHub SDK interfaces (PyGitHub and Octokit) for Gitea repositories. This allows you to use existing GitHub-based code with Gitea instances with minimal changes.

## Installation

### Python

```bash
cd gitea-shim/python
pip install -e .
```

### JavaScript/TypeScript

```bash
cd gitea-shim/javascript
npm install
```

## Usage

### Python (PyGitHub Compatible)

Instead of using PyGitHub:

```python
# Old GitHub code
from github import Github
gh = Github(token)
repo = gh.get_repo("owner/repo")
```

Use the Gitea shim:

```python
# New Gitea code
from gitea_github_shim import GiteaGitHubShim
gh = GiteaGitHubShim(token, base_url="https://your-gitea-instance.com")
repo = gh.get_repo("owner/repo")
```

Or with environment variables:

```python
import os
os.environ['GITEA_URL'] = 'https://your-gitea-instance.com'

# Now you can use it just like GitHub
gh = GiteaGitHubShim(token)  # URL is taken from env
repo = gh.get_repo("owner/repo")
```

### JavaScript/TypeScript (Octokit Compatible)

Instead of using Octokit:

```javascript
// Old GitHub code
const { Octokit } = require("@octokit/rest");
const octokit = new Octokit({ auth: token });
const repo = await octokit.rest.repos.get({ owner, repo });
```

Use the Gitea shim:

```javascript
// New Gitea code
const { GiteaOctokitShim } = require("gitea-shim");
const octokit = new GiteaOctokitShim({ 
  auth: token,
  baseUrl: "https://your-gitea-instance.com"
});
const repo = await octokit.rest.repos.get({ owner, repo });
```

## Supported APIs

### Repository Operations
- `get_repo()` / `rest.repos.get()` - Get repository
- `create_repo()` / `rest.repos.createForAuthenticatedUser()` - Create repository
- `repo.default_branch` - Get default branch
- `repo.create_fork()` / `rest.repos.createFork()` - Fork repository

### Pull Request Operations
- `repo.get_pull()` / `rest.pulls.get()` - Get pull request
- `repo.get_pulls()` / `rest.pulls.list()` - List pull requests
- `repo.create_pull()` / `rest.pulls.create()` - Create pull request
- `pr.update()` / `rest.pulls.update()` - Update pull request
- `pr.merge()` / `rest.pulls.merge()` - Merge pull request

### User Operations
- `get_user()` / `rest.users.getAuthenticated()` - Get user
- `user.get_repos()` - Get user repositories
- `user.add_to_following()` / `rest.users.follow()` - Follow user

### Activity Operations
- `user.get_starred()` / `rest.activity.listReposStarredByUser()` - Get starred repos
- `user.get_subscriptions()` / `rest.activity.listWatchedReposForUser()` - Get watched repos

## Environment Variables

- `GITEA_URL` - Base URL of your Gitea instance (e.g., `https://gitea.example.com`)
- `GITEA_TOKEN` - Personal access token for Gitea (you can still use `GITHUB_TOKEN` for compatibility)

## Migration Guide

### Step 1: Install the shim

```bash
# Python
pip install gitea-github-shim

# JavaScript
npm install gitea-github-shim
```

### Step 2: Update imports

Python:
```python
# Replace
from github import Github

# With
from gitea_github_shim import GiteaGitHubShim as Github
```

JavaScript:
```javascript
// Replace
const { Octokit } = require("@octokit/rest");

// With
const { GiteaOctokitShim: Octokit } = require("gitea-github-shim");
```

### Step 3: Update initialization

Add the Gitea URL when creating the client:

Python:
```python
gh = Github(token, base_url="https://your-gitea-instance.com")
```

JavaScript:
```javascript
const octokit = new Octokit({ 
  auth: token,
  baseUrl: "https://your-gitea-instance.com"
});
```

### Step 4: Handle API differences

Some features may not be available or work differently in Gitea:

1. **Draft PRs** - May not be supported
2. **Rate Limiting** - Gitea typically doesn't have rate limits
3. **GraphQL API** - Not available in Gitea
4. **Advanced Search** - Limited compared to GitHub

## Development

### Running Tests

```bash
# Python tests
cd gitea-shim/python
python -m pytest tests/

# JavaScript tests
cd gitea-shim/javascript
npm test
```

### Contributing

1. Check the `todo.md` file for pending tasks
2. Add tests for any new functionality
3. Update this README with new supported APIs
4. Submit a pull request

## Limitations

- Some GitHub-specific features are not available in Gitea
- API responses may have slight differences in structure
- Not all endpoints are implemented yet
- GraphQL is not supported (REST API only)

## License

MIT License - See LICENSE file for details