### Install and Run Varia Locally (Bash)

Source: https://github.com/hpottipati/greptile-takehome/blob/main/README.md

Instructions for setting up and running the Varia project locally. This involves installing dependencies, configuring environment variables, and starting the development server. Ensure you have your GitHub, Supabase, and OpenAI API keys ready.

```bash
bun install
cp .env.example .env.local   # fill GitHub + Supabase + OpenAI keys
bun dev                      # http://localhost:3000
```

--------------------------------

### GitHubService: Get Repositories and Commits

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Initialize GitHubService with an access token to fetch repository data. Supports retrieving a list of user repositories and detailed commit information within a specified date range. Requires a valid GitHub access token.

```typescript
import { GitHubService } from '@/lib/services/github';

const github = new GitHubService(accessToken);

// Get user's repositories
const repos = await github.getRepos();
// Returns: [{ id: 123, name: 'repo', owner: 'user', full_name: 'user/repo', ... }]

// Get commits with date filtering
const commits = await github.getCommits('anthropics', 'claude-code',
  '2025-01-01T00:00:00Z', '2025-01-15T23:59:59Z');
// Returns: [{ sha: 'abc123', message: '...', author: 'User', date: '...', html_url: '...' }]
```

--------------------------------

### List Releases - TypeScript

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves a list of GitHub releases for a specified repository. This endpoint uses GET /api/repos/[id]/releases. Authentication via cookies is required. The response is an array of release objects, each containing details like the tag name, release name, body, publication date, and HTML URL.

```typescript
// GET /api/repos/[id]/releases - Get GitHub releases for repository

const response = await fetch('/api/repos/abc-123/releases', {
  headers: { 'Cookie': 'next-auth.session-token=...' }
});

const releases = await response.json();
// Returns: [{ tag_name: 'v1.2.0', name: 'Version 1.2.0', body: '...',
//            published_at: '2025-01-15T10:00:00Z', html_url: '...' }]
```

--------------------------------

### Get Repository Activity - TypeScript

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Fetches commit history for a repository, typically used for changelog generation interfaces. It makes a GET request to the /api/repos/[id]/activity endpoint, with optional 'branch' and 'limit' query parameters. Authentication is required via cookies. The response includes a list of commits, each with its SHA, message, author, date, and associated pull request information.

```typescript
// GET /api/repos/[id]/activity - Get commits for changelog generation UI

const response = await fetch('/api/repos/abc-123/activity?branch=main&limit=50', {
  headers: { 'Cookie': 'next-auth.session-token=...' }
});

const activity = await response.json();
// Returns: { commits: [{ sha: 'abc123', message: 'Add feature', author: 'User',
//            date: '2025-01-15T10:00:00Z', pullRequest: { number: 42, title: '...' } }] }
```

--------------------------------

### Get Repository Activity

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves commit history for a specified repository, typically used for populating changelog generation UIs.

```APIDOC
## GET /api/repos/[id]/activity

### Description
Get commits for changelog generation UI.

### Method
GET

### Endpoint
/api/repos/[id]/activity

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the repository.

#### Query Parameters
- **branch** (string) - Optional - The branch to fetch commits from. Defaults to 'main'.
- **limit** (integer) - Optional - The maximum number of commits to retrieve.

### Response
#### Success Response (200)
- **commits** (array) - An array of commit objects.
  - **sha** (string) - The commit SHA.
  - **message** (string) - The commit message.
  - **author** (string) - The author of the commit.
  - **date** (string) - The date and time of the commit.
  - **pullRequest** (object) - Information about the associated pull request.
    - **number** (integer) - The pull request number.
    - **title** (string) - The pull request title.

#### Response Example
```json
{
  "commits": [
    {
      "sha": "abc123",
      "message": "Add feature",
      "author": "User",
      "date": "2025-01-15T10:00:00Z",
      "pullRequest": {
        "number": 42,
        "title": "..."
      }
    }
  ]
}
```
```

--------------------------------

### List Changelog Entries - TypeScript

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves a list of changelog entries for a given repository, filtered by status. It uses the GET /api/entries endpoint with query parameters for repositoryId and status. Authentication is handled via cookies. The response is an array of changelog entries, each containing an ID, title, content, status, and associated repository information.

