> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/clyrisai/gitresolve/llms.txt
> Use this file to discover all available pages before exploring further.

# GitResolve Programmatic API — Complete Reference

> Install @clyrisai/gitresolve and use its full programmatic API to resolve portfolio URLs, resume PDFs, and git links into structured profiles.

The GitResolve programmatic API gives you direct access to every stage of the resolution pipeline — input classification, portfolio scraping, resume parsing, owner disambiguation, and browser provider management — so you can integrate candidate profile extraction into any Node.js application. While the CLI is ideal for one-off or shell-based workflows, the library API is designed for systems that need to process multiple candidates concurrently, persist results, or compose custom pipelines.

## Installation

```bash theme={null}
npm install @clyrisai/gitresolve
```

GitResolve requires **Node.js 18 or later** (native `fetch` and `ReadableStream` are used internally). For full JavaScript-rendered portfolio scraping you will also want a browser peer dependency:

```bash theme={null}
# Option A — local headless Chrome
npm install puppeteer

# Option B — point at a running Browserless instance (no extra npm dep)
export BROWSERLESS_URL=http://localhost:3000
```

## Canonical integration pattern

The most common production pattern combines `createProvider`, `scrapePortfolio`, and `parseResume`. Always call `provider.cleanup()` in a `finally` block so browser processes are never left dangling.

```typescript theme={null}
import {
  createProvider,
  scrapePortfolio,
  parseResume,
} from '@clyrisai/gitresolve';

const provider = await createProvider(); // auto-detects best available

try {
  const [portfolioResult, resumeResult] = await Promise.all([
    scrapePortfolio('https://janedoe.dev', provider),
    parseResume('./resumes/janedoe.pdf'),
  ]);

  console.log('Portfolio owner:', portfolioResult.ownerProfile?.username);
  console.log('Confidence:',     portfolioResult.confidence);
  console.log('Owned repos:',    portfolioResult.ownedRepos.length);

  console.log('Resume owner:',   resumeResult.ownerProfile?.username);
  console.log('Warnings:',       resumeResult.warnings);
} finally {
  await provider.cleanup();
}
```

<Note>
  Neither `scrapePortfolio` nor `parseResume` ever throws. Any failure is captured in `result.error` so a `try/finally` around `cleanup()` is sufficient — you do not need a `catch` block for the resolution functions themselves.
</Note>

## Export reference

All public exports are grouped below. Click any category to jump to the dedicated reference page.

### Classifier

| Export                   | Kind     | Description                                                                    |
| ------------------------ | -------- | ------------------------------------------------------------------------------ |
| `classifyInput`          | function | Categorise any string as a repo URL, git profile, portfolio, resume file, etc. |
| `parseRepoUrl`           | function | Fully parse a GitHub / GitLab / Bitbucket repo URL into structured data        |
| `parseGitLink`           | function | Classify a raw git-provider URL as profile, repo, gist, PR, or issue           |
| `extractGitUrlsFromText` | function | Regex-extract all git provider URLs from a block of plain text                 |
| `isGitProviderUrl`       | function | Boolean check — is this URL on a supported git host?                           |
| `GIT_HOSTS`              | constant | Map of recognised hostnames to `GitProvider` values                            |

### Portfolio Scraper

| Export                 | Kind           | Description                                               |
| ---------------------- | -------------- | --------------------------------------------------------- |
| `scrapePortfolio`      | async function | Fetch a portfolio page and return a full `ResolverResult` |
| `extractLinksFromHtml` | function       | Pull all `href` values and git URLs out of raw HTML       |

### Resume Parser

| Export        | Kind           | Description                                                 |
| ------------- | -------------- | ----------------------------------------------------------- |
| `parseResume` | async function | Parse a local PDF resume and return a full `ResolverResult` |

### Disambiguator

| Export                      | Kind     | Description                                                              |
| --------------------------- | -------- | ------------------------------------------------------------------------ |
| `resolveOwnerAndCategorize` | function | Determine the candidate owner from a list of `ExtractedGitLink` objects  |
| `dedupeProfilesByUsername`  | function | Remove duplicate profile links with the same username (case-insensitive) |

### Browser providers

| Export                   | Kind           | Description                                                  |
| ------------------------ | -------------- | ------------------------------------------------------------ |
| `createProvider`         | async function | Auto-detect or explicitly select a `BrowserProvider`         |
| `FetchProvider`          | class          | Plain `fetch`-based provider, always available               |
| `PuppeteerProvider`      | class          | Full headless Chrome via Puppeteer                           |
| `BrowserlessProvider`    | class          | Full JS rendering via a Browserless REST endpoint            |
| `BrowserProvider`        | interface      | The common contract every provider implements                |
| `BrowserProviderOptions` | interface      | `timeout` and `waitUntil` options passed to `getPageContent` |
| `ProviderName`           | type           | `'puppeteer' \| 'browserless' \| 'fetch'`                    |

### Types

| Export             | Kind      | Description                                                           |
| ------------------ | --------- | --------------------------------------------------------------------- |
| `InputType`        | type      | Union of possible input classifications                               |
| `GitProvider`      | type      | `'github' \| 'gitlab' \| 'bitbucket'`                                 |
| `GitLinkType`      | type      | Union of link classifications (profile, repo, gist, PR, issue, other) |
| `ParsedRepo`       | interface | Structured data from a parsed repo URL                                |
| `ExtractedGitLink` | interface | A single classified git URL with username, repo, and type             |
| `ResolverResult`   | interface | Complete resolution output for one source                             |

***

## API pages

<CardGroup cols={2}>
  <Card title="Classifier" icon="tag" href="/api/classify-input">
    `classifyInput`, `parseRepoUrl`, `parseGitLink`, `extractGitUrlsFromText`, `isGitProviderUrl`, and `GIT_HOSTS`
  </Card>

  <Card title="Portfolio Scraper" icon="globe" href="/api/scrape-portfolio">
    `scrapePortfolio` and `extractLinksFromHtml`
  </Card>

  <Card title="Resume Parser" icon="file-pdf" href="/api/parse-resume">
    `parseResume` — dual-method PDF extraction with `unpdf`
  </Card>

  <Card title="Disambiguator" icon="user-check" href="/api/resolve-owner">
    `resolveOwnerAndCategorize` and `dedupeProfilesByUsername`
  </Card>

  <Card title="createProvider" icon="browser" href="/api/create-provider">
    Browser provider factory, all three provider classes, and the `BrowserProvider` interface
  </Card>

  <Card title="Types" icon="brackets-curly" href="/api/types">
    Complete TypeScript type reference for every exported interface and union type
  </Card>
</CardGroup>