TypeScript Types Reference for @clyrisai/gitresolve

This page is the canonical reference for every TypeScript type exported by @clyrisai/gitresolve. All types are pure interfaces and union types — there are no classes to instantiate unless you are implementing a custom BrowserProvider. Import only what you need; tree-shaking eliminates unused type imports at compile time.

Importing types

Use import type to ensure types are erased at runtime and do not bloat your bundle:

import type {
  InputType,
  GitProvider,
  GitLinkType,
  ParsedRepo,
  ExtractedGitLink,
  ResolverResult,
  BrowserProvider,
  BrowserProviderOptions,
  ProviderName,
} from '@clyrisai/gitresolve';

AggregatedResult is defined in the package’s types.ts source file but is not re-exported from the public package index. It is not importable from @clyrisai/gitresolve at runtime. Its shape is documented below for reference when working with aggregation patterns, but you cannot use import type { AggregatedResult } in your own code.

The GIT_HOSTS constant is a runtime value and must be imported without the type modifier:

import { GIT_HOSTS } from '@clyrisai/gitresolve';

InputType

InputType classifies what kind of source was passed to the resolver. It is set on ResolverResult.sourceType so downstream code can decide how to handle each result.

type InputType =
  | 'repo_url'
  | 'git_profile'
  | 'portfolio'
  | 'resume_file'
  | 'resume_url'
  | 'linkedin'
  | 'unknown';

'repo_url'

InputType