```typescript
// GET /api/entries?repositoryId=abc-123&status=published - List user's entries

const response = await fetch('/api/entries?repositoryId=abc-123&status=draft', {
  headers: { 'Cookie': 'next-auth.session-token=...' }
});

const entries = await response.json();
// Returns: [{ id: 'uuid', title: 'Release v1.2.0', content: '...', status: 'draft',
//            repositories: { full_name: 'anthropics/claude-code', ... } }]
```

--------------------------------

### GitHubService: Get Pull Request Diffs and Issues

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Utilizes GitHubService to retrieve pull request diffs, including sensitive file filtering, and fetch specific issue details. These functions are crucial for understanding code changes and issue tracking within a repository. Requires repository owner, name, and PR/issue number.

```typescript
import { GitHubService } from '@/lib/services/github';

const github = new GitHubService(accessToken);

// Get pull request diff with automatic sensitive file filtering
const diffs = await github.getPRDiff('anthropics', 'claude-code', 42);
// Returns: [{ filename: 'src/app.ts', status: 'modified', additions: 10, deletions: 5,
//            patch: '@@ -1,5 +1,10 @@\n-old line\n+new line' }]
// Note: Automatically excludes .env, .pem, .key files

// Get changed files list (lightweight, no patches)
const files = await github.getChangedFilesList('owner', 'repo', 'v1.0.0', 'v1.1.0');
// Returns: [{ filename: 'src/app.ts', status: 'modified', additions: 10, deletions: 5 }]

// Fetch linked issues from PR
const pr = await github.getPR('owner', 'repo', 42);
const issue = await github.getIssue('owner', 'repo', 15);
// Returns: { number: 15, title: 'Bug report', body: '...', state: 'closed', ... }
```

--------------------------------

### Public Changelog Feed - TypeScript

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Provides access to a public feed of published changelog entries for a repository. It uses the GET /api/changelog endpoint, allowing pagination with 'page' and 'limit' query parameters. The response contains an array of changelog entries and pagination details, including the current page, limit, total entries, and total pages.

```typescript
// GET /api/changelog?repositoryId=abc-123&page=1&limit=10 - Public published entries

const response = await fetch('/api/changelog?page=1&limit=10');

const data = await response.json();
// Returns: {
//   entries: [{ id: 'uuid', title: '...', content: '...', published_at: '...',
//               repositories: { full_name: 'anthropics/claude-code' } }],
//   pagination: { page: 1, limit: 10, total: 25, totalPages: 3 }
// }
```

--------------------------------

### List Repositories

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieve a list of connected or all GitHub repositories, including their connection status and indexing information.

```APIDOC
## GET /api/repos

### Description
List connected repositories (if `connected=true` query parameter is used) or all GitHub repositories with their connection status.

### Method
GET

### Endpoint
/api/repos

### Parameters
#### Query Parameters
- **connected** (boolean) - Optional - If `true`, only lists repositories that are connected.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the repository.
- **owner** (string) - The owner of the GitHub repository.
- **name** (string) - The name of the GitHub repository.
- **codebase_index** (object) - Information about the codebase index.
- **indexed_at** (string) - Timestamp indicating when the repository was last indexed.

#### Response Example
```json
[
  {
    "id": "uuid",
    "owner": "anthropics",
    "name": "claude-code",
    "codebase_index": { ... },
    "indexed_at": "2025-01-15T10:30:00Z"
  }
]
```
```

--------------------------------

### List Releases

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves a list of GitHub releases for a specified repository.

```APIDOC
## GET /api/repos/[id]/releases

### Description
Get GitHub releases for repository.

### Method
GET

### Endpoint
/api/repos/[id]/releases

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the repository.

### Response
#### Success Response (200)
- **tag_name** (string) - The tag name of the release.
- **name** (string) - The name of the release.
- **body** (string) - The release notes body.
- **published_at** (string) - The timestamp when the release was published.
- **html_url** (string) - The URL to the release on GitHub.

#### Response Example
```json
[
  {
    "tag_name": "v1.2.0",
    "name": "Version 1.2.0",
    "body": "...",
    "published_at": "2025-01-15T10:00:00Z",
    "html_url": "..."
  }
]
```
```

--------------------------------

### Connect Repository

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Connect a GitHub repository to Varia and initiate the codebase indexing process. This endpoint is used to onboard new repositories into the system.

