Git Provider Core

@ftmahringer/git-provider-core is a TypeScript library for reading, normalizing, and analyzing repository data from git hosting services.

It provides one client for repository metadata, grouped repo insights, README content, docs, activity, normalized content models, and lightweight analytics across GitHub and Forgejo-compatible servers.

What it does

With one client you can:

• fetch repository metadata
• fetch grouped repository insights such as languages, refs, releases, and repository stats
• fetch and normalize README content
• fetch docs from an explicit URL or optional wiki discovery
• fetch recent activity
• extract metadata and document structure from README/docs
• build a normalized content model for downstream apps
• generate lightweight analytics from repository content
• use caching, retries, timeouts, and force-refresh controls

This package is designed as a framework-agnostic core layer. You can use it directly in Node.js apps, server-side rendering, dashboards, portfolio sites, and future UI wrappers.

Install

npm install @ftmahringer/git-provider-core

Quick start

import { createGitProviderClient } from '@ftmahringer/git-provider-core';

const client = createGitProviderClient({
  repoUrl: 'https://codeberg.org/example/project',
  repoName: 'example/project',
});

const repo = await client.getRepo();
const insights = await client.getRepoInsights();
const readme = await client.getReadme();
const docs = await client.getDocs();
const activity = await client.getActivity();

Main client methods

Core repository data

• getProviderInfo()
• getRepo()
• getRepoInsights()
• getReadme()
• getDocs()
• getActivity()

Content and analysis helpers

• getReadmeMetadata()
• getReadmeStructure()
• getDocsMetadata()
• getDocsStructure()
• getContentModel()
• getAnalytics()

What getRepoInsights() returns

getRepoInsights() returns a grouped object with sections such as:

• provider
• stats
• languages
• refs
• releases
• packages
• capabilities

Some sections depend on provider support and available API data. Fields that cannot be resolved cleanly are returned as null, and capabilities tells you which sections are supported.

Example: normalized content model

const model = await client.getContentModel();

console.log(model.repo.fullName);
console.log(model.readme.title);
console.log(model.docs.available);
console.log(model.activity.latestCommit?.summary);

Example: lightweight analytics

const analytics = await client.getAnalytics();

console.log(analytics.freshness.freshnessLabel);
console.log(analytics.coverage.hasDocs);
console.log(analytics.activity.commitCount);
console.log(analytics.usefulness.completenessScore);

Example: repo insights

const insights = await client.getRepoInsights();

console.log(insights.provider.name);
console.log(insights.stats.stars);
console.log(insights.stats.commitCount);
console.log(insights.languages.primary);
console.log(insights.languages.breakdown);
console.log(insights.refs.defaultBranch);
console.log(insights.refs.branchCount);
console.log(insights.releases.latest?.tag);

Provider support

Supported today:

• GitHub
• Forgejo-compatible servers

The public API is provider-agnostic, but some data depends on what each provider exposes cleanly through its API. The goal is to keep the result shape stable even when provider capabilities differ.

If provider detection is ambiguous, pass the provider explicitly:

const client = createGitProviderClient({
  repoUrl: 'https://git.example.test/owner/repo',
  repoName: 'owner/repo',
  provider: 'forgejo',
});

Request controls

The client supports retries, timeouts, caching, and force refresh.

These controls apply to the raw fetch methods as well as higher-level helpers like getContentModel(), getAnalytics(), and getRepoInsights().

const client = createGitProviderClient({
  repoUrl: 'https://github.com/owner/repo',
  repoName: 'owner/repo',
  requestTimeoutMs: 10_000,
  retry: {
    attempts: 3,
    delayMs: 250,
    factor: 2,
  },
});

const repo = await client.getRepo({ forceRefresh: true });

Caching

An in-memory cache is enabled by default.

You can provide your own cache implementation or turn caching off completely.

import {
  createGitProviderClient,
  createInMemoryGitProviderCache,
} from '@ftmahringer/git-provider-core';

const cache = createInMemoryGitProviderCache();

const client = createGitProviderClient({
  repoUrl: 'https://github.com/owner/repo',
  repoName: 'owner/repo',
  cache,
  cachePolicy: {
    repoTtlMs: 5 * 60 * 1000,
    readmeTtlMs: 10 * 60 * 1000,
    docsTtlMs: 10 * 60 * 1000,
    activityTtlMs: 2 * 60 * 1000,
    insightsTtlMs: 5 * 60 * 1000,
  },
});

Docs fetching

If you already know the docs URL, pass it directly:

const client = createGitProviderClient({
  repoUrl: 'https://github.com/owner/repo',
  repoName: 'owner/repo',
  docsUrl: 'https://docs.example.test/readme.md',
});

Wiki discovery is disabled by default to avoid unnecessary HTTPS/API usage. If you want it, enable it explicitly:

const client = createGitProviderClient({
  repoUrl: 'https://github.com/owner/repo',
  repoName: 'owner/repo',
  allowWikiDiscovery: true,
});

Auth

Use token for authenticated provider API access when the provider supports it. The client sends it as a Bearer token.

Without a token, the library uses public API access only. With a token, it can use any additional authenticated data the provider makes available to that token.

const client = createGitProviderClient({
  repoUrl: 'https://github.com/owner/repo',
  repoName: 'owner/repo',
  token: process.env.GITHUB_TOKEN,
});

The library is intentionally HTTPS/API-first for repository reads and repo insights.

Standalone helper functions

The package also exposes standalone helpers if you want to work with fetched data yourself instead of going through the client for everything.

Examples include:

• metadata extraction helpers
• document structure helpers
• normalization helpers
• analytics helpers
• repo insights types and helpers

This makes it easier to build custom UIs, content pipelines, API wrappers, or framework integrations on top of the core package.

Package notes

• Pure TypeScript core logic
• No React components
• No Next.js-specific code
• Public HTTPS repository access first
• Internal provider adapters, public normalized API

---

Important Notice

This project made extensive use of AI during development, primarily for code cleanup, refactoring, documentation, and improving code quality. The initial implementation, design, and overall direction of the project were created by a human.

If you prefer not to use software that has been developed with significant AI assistance, this package may not be the right choice for you.