A GitHub, GitLab, or Bitbucket repository URL (e.g. https://github.com/owner/repo). The resolver extracts the owner profile and treats the repo as an owned repository.

'git_profile'

InputType

A GitHub, GitLab, or Bitbucket profile URL (e.g. https://github.com/janedoe). Direct profile links yield the highest confidence scores.

'portfolio'

InputType

Any website that is not itself a git host URL (e.g. https://janedoe.dev). The resolver scrapes the page for embedded git links using the configured BrowserProvider.

'resume_file'

InputType

A local file path pointing to a resume document (.pdf, .doc, .docx, or .rtf). The file is read from disk and its text content is scanned for git links.

'resume_url'

InputType

A remote PDF URL. Set by the CLI after the PDF has been downloaded to a temp file and parsed. Functionally equivalent to 'resume_file' in resolver output.

'linkedin'

InputType

A LinkedIn profile URL. GitResolve recognises LinkedIn URLs and records them, but does not scrape or resolve LinkedIn pages. The result will contain no extracted git links from this source.

'unknown'

InputType

The input could not be classified. This typically means the URL scheme is unrecognised or the string is not a valid URL or file path. Inspect ResolverResult.warnings for details.

GitProvider

Identifies the hosting platform of a git link or repository.

type GitProvider = 'github' | 'gitlab' | 'bitbucket';

'github'

GitProvider

GitHub — github.com or www.github.com.

'gitlab'

GitProvider

GitLab — gitlab.com or www.gitlab.com.

'bitbucket'

GitProvider

Bitbucket — bitbucket.org or www.bitbucket.org.

GitLinkType

Classifies the kind of page a git URL points to within its host platform.

type GitLinkType = 'profile' | 'repo' | 'gist' | 'pull_request' | 'issue' | 'other';

'profile'

GitLinkType

A user or organization profile page (e.g. https://github.com/janedoe).

'repo'

GitLinkType

A repository root (e.g. https://github.com/janedoe/my-project).

'gist'

GitLinkType

A GitHub Gist (e.g. https://gist.github.com/janedoe/abc123). parseGitLink handles gist.github.com URLs and sets provider to 'github'.

'pull_request'

GitLinkType

A pull request URL. When present, ExtractedGitLink.number holds the PR number.

'issue'

GitLinkType

An issue URL. When present, ExtractedGitLink.number holds the issue number.

'other'

GitLinkType

Any other URL on a recognised git host that does not match the patterns above (e.g. a wiki page, a release asset, or a raw file URL).

ParsedRepo

A low-level representation of a parsed repository URL, produced by the URL parsing layer before link classification. Contains every component of the URL path in decomposed form.

interface ParsedRepo {
  provider: GitProvider;
  host: string;
  owner: string;
  repo: string;
  fullPath: string;
  normalized: string;
  contribution?: { type: 'pull_request' | 'issue'; number: string };
}

provider

GitProvider

required

The hosting platform inferred from the URL’s hostname.

host

string

required

The raw hostname from the URL (e.g. 'github.com', 'www.gitlab.com').

owner

string

required

The repository owner’s username or organization name extracted from the URL path.

repo

string

required

The repository name extracted from the URL path.

fullPath

string

required

The full owner/repo path segment as it appears in the URL.

normalized

string

required

A canonical HTTPS URL for the repository, stripped of trailing slashes and query parameters (e.g. 'https://github.com/janedoe/my-project').

contribution

{ type: 'pull_request' | 'issue'; number: string }

Present when the URL points to a pull request or issue within the repository. type distinguishes between the two; number is the numeric ID as a string.

Show contribution fields

type

'pull_request' | 'issue'

required

Whether the link is a pull request or an issue.

number

string

required

The PR or issue number as a string (e.g. '42').

ExtractedGitLink

The primary unit of resolver output. Represents a single git link found in a source, fully parsed and classified.

interface ExtractedGitLink {
  url: string;
  provider: GitProvider;
  type: GitLinkType;
  username: string;
  repo?: string;
  number?: string;
}

url

string

required

The normalized, canonical HTTPS URL for the link (trailing slashes removed, query parameters stripped).

provider

GitProvider

required

The hosting platform for this link.

type

GitLinkType

required

The kind of page this URL points to on its platform.

username

string

required

The profile owner or repository owner’s username as extracted from the URL. For a repository URL this is the repo owner, not necessarily the candidate.

repo

string

The repository name. Present when type is 'repo', 'pull_request', or 'issue'; absent for 'profile' and 'gist' links.

number

string

The pull request or issue number as a string. Present only when type is 'pull_request' or 'issue'.

ResolverResult

The complete output for a single resolved source (one URL, file path, or input string). Contains the candidate’s inferred profile, confidence score, and all extracted links partitioned into meaningful categories.

interface ResolverResult {
  source: string;
  sourceType: InputType;
  ownerProfile: ExtractedGitLink | null;
  confidence: 'high' | 'medium' | 'low' | 'none';
  ownedRepos: ExtractedGitLink[];
  contributions: ExtractedGitLink[];
  externalRepos: ExtractedGitLink[];
  allLinks: ExtractedGitLink[];
  warnings: string[];
  error?: string;
}

source

string

required

The original input string passed to the resolver — a URL, a local file path, or a raw string. Used to trace a result back to its origin.

sourceType

InputType

required

The classified type of source. Set during input parsing before any network activity occurs.

ownerProfile

ExtractedGitLink | null

required

The best-guess ExtractedGitLink representing the candidate’s own git profile, or null if no profile could be identified. A non-null value does not guarantee the profile belongs to this candidate — see confidence.

confidence

'high' | 'medium' | 'low' | 'none'

required

How certain the resolver is that ownerProfile belongs to the candidate:

'high' — the source was a direct git profile URL or a repository URL owned by the candidate.
'medium' — the profile was inferred from multiple corroborating links on a portfolio or resume.
'low' — the profile is a best guess from limited or ambiguous signals.
'none' — no profile could be identified.

ownedRepos

ExtractedGitLink[]

required

Repositories where the extracted username matches the candidate’s resolved username from ownerProfile. These are the repositories most likely to belong to the candidate.

contributions

ExtractedGitLink[]

required

Explicit pull request and issue links found in the source. These signal active open-source contribution activity regardless of repository ownership.

externalRepos

ExtractedGitLink[]

required

Repository links owned by a username that does not match the candidate’s resolved username. These indicate referenced libraries, employer codebases, or other external projects mentioned in the source.

allLinks

ExtractedGitLink[]

required

Every git link extracted from the source, unfiltered and unsorted. This is the superset of ownedRepos, contributions, and externalRepos, plus any links that did not fit a more specific category.

warnings

string[]

required

Non-fatal diagnostic messages accumulated during resolution (e.g. ambiguous profile detection, slow page load, parser heuristic fallbacks). Always an array; empty when resolution was clean.

error

string

Set when a fatal error occurred during resolution (e.g. network failure, unparseable PDF). When present, the other output fields may be partially populated or empty.

AggregatedResult

AggregatedResult is defined in the package source but is not exported from the public package index. You cannot import it from @clyrisai/gitresolve. It is documented here as a reference for its shape, which may be useful if you are building your own aggregation layer on top of multiple ResolverResult objects.

Combines multiple ResolverResult objects — from different sources that were determined to belong to the same candidate — into a single de-duplicated profile. Used when a candidate provides both a portfolio URL and a resume file, for example.

interface AggregatedResult {
  candidateUsername: string | null;
  sources: string[];
  sourceTypes: InputType[];
  ownerProfile: ExtractedGitLink | null;
  confidence: 'high' | 'medium' | 'low' | 'none';
  ownedRepos: ExtractedGitLink[];
  contributions: ExtractedGitLink[];
  externalRepos: ExtractedGitLink[];
  allLinks: ExtractedGitLink[];
  warnings: string[];
}

candidateUsername

string | null

required

The resolved git username for the candidate, or null if the aggregation could not determine a single username. A null value means the sources were either ambiguous (multiple different usernames found) or contained no profile links at all.

sources

string[]

required

All original input strings that were aggregated into this result, in the order they were processed (e.g. ['https://janedoe.dev', './resumes/janedoe.pdf']).

sourceTypes

InputType[]

required

The InputType classification for each entry in sources, at the same index. sources[i] has type sourceTypes[i].

ownerProfile

ExtractedGitLink | null

required

The highest-confidence profile link found across all aggregated sources, or null if none was found.

confidence

'high' | 'medium' | 'low' | 'none'

required

The highest confidence level observed across all aggregated ResolverResult entries. Aggregating multiple sources never lowers confidence below the best individual result.

ownedRepos

ExtractedGitLink[]

required

De-duplicated union of ownedRepos from all aggregated results.

contributions

ExtractedGitLink[]

required

De-duplicated union of contributions from all aggregated results.

externalRepos

ExtractedGitLink[]

required

De-duplicated union of externalRepos from all aggregated results.

allLinks

ExtractedGitLink[]

required

De-duplicated union of every ExtractedGitLink found across all aggregated sources.

warnings

string[]

required

Merged warnings from all aggregated ResolverResult entries. May contain messages from multiple sources.

BrowserProvider

The interface that all browser engine implementations must satisfy. See createProvider for auto-detection and the Custom provider section for how to implement your own.

interface BrowserProvider {
  readonly name: string;
  getPageContent(url: string, options?: BrowserProviderOptions): Promise<string>;
  isAvailable(): Promise<boolean>;
  cleanup(): Promise<void>;
}

name

string

required

Human-readable provider identifier. Built-in values: 'fetch', 'puppeteer', 'browserless'.

getPageContent(url, options?)

Promise<string>

required

Fetches the fully rendered HTML of url. Throws on network errors, non-2xx responses, or timeouts.

isAvailable()

Promise<boolean>

required

Returns true if the provider can be used in the current environment. Called by createProvider during the fallback chain.

cleanup()

Promise<void>

required

Releases all resources held by the provider instance. Always call this in a finally block.

BrowserProviderOptions

Optional per-request settings passed to BrowserProvider.getPageContent.

interface BrowserProviderOptions {
  timeout?: number;
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
}

timeout

number

Navigation timeout in milliseconds. Defaults to 15000 for the fetch provider and 30000 for puppeteer and browserless.

waitUntil

'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'

Determines when the headless browser considers navigation complete. Ignored by the fetch provider. Defaults to 'networkidle2'.

ProviderName

The set of built-in provider names accepted by createProvider and the BROWSER_PROVIDER environment variable.

type ProviderName = 'puppeteer' | 'browserless' | 'fetch';

'puppeteer'

ProviderName

Full headless Chrome via the puppeteer optional peer dependency. Renders JavaScript. Requires puppeteer to be installed.

'browserless'

ProviderName

Remote headless browser via the Browserless REST API. Renders JavaScript. Requires a running Browserless instance, configured via BROWSERLESS_URL (defaults to http://localhost:3000).

'fetch'

ProviderName

Native fetch — no external dependencies, always available on Node 18+. Does not execute JavaScript; works for static or server-rendered pages.

GIT_HOSTS constant

A lookup table mapping recognised hostnames (with and without the www. prefix) to their GitProvider value. Use it to check whether a hostname belongs to a supported git platform or to normalise hostnames before comparison.

import { GIT_HOSTS } from '@clyrisai/gitresolve';

GIT_HOSTS['github.com']        // 'github'
GIT_HOSTS['www.github.com']    // 'github'
GIT_HOSTS['gitlab.com']        // 'gitlab'
GIT_HOSTS['www.gitlab.com']    // 'gitlab'
GIT_HOSTS['bitbucket.org']     // 'bitbucket'
GIT_HOSTS['www.bitbucket.org'] // 'bitbucket'

The full constant definition:

const GIT_HOSTS: Record<string, GitProvider> = {
  'github.com': 'github',
  'www.github.com': 'github',
  'gitlab.com': 'gitlab',
  'www.gitlab.com': 'gitlab',
  'bitbucket.org': 'bitbucket',
  'www.bitbucket.org': 'bitbucket',
};

Prefer GIT_HOSTS[hostname] over hard-coding string comparisons. If GitResolve adds support for additional git hosts in future versions, your code will benefit automatically.

Programmatic API

Types

TypeScript Types Reference for @clyrisai/gitresolve

Importing types

InputType

GitProvider

GitLinkType

ParsedRepo

ExtractedGitLink

ResolverResult

AggregatedResult

BrowserProvider

BrowserProviderOptions

ProviderName

GIT_HOSTS constant

Build docs developers (and LLMs) love

Programmatic API

Types

Documentation Index

​Importing types

​InputType

​GitProvider

​GitLinkType

​ParsedRepo

​ExtractedGitLink

​ResolverResult

​AggregatedResult

​BrowserProvider

​BrowserProviderOptions

​ProviderName

​GIT_HOSTS constant

Build docs developers (and LLMs) love

Importing types

InputType

GitProvider

GitLinkType

ParsedRepo

ExtractedGitLink

ResolverResult

AggregatedResult

BrowserProvider

BrowserProviderOptions

ProviderName

GIT_HOSTS constant