```APIDOC
## POST /api/repos

### Description
Connect a GitHub repository and trigger initial codebase indexing.

### Method
POST

### Endpoint
/api/repos

### Parameters
#### Request Body
- **githubId** (integer) - Required - The GitHub repository ID.
- **owner** (string) - Required - The owner of the GitHub repository.
- **name** (string) - Required - The name of the GitHub repository.
- **fullName** (string) - Required - The full name of the GitHub repository (owner/name).
- **defaultBranch** (string) - Required - The default branch of the repository.

### Request Example
```json
{
  "githubId": 123456789,
  "owner": "anthropics",
  "name": "claude-code",
  "fullName": "anthropics/claude-code",
  "defaultBranch": "main"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the connected repository.
- **github_id** (integer) - The GitHub repository ID.
- **owner** (string) - The owner of the GitHub repository.
- **name** (string) - The name of the GitHub repository.
- **indexing_at** (string) - Timestamp indicating when indexing started.
- **indexing_step** (integer) - The current step in the indexing process.

#### Response Example
```json
{
  "id": "uuid",
  "github_id": 123456789,
  "owner": "anthropics",
  "name": "claude-code",
  "indexing_at": "2025-01-15T10:00:00Z",
  "indexing_step": 1
}
```
```

--------------------------------

### Connect GitHub Repository API

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Connects a GitHub repository to the Varia system and initiates the codebase indexing process. It requires repository details and authentication via a session cookie. The response includes initial indexing status.

```typescript
const response = await fetch('/api/repos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cookie': 'next-auth.session-token=...'
  },
  body: JSON.stringify({
    githubId: 123456789,
    owner: 'anthropics',
    name: 'claude-code',
    fullName: 'anthropics/claude-code',
    defaultBranch: 'main'
  })
});

const repo = await response.json();
// Returns: { id: 'uuid', github_id: 123456789, owner: 'anthropics', name: 'claude-code',
//           indexing_at: '2025-01-15T10:00:00Z', indexing_step: 1, ... }
```

--------------------------------

### Generate Initial Release

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Generates an introductory changelog for the first release of a repository. This endpoint does not require any existing commits.

```APIDOC
## POST /api/repos/[id]/generate

### Description
Generate intro for first release (no commits needed).

### Method
POST

### Endpoint
/api/repos/[id]/generate

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the repository.

#### Request Body
- **sourceType** (string) - Required - Must be 'initial_release'.
- **sourceRef** (string) - Optional - Reference for the source.

### Request Example
```json
{
  "sourceType": "initial_release",
  "sourceRef": ""
}
```

### Response
#### Success Response (200)
- **title** (string) - The title of the changelog.
- **content** (string) - The markdown content of the changelog.
- **sourceType** (string) - The type of source used.
- **sourceRef** (string) - The reference for the source.
- **includedCommits** (array) - An array of included commit SHAs.

#### Response Example
```json
{
  "title": "Introducing claude-code",
  "content": "## What is it?\n\n...",
  "sourceType": "initial_release",
  "sourceRef": "",
  "includedCommits": []
}
```
```

--------------------------------

### Generate Initial Release - TypeScript

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Generates an introductory changelog for the first release of a repository. It makes a POST request to the /api/repos/[id]/generate endpoint. This endpoint does not require any prior commits. The response includes the generated title and content for the changelog, along with source information.

```typescript
// POST /api/repos/[id]/generate - Generate intro for first release (no commits needed)

const response = await fetch('/api/repos/abc-123/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sourceType: 'initial_release',
    sourceRef: ''
  })
});

const changelog = await response.json();
// Returns: { title: 'Introducing claude-code', content: '## What is it?\n\n...',
//            sourceType: 'initial_release', sourceRef: '', includedCommits: [] }
```

--------------------------------

### TypeScript CodebaseIndex Structure

Source: https://github.com/hpottipati/greptile-takehome/blob/main/INDEXING.md

Defines the structure of the CodebaseIndex, an object that summarizes the analyzed codebase. It includes project type, summary, primary language, key directories, user-facing and internal areas, and what users typically care about. This index is stored and used for changelog generation.

```typescript
{
  project_type: "Next.js web application",
  summary: "AI changelog generator that...",
  primary_language: "TypeScript",
  key_directories: { "src/app": "Pages", "src/lib": "Utilities" },
  user_facing_areas: ["src/app", "src/components"],
  internal_areas: ["src/lib/utils"],
  what_users_care_about: "New features, UI changes, breaking changes"
}
```

--------------------------------

### List Repositories API

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves a list of connected GitHub repositories or all GitHub repositories with their connection status. Requires authentication via a session cookie. The response includes repository details and indexing information.

```typescript
const response = await fetch('/api/repos?connected=true', {
  headers: { 'Cookie': 'next-auth.session-token=...' }
});

