repo-sdk 0.2.1 → 0.2.2

package/README.md

@@ -4,7 +4,16 @@
 [![npm downloads](https://img.shields.io/npm/dm/repo-sdk)](https://www.npmjs.com/package/repo-sdk)
 [![license](https://img.shields.io/npm/l/repo-sdk)](https://github.com/capawesome-team/repo-sdk/blob/main/LICENSE)
 
-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 discovery, commit, tag, 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.
+A unified, normalized, zero-dependency, edge-compatible TypeScript SDK over [GitHub](https://github.com), [GitLab](https://gitlab.com), [Bitbucket Cloud](https://bitbucket.org), [Azure DevOps](https://azure.microsoft.com/products/devops), and [Gitea](https://about.gitea.com) — 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
 
@@ -14,6 +23,8 @@ npm install repo-sdk
 
 ## Quickstart
 
+Create a client from the package root and a provider factory from its subpath.
+
 ```ts
 import { createClient } from 'repo-sdk';
 import { github } from 'repo-sdk/github';
@@ -21,42 +32,154 @@ 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.
 
-// Resolve a ref (branch, tag, or SHA) to a single commit.
+```ts
 const head = await client.commits.get({ repo: 'capawesome-team/repo-sdk', ref: 'main' });
 console.log(head.sha, head.message);
 
-// List commits on a branch.
-const { data: commits } = await client.commits.list({
+const { data: commits, cursor } = await client.commits.list({
   repo: 'capawesome-team/repo-sdk',
   ref: 'main',
   limit: 20,
 });
 ```
 
-Switching providers means swapping the `provider` — the rest of your code stays the same.
+Find out what a user-supplied ref actually is before you act on it.
 
-## Documentation
+```ts
+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
+```
 
-Full documentation lives at **[repo-sdk.dev](https://repo-sdk.dev)** ([docs](https://repo-sdk.dev/docs)):
+Download the code at that ref, as a stream or as a credential-bearing clone URL for the `git` CLI.
 
-- [Quickstart](https://repo-sdk.dev/docs/quickstart)
-- [Authentication](https://repo-sdk.dev/docs/authentication)
-- [Guides](https://repo-sdk.dev/docs/guides)
-- [API Reference](https://repo-sdk.dev/docs/reference)
+```ts
+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.
+
+```ts
+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` · `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.
 
 ## Providers
 
 | Provider     | Import                  | Notes                                                            |
 | ------------ | ----------------------- | ---------------------------------------------------------------- |
-| GitHub       | `repo-sdk/github`       | Token and GitHub App auth                                        |
-| GitLab       | `repo-sdk/gitlab`       | PAT, group/project, or OAuth token                               |
-| Bitbucket    | `repo-sdk/bitbucket`    | Bitbucket Cloud                                                  |
-| Azure DevOps | `repo-sdk/azure-devops` | PAT or Entra ID                                                  |
-| Gitea        | `repo-sdk/gitea`        | Gitea ≥ 1.20 and Forgejo                                         |
-| Generic git  | `repo-sdk/git-http`     | Any git smart-HTTP remote (read-only ref discovery + clone URLs) |
+| GitHub       | `repo-sdk/github`       | Personal access token or GitHub App installation auth.           |
+| GitLab       | `repo-sdk/gitlab`       | Personal, group, project, or OAuth token.                        |
+| Bitbucket    | `repo-sdk/bitbucket`    | Bitbucket Cloud. Atlassian API token or access token.            |
+| Azure DevOps | `repo-sdk/azure-devops` | Organization-scoped. PAT or Entra ID token.                      |
+| Gitea        | `repo-sdk/gitea`        | Gitea ≥ 1.20 and Forgejo.                                        |
+| Generic git  | `repo-sdk/git-http`     | Any git smart-HTTP remote. Ref discovery and clone URLs only.    |
+| Testing      | `repo-sdk/testing`      | Seedable in-memory provider for your test suite. No credentials. |
 
-Self-hosted deployments — GitHub Enterprise Server, GitLab self-managed, Azure DevOps Server, and Gitea/Forgejo instances — are supported via `baseUrl`.
+Every factory accepts an injectable `fetch`, and every token can be a static string or a `tokenProvider` that mints one per request and is re-invoked once on a 401. Self-hosted deployments — GitHub Enterprise Server, GitLab self-managed, Azure DevOps Server, and Gitea/Forgejo — are supported via `baseUrl`. Providers do not support the same feature set — `client.capabilities` tells you what the active one can do, and the full breakdown lives in the [capability matrix](https://repo-sdk.dev/docs/reference/capability-matrix).
+
+## Testing
+
+`repo-sdk/testing` ships a seedable in-memory provider you hand to `createClient` like any other — no account, no tokens, no `fetch` stubs, no throwaway repositories.
+
+```ts
+import { createClient } from 'repo-sdk';
+import { createInMemoryProvider } from 'repo-sdk/testing';
+
+const client = createClient({
+  provider: createInMemoryProvider({
+    repositories: { 'acme/app': { name: 'app', namespace: 'acme', defaultBranch: 'main' } },
+    branches: { 'acme/app': [{ name: 'main', sha: 'c1' }] },
+    commits: { 'acme/app': [{ sha: 'c1', message: 'Initial commit' }] },
+  }),
+});
+```
+
+It reports every capability enabled by default, and a second options argument simulates a specific provider's identity and capability gaps — so code that branches on `client.capabilities` is testable. Its page size is deliberately small, so your cursor pagination gets exercised, and `provider.state` exposes the data as plain maps for assertions.
+
+## Errors
+
+Every failure is a `RepoError` with a closed `code` union: `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `validation`, `unsupported`, `provider_error`, `network_error`.
+
+```ts
+import { RepoError } from 'repo-sdk';
+
+try {
+  await client.repos.downloadArchive({ repo: 'acme/app', ref: 'main', format: 'tar.gz' });
+} catch (error) {
+  if (error instanceof RepoError && error.code === 'unsupported') {
+    // Azure DevOps serves zip only — fall back instead of failing the job.
+  }
+}
+```
+
+Errors also carry `provider`, `status`, `retryAfter` and `retryable`; `cause` is the underlying JS `Error`. Token values are redacted from every message, so a leaked stack trace cannot leak a credential. The one deliberate exception is `repos.getCloneUrl`, which returns a URL with the credential embedded because that is what `git clone` needs — treat it as a secret.
+
+## Runtime support
+
+Node.js ≥ 20, Cloudflare Workers (without `nodejs_compat`), Deno, Bun, Vercel Edge, and any other runtime with `fetch`, Web Crypto and `TextEncoder`. ESM only.
+
+## Documentation
+
+Full documentation lives at **[repo-sdk.dev](https://repo-sdk.dev)** ([docs](https://repo-sdk.dev/docs)):
+
+- [Quickstart](https://repo-sdk.dev/docs/quickstart)
+- [Concepts](https://repo-sdk.dev/docs/concepts/client-and-providers) — clients, repositories and namespaces, capabilities, pagination, errors
+- [Authentication](https://repo-sdk.dev/docs/authentication) — tokens, GitHub Apps, Entra ID, and the scopes each provider needs
+- [Guides](https://repo-sdk.dev/docs/guides/resolving-refs) — resolving refs, commits, branches, tags, downloading code, managing and receiving webhooks
+- [Testing](https://repo-sdk.dev/docs/testing)
+- [Capability matrix](https://repo-sdk.dev/docs/reference/capability-matrix)
+- [Provider support](https://repo-sdk.dev/docs/reference/provider-support)
+- [Error codes](https://repo-sdk.dev/docs/reference/error-codes)
 
 ## Development
 
@@ -69,7 +192,7 @@ npm install
 | Script               | Description                                                     |
 | -------------------- | --------------------------------------------------------------- |
 | `npm run build`      | Build with tsdown                                               |
-| `npm test`           | Run the unit + contract test suite                              |
+| `npm test`           | Run the unit + provider contract test suite                     |
 | `npm run test:watch` | Run tests in watch mode                                         |
 | `npm run test:live`  | Gated live provider tests (env vars documented in CONTRIBUTING) |
 | `npm run typecheck`  | Type-check without emitting                                     |

package/dist/github.js

@@ -580,6 +580,17 @@ function github(options) {
 				};
 			}
 			if (params.namespace) {
+				if (tokenSource.kind === "app") {
+					const namespaceLower = params.namespace.toLowerCase();
+					const { data, response } = await http.json("/installation/repositories", {
+						query: { per_page: perPage },
+						signal: params.signal
+					});
+					return {
+						data: reposFromBody(data).filter((repo) => repo.owner.login.toLowerCase() === namespaceLower).map(mapRepository),
+						cursor: nextCursor(response)
+					};
+				}
 				try {
 					const { data, response } = await http.json(`/orgs/${encodeURIComponent(params.namespace)}/repos`, {
 						query: { per_page: perPage },
@@ -592,21 +603,18 @@ function github(options) {
 				} catch (error) {
 					if (!(error instanceof RepoError && error.code === "not_found")) throw error;
 				}
-				if (tokenSource.kind === "token") {
-					const login = await getLogin(params.signal);
-					if (params.namespace.toLowerCase() === login.toLowerCase()) {
-						const { data, response } = await http.json("/user/repos", {
-							query: {
-								affiliation: "owner",
-								per_page: perPage
-							},
-							signal: params.signal
-						});
-						return {
-							data: data.map(mapRepository),
-							cursor: nextCursor(response)
-						};
-					}
+				if ((await getLogin(params.signal)).toLowerCase() === params.namespace.toLowerCase()) {
+					const { data, response } = await http.json("/user/repos", {
+						query: {
+							affiliation: "owner",
+							per_page: perPage
+						},
+						signal: params.signal
+					});
+					return {
+						data: data.map(mapRepository),
+						cursor: nextCursor(response)
+					};
 				}
 				const { data, response } = await http.json(`/users/${encodeURIComponent(params.namespace)}/repos`, {
 					query: { per_page: perPage },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Unified TypeScript SDK for git providers — GitHub, GitLab, Bitbucket, Azure DevOps, Gitea",
   "license": "MIT",
   "author": "Robin Genz <mail@robingenz.dev>",
@@ -22,7 +22,7 @@
     "version-control",
     "webhooks"
   ],
-  "homepage": "https://github.com/capawesome-team/repo-sdk",
+  "homepage": "https://repo-sdk.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/capawesome-team/repo-sdk"