Quickstart

Create a client, list and resolve commits, and verify your first webhook in minutes.

This guide takes you from an empty file to a working client that lists commits, resolves a ref, and verifies an incoming webhook.

1. Install

npm install repo-sdk

pnpm add repo-sdk

yarn add repo-sdk

bun add repo-sdk

2. Create a client

Import createClient from the package root and a provider factory from its subpath. Every provider factory accepts an injectable fetch for testing.

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

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

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,
});

3. Switch providers

Switching providers means swapping the provider — the rest of your code stays the same.

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

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

import { gitlab } from 'repo-sdk/gitlab';

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

import { bitbucket } from 'repo-sdk/bitbucket';

const client = createClient({
  provider: bitbucket({
    auth: {
      email: process.env.BITBUCKET_EMAIL!,
      apiToken: process.env.BITBUCKET_API_TOKEN!,
    },
  }),
});

import { azureDevOps } from 'repo-sdk/azure-devops';

const client = createClient({
  provider: azureDevOps({
    organization: 'my-org',
    auth: { pat: process.env.AZURE_PAT! },
  }),
});

import { gitea } from 'repo-sdk/gitea';

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

4. Receive a webhook

verifyWebhook and parseWebhookEvent are standalone exports on each provider subpath — no client needed. They accept a Web-standard Request, so they drop straight into Next.js route handlers, Hono, and workers.

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

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

  const event = await parseWebhookEvent(request);
  if (event.type === 'push') {
    console.log(`push to ${event.repo} @ ${event.ref}`, event.commits);
  }
  return new Response('ok');
}

Next steps