const repos = await response.json();
// Returns: [{ id: 'uuid', owner: 'anthropics', name: 'claude-code',
//            codebase_index: {...}, indexed_at: '2025-01-15T10:30:00Z', ... }]
```

--------------------------------

### Supabase Client Database Access with RLS (TypeScript)

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Demonstrates how to use Supabase clients for authenticated, anonymous, and service-level database access. The authenticated client respects Row Level Security (RLS), the anonymous client provides public read access, and the service client bypasses RLS for trusted operations. Ensure RLS policies are correctly configured in Supabase.

```typescript
import { createAuthenticatedClient, createAnonClient, createServiceClient } from '@/lib/supabase/server';

// 1. Authenticated client - respects RLS, signs custom JWT
const supabase = createAuthenticatedClient(userId);
const { data: repos } = await supabase
  .from('repositories')
  .select('*')
  .eq('user_id', userId);
// Returns only repositories owned by userId due to RLS policy

// 2. Anonymous client - public read access
const anonClient = await createAnonClient();
const { data: entries } = await anonClient
  .from('changelog_entries')
  .select('*')
  .eq('status', 'published');
// Returns all published entries (RLS allows public read)

// 3. Service client - bypasses RLS (use only in trusted contexts)
const serviceClient = createServiceClient();
await serviceClient
  .from('repositories')
  .update({ codebase_index: index })
  .eq('id', repoId)
  .eq('user_id', userId); // Manual ownership check required
```

--------------------------------

### Create Changelog Entry

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Saves a generated changelog entry as either a draft or publishes it.

```APIDOC
## POST /api/entries

### Description
Save generated changelog as draft or publish.

### Method
POST

### Endpoint
/api/entries

### Parameters
#### Request Body
- **repositoryId** (string) - Required - The ID of the repository.
- **title** (string) - Required - The title of the changelog entry.
- **content** (string) - Required - The markdown content of the changelog entry.
- **sourceType** (string) - Required - The type of source (e.g., 'release').
- **sourceRef** (string) - Required - The reference for the source (e.g., version tag).
- **status** (string) - Required - The status of the entry ('draft' or 'published').
- **version** (string) - Optional - The version number.
- **includedCommits** (array) - Optional - An array of commit SHAs included.

### Request Example
```json
{
  "repositoryId": "abc-123",
  "title": "Release v1.2.0",
  "content": "## What Changed\n\nAdded dark mode support...",
  "sourceType": "release",
  "sourceRef": "v1.2.0",
  "status": "draft",
  "version": "1.2.0",
  "includedCommits": ["sha1", "sha2"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the changelog entry.
- **repository_id** (string) - The ID of the associated repository.
- **title** (string) - The title of the changelog entry.
- **status** (string) - The status of the entry.
- **created_at** (string) - The timestamp when the entry was created.

#### Response Example
```json
{
  "id": "uuid",
  "repository_id": "abc-123",
  "title": "...",
  "status": "draft",
  "created_at": "2025-01-15T11:00:00Z"
}
```
```

--------------------------------

### IndexerService: Analyze Codebase (Agentic and Legacy Modes)

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Initializes IndexerService for multi-agent codebase analysis. Supports agentic mode for detailed analysis with progress tracking and a legacy mode for faster, less accurate indexing. Requires an access token and a boolean to select the mode.

```typescript
import { IndexerService } from '@/lib/services/indexer';

const indexer = new IndexerService(accessToken, true); // true = agentic mode (default)

// Index repository with progress tracking
const codebaseIndex = await indexer.indexRepository('anthropics', 'claude-code',
  async (step) => {
    console.log(`Indexing step ${step}/5`);
    // Steps: 1=structure, 2=parallel agents, 3=synthesis, 4=validation, 5=complete
    await updateDatabase({ indexing_step: step });
  }
);

// Result structure
const result = codebaseIndex;
// Returns: {
//   project_type: 'Next.js web application',
//   summary: 'AI-powered changelog generator with multi-agent analysis...',
//   primary_language: 'TypeScript',
//   key_directories: {
//     'src/app': 'Next.js app router pages and API routes',
//     'src/lib': 'Shared utilities and services',
//     'src/components': 'React UI components'
//   },
//   user_facing_areas: ['src/app', 'src/components'],
//   internal_areas: ['src/lib/utils', 'src/lib/cache'],
//   what_users_care_about: 'New features, UI improvements, bug fixes, breaking changes'
// }

// Legacy mode (faster, less accurate)
const legacyIndexer = new IndexerService(accessToken, false);
const index = await legacyIndexer.indexRepository('owner', 'repo');
```

