repo-sdk 0.2.0 → 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.d.ts

@@ -57,6 +57,18 @@ interface ListUserInstallationsParams {
   cursor?: string;
   signal?: AbortSignal;
 }
+interface ListInstallationRequestsParams {
+  /** The GitHub App id the installation requests belong to. */
+  appId: string | number;
+  /** PEM-encoded private key of the app, used to sign the app JWT. */
+  privateKey: string;
+  /** GHES API root (`/api/v3`); defaults to `https://api.github.com`. */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  limit?: number;
+  cursor?: string;
+  signal?: AbortSignal;
+}
 interface GitHubInstallationAccount {
   id: string;
   login: string;
@@ -69,6 +81,16 @@ interface GitHubUserInstallation {
   account?: GitHubInstallationAccount;
   raw: unknown;
 }
+interface GitHubInstallationRequest {
+  id: string;
+  /** Account (organization or user) the installation was requested for. */
+  account?: GitHubInstallationAccount;
+  /** ISO 8601 timestamp of when the request was created. */
+  createdAt: string;
+  /** User who requested the installation. */
+  requester?: GitHubInstallationAccount;
+  raw: unknown;
+}
 /**
  * Lists the GitHub App installations the given user can access
  * (`GET /user/installations`). Standalone by design: the endpoint requires a
@@ -76,9 +98,17 @@ interface GitHubUserInstallation {
  * `github` provider authenticates its requests with.
  */
 declare function listUserInstallations(params: ListUserInstallationsParams): Promise<Page<GitHubUserInstallation>>;
+/**
+ * Lists the pending installation requests of a GitHub App
+ * (`GET /app/installation-requests`) — installations an organization owner has
+ * yet to approve. Standalone by design: the endpoint is authenticated with an
+ * app JWT, a different credential from the installation token the `github`
+ * provider authenticates its requests with.
+ */
+declare function listInstallationRequests(params: ListInstallationRequestsParams): Promise<Page<GitHubInstallationRequest>>;
 //#endregion
 //#region src/providers/github/webhooks.d.ts
 declare function verifyWebhook(params: VerifyWebhookParams): Promise<boolean>;
 declare function parseWebhookEvent(input: Request | IncomingWebhookRequest): Promise<ParsedWebhookEvent>;
 //#endregion
-export { type GitHubAppAuth, type GitHubAuth, type GitHubInstallationAccount, type GitHubInstallationToken, type GitHubProviderOptions, type GitHubRepoProvider, type GitHubTokenAuth, type GitHubUserInstallation, type ListUserInstallationsParams, type VerifyWebhookParams, commitWebUrl, github, listUserInstallations, parseWebhookEvent, verifyWebhook };
+export { type GitHubAppAuth, type GitHubAuth, type GitHubInstallationAccount, type GitHubInstallationRequest, type GitHubInstallationToken, type GitHubProviderOptions, type GitHubRepoProvider, type GitHubTokenAuth, type GitHubUserInstallation, type ListInstallationRequestsParams, type ListUserInstallationsParams, type VerifyWebhookParams, commitWebUrl, github, listInstallationRequests, listUserInstallations, parseWebhookEvent, verifyWebhook };

package/dist/github.js

@@ -77,7 +77,23 @@ const encoder = new TextEncoder();
 function base64UrlJson(value) {
 	return bytesToBase64Url(encoder.encode(JSON.stringify(value)));
 }
-async function createJwt(key, appId) {
+/**
+* Mints a short-lived RS256 JWT signed with the app private key — the
+* credential for app-level endpoints (`/app/…`), which installation and user
+* tokens cannot access. Internal to the package: not exported from the
+* `repo-sdk/github` barrel.
+*/
+async function createAppJwt(options) {
+	let key;
+	try {
+		key = await importPrivateKey(options.privateKey);
+	} catch (error) {
+		throw new RepoError("GitHub App private key is not a valid PEM-encoded RSA private key", {
+			provider: "github",
+			code: "validation",
+			cause: error
+		});
+	}
 	const now = Math.floor(Date.now() / 1e3);
 	const signingInput = `${base64UrlJson({
 		alg: "RS256",
@@ -85,7 +101,7 @@ async function createJwt(key, appId) {
 	})}.${base64UrlJson({
 		iat: now - 60,
 		exp: now + 540,
-		iss: appId
+		iss: String(options.appId)
 	})}`;
 	const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, encoder.encode(signingInput));
 	return `${signingInput}.${bytesToBase64Url(new Uint8Array(signature))}`;
@@ -94,8 +110,9 @@ async function createJwt(key, appId) {
 * Mints and caches GitHub App installation access tokens. A short-lived RS256
 * JWT (signed with the app private key) authenticates the app-level calls that
 * resolve the installation and mint installation tokens; the installation token
-* is cached and refreshed once it nears expiry. A fresh JWT is minted per token
-* refresh (cheap, and refreshes are rare given the ~1h token TTL).
+* is cached and refreshed once it nears expiry. A fresh key import and JWT go
+* into every token refresh (cheap, and refreshes are rare given the ~1h token
+* TTL).
 */
 var AppTokenSource = class {
 	kind = "app";
@@ -107,7 +124,6 @@ var AppTokenSource = class {
 	userAgent;
 	installationId;
 	owner;
-	keyPromise;
 	cached;
 	refresh;
 	constructor(options) {
@@ -153,7 +169,10 @@ var AppTokenSource = class {
 		return this.refresh;
 	}
 	async mintInstallationToken() {
-		const jwt = await this.createAppJwt();
+		const jwt = await createAppJwt({
+			appId: this.appId,
+			privateKey: this.privateKey
+		});
 		const installationId = await this.resolveInstallationId(jwt);
 		const data = await this.appRequest(`/app/installations/${installationId}/access_tokens`, "POST", jwt);
 		const token = {
@@ -199,10 +218,6 @@ var AppTokenSource = class {
 		});
 		return String(installations[0].id);
 	}
-	createAppJwt() {
-		if (!this.keyPromise) this.keyPromise = importPrivateKey(this.privateKey);
-		return this.keyPromise.then((key) => createJwt(key, this.appId));
-	}
 	async appRequest(path, method, jwt) {
 		const url = joinUrl(this.baseUrl, path);
 		const { fetchImpl } = this;
@@ -565,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 },
@@ -577,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 },
@@ -864,42 +887,47 @@ function github(options) {
 }
 //#endregion
 //#region src/providers/github/installations.ts
+function toAccount(payload) {
+	if (payload?.login === void 0) return void 0;
+	return {
+		id: String(payload.id),
+		login: payload.login,
+		kind: payload.type === "Organization" ? "organization" : "user",
+		avatarUrl: payload.avatar_url
+	};
+}
 function toInstallation(payload) {
-	const account = payload.account;
 	return {
 		id: String(payload.id),
-		account: account?.login === void 0 ? void 0 : {
-			id: String(account.id),
-			login: account.login,
-			kind: account.type === "Organization" ? "organization" : "user",
-			avatarUrl: account.avatar_url
-		},
+		account: toAccount(payload.account),
 		raw: payload
 	};
 }
-/**
-* Lists the GitHub App installations the given user can access
-* (`GET /user/installations`). Standalone by design: the endpoint requires a
-* user access token, a different credential from the installation token the
-* `github` provider authenticates its requests with.
-*/
-async function listUserInstallations(params) {
-	const { token } = params;
+function toInstallationRequest(payload) {
+	return {
+		id: String(payload.id),
+		account: toAccount(payload.account),
+		createdAt: payload.created_at,
+		requester: toAccount(payload.requester),
+		raw: payload
+	};
+}
+async function listPage(bearer, defaultPath, params, toItems) {
 	const baseUrl = params.baseUrl ?? "https://api.github.com";
 	const http = new HttpClient({
 		provider: "github",
 		baseUrl,
 		fetchImpl: params.fetch,
 		authHeaders: () => ({
-			Authorization: `Bearer ${token}`,
+			Authorization: `Bearer ${bearer}`,
 			Accept: "application/vnd.github+json",
 			"X-GitHub-Api-Version": API_VERSION,
 			"User-Agent": USER_AGENT
 		}),
 		mapError,
-		secrets: () => [token]
+		secrets: () => [bearer]
 	});
-	let path = "/user/installations";
+	let path = defaultPath;
 	let query;
 	if (params.cursor) {
 		const { url } = decodeCursor("github", params.cursor);
@@ -910,10 +938,32 @@ async function listUserInstallations(params) {
 		signal: params.signal
 	});
 	return {
-		data: (data.installations ?? []).map(toInstallation),
+		data: toItems(data),
 		cursor: nextCursor(response)
 	};
 }
+/**
+* Lists the GitHub App installations the given user can access
+* (`GET /user/installations`). Standalone by design: the endpoint requires a
+* user access token, a different credential from the installation token the
+* `github` provider authenticates its requests with.
+*/
+async function listUserInstallations(params) {
+	return listPage(params.token, "/user/installations", params, (payload) => (payload.installations ?? []).map(toInstallation));
+}
+/**
+* Lists the pending installation requests of a GitHub App
+* (`GET /app/installation-requests`) — installations an organization owner has
+* yet to approve. Standalone by design: the endpoint is authenticated with an
+* app JWT, a different credential from the installation token the `github`
+* provider authenticates its requests with.
+*/
+async function listInstallationRequests(params) {
+	return listPage(await createAppJwt({
+		appId: params.appId,
+		privateKey: params.privateKey
+	}), "/app/installation-requests", params, (payload) => payload.map(toInstallationRequest));
+}
 //#endregion
 //#region src/providers/github/webhooks.ts
 function verifyWebhook(params) {
@@ -949,4 +999,4 @@ async function parseWebhookEvent(input) {
 	};
 }
 //#endregion
-export { commitWebUrl, github, listUserInstallations, parseWebhookEvent, verifyWebhook };
+export { commitWebUrl, github, listInstallationRequests, listUserInstallations, parseWebhookEvent, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-sdk",
-  "version": "0.2.0",
+  "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"