repo-sdk

A unified, normalized, zero-dependency, edge-compatible TypeScript SDK over GitHub, GitLab, Bitbucket Cloud, Azure DevOps, and Gitea — plus generic git smart-HTTP remotes. Write your repository, commit, branch, tag, ref-resolution, download and webhook logic once against one normalized API — built on raw fetch and Web Crypto, so it runs on Node, Cloudflare Workers, and other Web-standard runtimes.

Features

• One API, eight namespaces — users, namespaces, repos, commits, branches, tags, refs, and webhooks behind a single interface.
• Capability gating — providers differ. The client reports what the active provider supports and throws unsupported instead of silently dropping an option.
• Ref resolution that follows git — refs.resolve accepts a branch, a tag, a fully-qualified refs/…, HEAD, or an abbreviated SHA and returns one normalized match, with tags shadowing branches exactly like git rev-parse.
• Webhook verify & parse — standalone per-provider helpers that take a Web-standard Request. No client, no credentials. detectWebhookProvider routes a shared endpoint to the right pair.
• Zero dependencies — fetch and Web Crypto only. No node:* imports, so it runs on Cloudflare Workers without nodejs_compat — including RS256 JWT signing for GitHub App auth.
• Tree-shakable and typed — each provider ships on its own subpath, so unused providers never reach your bundle. Every model is normalized (IDs as strings, dates as Date, refs fully qualified) and keeps the untouched provider payload on raw.

Installation

npm install repo-sdk

Quickstart

Create a client from the package root and a provider factory from its subpath.

import { createClient } from 'repo-sdk';
import { github } from 'repo-sdk/github';

const client = createClient({
  provider: github({ auth: { token: process.env.GITHUB_TOKEN! } }),
});

Resolve a ref — a branch, tag, SHA, or HEAD — to a single commit, and page through history.

const head = await client.commits.get({ repo: 'capawesome-team/repo-sdk', ref: 'main' });
console.log(head.sha, head.message);

const { data: commits, cursor } = await client.commits.list({
  repo: 'capawesome-team/repo-sdk',
  ref: 'main',
  limit: 20,
});

Find out what a user-supplied ref actually is before you act on it.

const match = await client.refs.resolve({ repo: 'capawesome-team/repo-sdk', ref: 'v1.0.0' });
match.type; // 'branch' | 'tag' | 'commit'
match.ref; // 'refs/tags/v1.0.0'
match.sha; // peeled to the commit SHA for annotated tags

Download the code at that ref, as a stream or as a credential-bearing clone URL for the git CLI.

const archive = await client.repos.downloadArchive({
  repo: 'capawesome-team/repo-sdk',
  ref: match.sha,
  format: 'tar.gz',
});
await new Response(archive.stream).arrayBuffer();

const { url } = await client.repos.getCloneUrl({ repo: 'capawesome-team/repo-sdk' });

Verify and handle the webhook. The helpers take the Request itself — no client, no credentials.

import { parseWebhookEvent, verifyWebhook } from 'repo-sdk/github';

export async function POST(request: Request): Promise<Response> {
  if (!(await verifyWebhook({ request, secret: process.env.WEBHOOK_SECRET! }))) {
    return new Response('invalid signature', { status: 401 });
  }

  const event = await parseWebhookEvent(request);

  switch (event.type) {
    case 'push':
      // event.headCommitSha is undefined when the push deleted the ref.
      break;
    case 'tag_push':
      // event.ref is always fully qualified — refs/tags/v1.0.0.
      break;
    case 'release':
      break;
  }

  return new Response(null, { status: 204 });
}

API at a glance

Namespace	Methods
users	me
namespaces	list · listAll
repos	list · listAll · get · downloadArchive · getCloneCredentials · getCloneUrl
commits	list · listAll · get
branches	list · listAll · get
tags	list · listAll · get
refs	resolve · search
webhooks	create · list · get · update · delete

Every list returns an opaque cursor and has a listAll async generator that walks the pages for you. Cursors are provider-tagged and origin-checked, so a forged one cannot redirect an authenticated request. Every method accepts a signal for cancellation. Rate-limited requests are retried once when the provider's Retry-After fits the budget (10 seconds by default, configurable via retry).

Webhook payload helpers — verifyWebhook and parseWebhookEvent — are exported from the provider subpaths and take no credential beyond the shared secret, so they run in a handler with no client at all. detectWebhookProvider from the core entry identifies the sender when one endpoint serves several providers.

This is the beginning of the README. Read the rest at the original. Read the full README ↗