--------------------------------

### IndexerService - Multi-Agent Codebase Analysis

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Analyzes codebases using AI agents to provide structured insights about project type, summary, languages, and key directories.

```APIDOC
## IndexerService - Multi-Agent Codebase Analysis

### Description
Analyzes codebases using AI agents to provide structured insights about project type, summary, languages, and key directories. Supports agentic (default) and legacy modes.

### Methods

#### Index Repository

- **Method**: `POST`
- **Endpoint**: `/indexer/repository` (Implicit)
- **Description**: Indexes a given repository, performing structure analysis, agentic processing, synthesis, and validation. Supports progress tracking via a callback.
- **Parameters**:
  - `owner` (string) - Required - The owner of the repository.
  - `repo` (string) - Required - The name of the repository.
  - `progressCallback` (function) - Optional - A callback function to receive progress updates during indexing (e.g., `async (step) => { console.log(`Indexing step ${step}/5`); }`).
  - `agenticMode` (boolean) - Optional - Defaults to `true`. If `false`, uses a faster, less accurate legacy mode.
- **Request Example**:
```typescript
const indexer = new IndexerService(accessToken, true); // agentic mode
const codebaseIndex = await indexer.indexRepository('anthropics', 'claude-code',
  async (step) => { console.log(`Indexing step ${step}/5`); });
```
- **Response Example**:
```json
{
  "project_type": "Next.js web application",
  "summary": "AI-powered changelog generator with multi-agent analysis...",
  "primary_language": "TypeScript",
  "key_directories": {
    "src/app": "Next.js app router pages and API routes",
    "src/lib": "Shared utilities and services",
    "src/components": "React UI components"
  },
  "user_facing_areas": ["src/app", "src/components"],
  "internal_areas": ["src/lib/utils", "src/lib/cache"],
  "what_users_care_about": "New features, UI improvements, bug fixes, breaking changes"
}
```
```

--------------------------------

### AgenticIndexerService for Parallel Code Analysis (TypeScript)

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Utilizes the AgenticIndexerService for advanced, multi-agent parallel analysis of code repositories. This service breaks down the indexing process into stages, leveraging specialized agents for different tasks like structure analysis, documentation generation, and code sampling. It supports progress callbacks and requires an access token for operation.

```typescript
import { AgenticIndexerService } from '@/lib/services/agentic-indexer';

const indexer = new AgenticIndexerService(accessToken);

const codebaseIndex = await indexer.indexRepository('owner', 'repo',
  async (step, message) => {
    console.log(`Step ${step}: ${message}`);
    // Progress: 1=pre-analysis, 2=parallel agents, 3=synthesis,
    //           4=validation, 5=complete
  }
);

// Internal flow:
// 1. Pre-analysis: Classifies source vs dependencies from file tree stats
// 2. Parallel agents: Structure (15 steps), Docs (10 steps), Code Sampler (20 steps)
// 3. Synthesis: Merges findings into structured CodebaseIndex
// 4. Evaluator-optimizer: Scores quality (7/10 threshold), re-generates if needed
// 5. Returns validated index

// Each agent has access to tools: listFiles, readFile, analyzeDirectory, recordFindings
// AI infers project structure without hardcoded patterns (e.g., auto-detects node_modules)
```

--------------------------------

### GitHubService - Repository Data Access

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Provides methods to interact with GitHub repositories, including fetching repositories, commits, pull request diffs, and issues.

```APIDOC
## GitHubService - Repository Data Access

### Description
Provides methods to interact with GitHub repositories, including fetching repositories, commits, pull request diffs, and issues.

### Methods

#### Get User Repositories

- **Method**: `GET`
- **Endpoint**: `/github/repos` (Implicit, when `github.getRepos()` is called)
- **Description**: Fetches a list of repositories accessible by the authenticated user.
- **Request Example**: `const repos = await github.getRepos();`
- **Response Example**:
```json
[
  { "id": 123, "name": "repo", "owner": "user", "full_name": "user/repo", ... }
]
```

#### Get Commits

- **Method**: `GET`
- **Endpoint**: `/github/repos/{owner}/{repo}/commits` (Implicit)
- **Description**: Fetches commits for a specific repository within a date range.
- **Parameters**:
  - `owner` (string) - Required - The owner of the repository.
  - `repo` (string) - Required - The name of the repository.
  - `startDate` (string) - Required - The start date for filtering commits (ISO 8601 format).
  - `endDate` (string) - Required - The end date for filtering commits (ISO 8601 format).
- **Request Example**: `const commits = await github.getCommits('anthropics', 'claude-code', '2025-01-01T00:00:00Z', '2025-01-15T23:59:59Z');`
- **Response Example**:
```json
[
  { "sha": "abc123", "message": "...", "author": "User", "date": "...", "html_url": "..." }
]
```

#### Get Pull Request Diff

- **Method**: `GET`
- **Endpoint**: `/github/repos/{owner}/{repo}/pulls/{prNumber}/diff` (Implicit)
- **Description**: Fetches the diff of a specific pull request, with automatic filtering of sensitive files.
- **Parameters**:
  - `owner` (string) - Required - The owner of the repository.
  - `repo` (string) - Required - The name of the repository.
  - `prNumber` (integer) - Required - The number of the pull request.
- **Request Example**: `const diffs = await github.getPRDiff('anthropics', 'claude-code', 42);`
- **Response Example**:
```json
[
  { "filename": "src/app.ts", "status": "modified", "additions": 10, "deletions": 5, "patch": "@@ -1,5 +1,10 @@\n-old line\n+new line" }
]
```

#### Get Changed Files List

- **Method**: `GET`
- **Endpoint**: `/github/repos/{owner}/{repo}/compare/{baseRef}...{compareRef}/files` (Implicit)
- **Description**: Fetches a lightweight list of changed files between two references (e.g., tags or branches), without full patches.
- **Parameters**:
  - `owner` (string) - Required - The owner of the repository.
  - `repo` (string) - Required - The name of the repository.
  - `baseRef` (string) - Required - The base reference (e.g., tag 'v1.0.0').
  - `compareRef` (string) - Required - The reference to compare against (e.g., tag 'v1.1.0').
- **Request Example**: `const files = await github.getChangedFilesList('owner', 'repo', 'v1.0.0', 'v1.1.0');`
- **Response Example**:
```json
[
  { "filename": "src/app.ts", "status": "modified", "additions": 10, "deletions": 5 }
]
```

#### Get Pull Request Details

- **Method**: `GET`
- **Endpoint**: `/github/repos/{owner}/{repo}/pulls/{prNumber}` (Implicit)
- **Description**: Fetches the details of a specific pull request.
- **Parameters**:
  - `owner` (string) - Required - The owner of the repository.
  - `repo` (string) - Required - The name of the repository.
  - `prNumber` (integer) - Required - The number of the pull request.
- **Request Example**: `const pr = await github.getPR('owner', 'repo', 42);`
- **Response Example**:
```json
{ "number": 42, "title": "Update feature", "state": "open", ... }
```

#### Get Issue Details

- **Method**: `GET`
- **Endpoint**: `/github/repos/{owner}/{repo}/issues/{issueNumber}` (Implicit)
- **Description**: Fetches the details of a specific issue.
- **Parameters**:
  - `owner` (string) - Required - The owner of the repository.
  - `repo` (string) - Required - The name of the repository.
  - `issueNumber` (integer) - Required - The number of the issue.
- **Request Example**: `const issue = await github.getIssue('owner', 'repo', 15);`
- **Response Example**:
```json
{ "number": 15, "title": "Bug report", "body": "...", "state": "closed", ... }
```
```

--------------------------------

### GeneratorService: Generate Changelogs (Release and Commit-based)

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Initializes GeneratorService with a GitHub access token for AI-powered changelog generation. Supports generating changelogs from releases (comparing against previous, specific versions, or the beginning) and from selected commits with AI-generated titles. Requires repository owner, name, codebase index, and generation options.

```typescript
import { GeneratorService } from '@/lib/services/generator';
import type { CodebaseIndex } from '@/types/database';

const generator = new GeneratorService(accessToken);
const codebaseIndex: CodebaseIndex = { /* from IndexerService */ };

// Generate from release with comparison options
const changelog = await generator.generateChangelog(
  'anthropics', 'claude-code', codebaseIndex,
  {
    sourceType: 'release',
    sourceRef: 'v1.2.0',
    compareAgainst: 'previous' // or 'specific', 'beginning'
  }
);
// Returns: { title: 'Release v1.2.0', content: '## What Changed\n\n...',
//            sourceType: 'release', sourceRef: 'v1.2.0', includedCommits: [...] }

// Generate from selected commits with AI-generated title
const commitLog = await generator.generateChangelog(
  'owner', 'repo', codebaseIndex,
  {
    sourceType: 'commits',
    sourceRef: '', // not used when selectedCommits provided
    selectedCommits: ['sha1', 'sha2', 'sha3']
  }
);
// Returns: { title: 'Authentication System Improvements', content: '...', ... }
```

--------------------------------

### List Changelog Entries

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves a list of changelog entries for a given repository, filterable by status.

```APIDOC
## GET /api/entries

### Description
List user's entries.

### Method
GET

### Endpoint
/api/entries

### Parameters
#### Query Parameters
- **repositoryId** (string) - Required - The ID of the repository to filter by.
- **status** (string) - Optional - The status of the entries to list ('draft' or 'published').

### Request Example
```
/api/entries?repositoryId=abc-123&status=draft
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the changelog entry.
- **title** (string) - The title of the changelog entry.
- **content** (string) - The markdown content of the changelog entry.
- **status** (string) - The status of the entry.
- **repositories** (object) - Information about the repository.
  - **full_name** (string) - The full name of the repository.

#### Response Example
```json
[
  {
    "id": "uuid",
    "title": "Release v1.2.0",
    "content": "...",
    "status": "draft",
    "repositories": {
      "full_name": "anthropics/claude-code",
      "...": "..."
    }
  }
]
```
```

--------------------------------

### Generate Changelog (Release)

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Generate a changelog based on a specific GitHub release. This allows creating release notes from a tagged version.

```APIDOC
## POST /api/repos/[id]/generate (Release)

### Description
Generate a changelog from a specific GitHub release. You can compare the release against the previous one or a specific tag.

### Method
POST

### Endpoint
/api/repos/:id/generate

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the repository.

#### Request Body
- **sourceType** (string) - Required - The type of source to generate the changelog from. Must be 'release'.
- **sourceRef** (string) - Required - The tag name of the GitHub release (e.g., 'v1.2.0').
- **compareAgainst** (string) - Required - Specifies what to compare against. Options: 'previous', 'specific', 'beginning'.
- **compareAgainstTag** (string) - Optional - If `compareAgainst` is 'specific', this is the tag name to compare against (e.g., 'v1.0.0').

### Request Example
```json
{
  "sourceType": "release",
  "sourceRef": "v1.2.0",
  "compareAgainst": "previous", 
  "compareAgainstTag": "v1.0.0" 
}
```

### Response
#### Success Response (200)
- **title** (string) - The title of the changelog (e.g., 'Release v1.2.0').
- **content** (string) - The generated changelog content in markdown format.
- **sourceType** (string) - The type of source used ('release').
- **sourceRef** (string) - The reference used for the source (release tag).
- **includedCommits** (array) - An array of commit SHAs included in the changelog.

#### Response Example
```json
{
  "title": "Release v1.2.0",
  "content": "## What Changed\n\n...",
  "sourceType": "release",
  "sourceRef": "v1.2.0",
  "includedCommits": ["sha1", "sha2"]
}
```
```

--------------------------------

### Generate Changelog (Streaming)

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Generate a changelog from a list of specified commits and stream the content as it is generated. This allows for real-time feedback during generation.

```APIDOC
## POST /api/repos/[id]/generate (Streaming)

### Description
Generate a changelog from a list of selected commits and stream the content. This endpoint provides real-time updates as the changelog is being generated.

### Method
POST

### Endpoint
/api/repos/:id/generate

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the repository.

#### Request Body
- **sourceType** (string) - Required - The type of source to generate the changelog from. Must be 'commits'.
- **selectedCommits** (array) - Required - An array of commit SHAs to include in the changelog.
- **stream** (boolean) - Required - Set to `true` to enable streaming of the changelog content.

### Request Example
```json
{
  "sourceType": "commits",
  "selectedCommits": ["sha1", "sha2", "sha3"],
  "stream": true
}
```

### Response
#### Success Response (200)
- The response body will be a stream of text chunks representing the changelog content as it's generated.

#### Response Example
```
## What Changed

- ... (partial content)
```

*(Note: The full changelog is assembled by concatenating the streamed chunks.)*
```

--------------------------------

### Create Changelog Entry - TypeScript

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Saves a generated changelog entry, either as a draft or publishes it. It uses the POST /api/entries endpoint. This function requires repository ID, title, content, source type and reference, status, version, and optionally included commits. The response includes the created entry's ID, repository ID, title, status, and creation timestamp.

```typescript
// POST /api/entries - Save generated changelog as draft or publish

const response = await fetch('/api/entries', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    repositoryId: 'abc-123',
    title: 'Release v1.2.0',
    content: '## What Changed\n\nAdded dark mode support...', 
    sourceType: 'release',
    sourceRef: 'v1.2.0',
    status: 'draft', // or 'published'
    version: '1.2.0',
    includedCommits: ['sha1', 'sha2']
  })
});

const entry = await response.json();
// Returns: { id: 'uuid', repository_id: 'abc-123', title: '...', status: 'draft',
//            created_at: '2025-01-15T11:00:00Z', ... }
```

--------------------------------

### Public Changelog Feed

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Retrieves a paginated list of published changelog entries for public consumption.

```APIDOC
## GET /api/changelog

### Description
Public published entries.

### Method
GET

### Endpoint
/api/changelog

### Parameters
#### Query Parameters
- **repositoryId** (string) - Optional - The ID of the repository to filter by.
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **limit** (integer) - Optional - The number of entries per page. Defaults to 10.

### Request Example
```
/api/changelog?page=1&limit=10
```

### Response
#### Success Response (200)
- **entries** (array) - An array of published changelog entries.
  - **id** (string) - The unique identifier for the changelog entry.
  - **title** (string) - The title of the changelog entry.
  - **content** (string) - The markdown content of the changelog entry.
  - **published_at** (string) - The timestamp when the entry was published.
  - **repositories** (object) - Information about the repository.
    - **full_name** (string) - The full name of the repository.
- **pagination** (object) - Pagination details.
  - **page** (integer) - The current page number.
  - **limit** (integer) - The number of entries per page.
  - **total** (integer) - The total number of entries available.
  - **totalPages** (integer) - The total number of pages.

#### Response Example
```json
{
  "entries": [
    {
      "id": "uuid",
      "title": "...",
      "content": "...",
      "published_at": "...",
      "repositories": {
        "full_name": "anthropics/claude-code"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}
```
```

--------------------------------

### Generate Changelog from Release API

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Generates a changelog based on a specific GitHub release. Users can specify the release tag and how to compare it against previous versions. Requires JSON content type and returns the changelog title, content, and included commits.

```typescript
const response = await fetch('/api/repos/[id]/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sourceType: 'release',
    sourceRef: 'v1.2.0',
    compareAgainst: 'previous', // or 'specific', 'beginning'
    compareAgainstTag: 'v1.0.0' // only if compareAgainst === 'specific'
  })
});

const changelog = await response.json();
// Returns: { title: 'Release v1.2.0', content: '## What Changed\n\n...',
//            sourceType: 'release', sourceRef: 'v1.2.0', includedCommits: ['sha1', 'sha2'] }
```

--------------------------------

### GeneratorService: Stream Changelog Generation

Source: https://context7.com/hpottipati/greptile-takehome/llms.txt

Enables streaming changelog generation for real-time UI updates using GeneratorService. This method allows for consuming changelog content as it's generated, improving user experience. It also outlines an agentic flow for efficient diff fetching. Requires repository owner, name, codebase index, and generation options.

```typescript
import { GeneratorService } from '@/lib/services/generator';
import type { CodebaseIndex } from '@/types/database';

const generator = new GeneratorService(accessToken);
const codebaseIndex: CodebaseIndex = { /* from IndexerService */ };

// Stream generation for real-time UI updates
const stream = await generator.streamChangelog(
  'owner', 'repo', codebaseIndex,
  { sourceType: 'pr', sourceRef: '42' }
);

// Consume stream
const reader = stream.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

// Agentic flow: automatically filters relevant files before fetching diffs
// 1. Fetches lightweight file list (no patches)
// 2. AI analyzes which files matter to users based on codebase index
// 3. Fetches full diffs only for relevant files (reduces token usage)
```