repo-sdk 0.1.1 → 0.1.3

package/README.md

@@ -74,7 +74,7 @@ npm install
 | `npm run test:live`  | Gated live provider tests (env vars documented in CONTRIBUTING) |
 | `npm run typecheck`  | Type-check without emitting                                     |
 | `npm run lint`       | Lint the codebase                                               |
-| `npm run format`     | Format with prettier                                            |
+| `npm run fmt`        | Format with prettier                                            |
 
 Docs site:
 

package/dist/azure-devops.d.ts

@@ -1,4 +1,4 @@
-import { O as ParsedWebhookEvent, P as RepoProvider, v as IncomingWebhookRequest, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { B as TokenProvider, F as RepoProvider, O as ParsedWebhookEvent, v as IncomingWebhookRequest } from "./types-DfiRluvJ.js";
 import { t as VerifyWebhookParams$1 } from "./verify-p6JsExms.js";
 //#region src/providers/azure-devops/auth.d.ts
 /**

package/dist/azure-devops.js

@@ -1,6 +1,6 @@
 import { t as RepoError } from "./errors-Cxq_CqYv.js";
 import { n as decodeCursor, r as encodeCursor } from "./pagination-CWWHSu8I.js";
-import { a as isRecord, i as filenameFromContentDisposition, n as commitWebUrlBuilder, s as HttpClient } from "./shared-CuiOaaLD.js";
+import { a as filenameFromContentDisposition, o as isRecord, r as commitWebUrlBuilder, t as HttpClient } from "./http-C3hAQeY0.js";
 import { a as headShaOrUndefined, n as timingSafeEqual, r as toIncomingWebhook } from "./verify-BBMVxz8q.js";
 //#region src/providers/azure-devops/auth.ts
 /**

package/dist/bitbucket.d.ts

@@ -1,4 +1,4 @@
-import { O as ParsedWebhookEvent, P as RepoProvider, v as IncomingWebhookRequest, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { B as TokenProvider, F as RepoProvider, O as ParsedWebhookEvent, v as IncomingWebhookRequest } from "./types-DfiRluvJ.js";
 import { t as VerifyWebhookParams } from "./verify-p6JsExms.js";
 //#region src/providers/bitbucket/index.d.ts
 interface BitbucketProviderOptions {

package/dist/bitbucket.js

@@ -1,6 +1,6 @@
 import { t as RepoError } from "./errors-Cxq_CqYv.js";
 import { n as decodeCursor, r as encodeCursor, t as assertSameOriginUrl } from "./pagination-CWWHSu8I.js";
-import { a as isRecord, i as filenameFromContentDisposition, n as commitWebUrlBuilder, s as HttpClient, t as clampPerPage } from "./shared-CuiOaaLD.js";
+import { a as filenameFromContentDisposition, n as clampPerPage, o as isRecord, r as commitWebUrlBuilder, t as HttpClient } from "./http-C3hAQeY0.js";
 import { a as headShaOrUndefined, i as verifyHmacSignature, r as toIncomingWebhook } from "./verify-BBMVxz8q.js";
 //#region src/providers/bitbucket/index.ts
 const BASE_URL = "https://api.bitbucket.org/2.0";

package/dist/git-http.d.ts

@@ -1,4 +1,4 @@
-import { P as RepoProvider, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { B as TokenProvider, F as RepoProvider } from "./types-DfiRluvJ.js";
 //#region src/providers/git-http/index.d.ts
 interface GitHttpProviderOptions {
   /**

package/dist/git-http.js

@@ -1,6 +1,6 @@
 import { t as RepoError } from "./errors-Cxq_CqYv.js";
 import { a as stringToBase64, n as decodeCursor, r as encodeCursor } from "./pagination-CWWHSu8I.js";
-import { s as HttpClient, t as clampPerPage } from "./shared-CuiOaaLD.js";
+import { n as clampPerPage, t as HttpClient } from "./http-C3hAQeY0.js";
 //#region src/providers/git-http/index.ts
 const CAPABILITIES = {
 	userProfile: false,

package/dist/gitea.d.ts

@@ -1,4 +1,4 @@
-import { O as ParsedWebhookEvent, P as RepoProvider, v as IncomingWebhookRequest, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { B as TokenProvider, F as RepoProvider, O as ParsedWebhookEvent, v as IncomingWebhookRequest } from "./types-DfiRluvJ.js";
 import { t as VerifyWebhookParams } from "./verify-p6JsExms.js";
 //#region src/providers/gitea/index.d.ts
 interface GiteaProviderOptions {

package/dist/gitea.js

@@ -1,6 +1,6 @@
 import { t as RepoError } from "./errors-Cxq_CqYv.js";
 import { n as decodeCursor, r as encodeCursor, t as assertSameOriginUrl } from "./pagination-CWWHSu8I.js";
-import { a as isRecord, i as filenameFromContentDisposition, n as commitWebUrlBuilder, o as parseLinkNext, r as encodeRefPath, s as HttpClient, t as clampPerPage } from "./shared-CuiOaaLD.js";
+import { a as filenameFromContentDisposition, i as encodeRefPath, n as clampPerPage, o as isRecord, r as commitWebUrlBuilder, s as parseLinkNext, t as HttpClient } from "./http-C3hAQeY0.js";
 import { a as headShaOrUndefined, n as timingSafeEqual, r as toIncomingWebhook, t as hmacSha256Hex } from "./verify-BBMVxz8q.js";
 //#region src/providers/gitea/index.ts
 const DEFAULT_BASE_URL = "https://gitea.com/api/v1";

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import { O as ParsedWebhookEvent, P as RepoProvider, v as IncomingWebhookRequest, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { B as TokenProvider, D as Page, F as RepoProvider, O as ParsedWebhookEvent, v as IncomingWebhookRequest } from "./types-DfiRluvJ.js";
 import { t as VerifyWebhookParams } from "./verify-p6JsExms.js";
 //#region src/providers/github/app-auth.d.ts
 interface InstallationToken {
@@ -43,8 +43,42 @@ interface GitHubRepoProvider extends RepoProvider {
 declare const commitWebUrl: (repoWebUrl: string, sha: string) => string;
 declare function github(options: GitHubProviderOptions): GitHubRepoProvider;
 //#endregion
+//#region src/providers/github/installations.d.ts
+interface ListUserInstallationsParams {
+  /**
+   * A user access token — e.g. the OAuth token minted by the GitHub App web
+   * login flow. Installation tokens cannot call this endpoint.
+   */
+  token: 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;
+  kind: 'user' | 'organization';
+  avatarUrl?: string;
+}
+interface GitHubUserInstallation {
+  id: string;
+  /** Account the app is installed on; absent for enterprise-level installations. */
+  account?: GitHubInstallationAccount;
+  raw: unknown;
+}
+/**
+ * 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.
+ */
+declare function listUserInstallations(params: ListUserInstallationsParams): Promise<Page<GitHubUserInstallation>>;
+//#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 GitHubInstallationToken, type GitHubProviderOptions, type GitHubRepoProvider, type GitHubTokenAuth, type VerifyWebhookParams, commitWebUrl, github, parseWebhookEvent, verifyWebhook };
+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 };

package/dist/github.js

@@ -1,6 +1,6 @@
 import { n as codeFromStatus, t as RepoError } from "./errors-Cxq_CqYv.js";
 import { i as bytesToBase64Url, n as decodeCursor, r as encodeCursor, t as assertSameOriginUrl } from "./pagination-CWWHSu8I.js";
-import { a as isRecord, i as filenameFromContentDisposition, n as commitWebUrlBuilder, o as parseLinkNext, r as encodeRefPath, s as HttpClient, t as clampPerPage } from "./shared-CuiOaaLD.js";
+import { a as filenameFromContentDisposition, i as encodeRefPath, n as clampPerPage, o as isRecord, r as commitWebUrlBuilder, s as parseLinkNext, t as HttpClient } from "./http-C3hAQeY0.js";
 import { a as headShaOrUndefined, i as verifyHmacSignature, r as toIncomingWebhook } from "./verify-BBMVxz8q.js";
 //#region src/providers/github/app-auth.ts
 const RSA_ALGORITHM_IDENTIFIER = [
@@ -205,9 +205,10 @@ var AppTokenSource = class {
 	}
 	async appRequest(path, method, jwt) {
 		const url = joinUrl(this.baseUrl, path);
+		const { fetchImpl } = this;
 		let response;
 		try {
-			response = await this.fetchImpl(url, {
+			response = await fetchImpl(url, {
 				method,
 				headers: {
 					Authorization: `Bearer ${jwt}`,
@@ -242,11 +243,23 @@ var AppTokenSource = class {
 		});
 	}
 };
-//#endregion
-//#region src/providers/github/index.ts
-const DEFAULT_BASE_URL = "https://api.github.com";
 const API_VERSION = "2022-11-28";
 const USER_AGENT = "repo-sdk";
+function mapError(status, body, response) {
+	const message = isRecord(body) && typeof body.message === "string" ? body.message : void 0;
+	let code;
+	if (status === 429 || status === 403 && response.headers.get("x-ratelimit-remaining") === "0") code = "rate_limited";
+	return {
+		code,
+		message
+	};
+}
+function nextCursor(response) {
+	const next = parseLinkNext(response.headers.get("link"));
+	return next === void 0 ? void 0 : encodeCursor("github", { url: next });
+}
+//#endregion
+//#region src/providers/github/index.ts
 const CAPABILITIES = {
 	tagDates: false,
 	repoSearch: true,
@@ -297,10 +310,6 @@ function createTokenSource(auth, baseUrl, fetchImpl) {
 		userAgent: USER_AGENT
 	});
 }
-function nextCursor(response) {
-	const next = parseLinkNext(response.headers.get("link"));
-	return next === void 0 ? void 0 : encodeCursor("github", { url: next });
-}
 function gitHostFromBaseUrl(baseUrl) {
 	const url = new URL(baseUrl);
 	return url.hostname === "api.github.com" ? "github.com" : url.host;
@@ -410,22 +419,13 @@ function toWebhook(hook) {
 		raw: hook
 	};
 }
-function mapError(status, body, response) {
-	const message = isRecord(body) && typeof body.message === "string" ? body.message : void 0;
-	let code;
-	if (status === 429 || status === 403 && response.headers.get("x-ratelimit-remaining") === "0") code = "rate_limited";
-	return {
-		code,
-		message
-	};
-}
 /**
 * Builds the human-facing web URL for a commit from the repository's web URL
 * (`Repository.urls.web`) and a commit SHA — no API request needed.
 */
 const commitWebUrl = commitWebUrlBuilder("commit");
 function github(options) {
-	const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+	const baseUrl = options.baseUrl ?? "https://api.github.com";
 	const fetchImpl = options.fetch ?? fetch;
 	const tokenSource = createTokenSource(options.auth, baseUrl, fetchImpl);
 	const webBase = `https://${gitHostFromBaseUrl(baseUrl)}`;
@@ -863,6 +863,58 @@ function github(options) {
 	};
 }
 //#endregion
+//#region src/providers/github/installations.ts
+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
+		},
+		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;
+	const baseUrl = params.baseUrl ?? "https://api.github.com";
+	const http = new HttpClient({
+		provider: "github",
+		baseUrl,
+		fetchImpl: params.fetch,
+		authHeaders: () => ({
+			Authorization: `Bearer ${token}`,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": API_VERSION,
+			"User-Agent": USER_AGENT
+		}),
+		mapError,
+		secrets: () => [token]
+	});
+	let path = "/user/installations";
+	let query;
+	if (params.cursor) {
+		const { url } = decodeCursor("github", params.cursor);
+		path = assertSameOriginUrl("github", baseUrl, url);
+	} else query = { per_page: clampPerPage(params.limit) };
+	const { data, response } = await http.json(path, {
+		query,
+		signal: params.signal
+	});
+	return {
+		data: (data.installations ?? []).map(toInstallation),
+		cursor: nextCursor(response)
+	};
+}
+//#endregion
 //#region src/providers/github/webhooks.ts
 function verifyWebhook(params) {
 	return verifyHmacSignature(params, { header: "x-hub-signature-256" });
@@ -897,4 +949,4 @@ async function parseWebhookEvent(input) {
 	};
 }
 //#endregion
-export { commitWebUrl, github, parseWebhookEvent, verifyWebhook };
+export { commitWebUrl, github, listUserInstallations, parseWebhookEvent, verifyWebhook };

package/dist/gitlab.d.ts

@@ -1,4 +1,4 @@
-import { O as ParsedWebhookEvent, P as RepoProvider, v as IncomingWebhookRequest, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { B as TokenProvider, F as RepoProvider, O as ParsedWebhookEvent, v as IncomingWebhookRequest } from "./types-DfiRluvJ.js";
 import { t as VerifyWebhookParams } from "./verify-p6JsExms.js";
 //#region src/providers/gitlab/index.d.ts
 interface GitLabProviderOptions {

package/dist/gitlab.js

@@ -1,6 +1,6 @@
 import { t as RepoError } from "./errors-Cxq_CqYv.js";
 import { n as decodeCursor, r as encodeCursor, t as assertSameOriginUrl } from "./pagination-CWWHSu8I.js";
-import { a as isRecord, i as filenameFromContentDisposition, n as commitWebUrlBuilder, o as parseLinkNext, s as HttpClient, t as clampPerPage } from "./shared-CuiOaaLD.js";
+import { a as filenameFromContentDisposition, n as clampPerPage, o as isRecord, r as commitWebUrlBuilder, s as parseLinkNext, t as HttpClient } from "./http-C3hAQeY0.js";
 import { a as headShaOrUndefined, n as timingSafeEqual, r as toIncomingWebhook } from "./verify-BBMVxz8q.js";
 //#region src/providers/gitlab/index.ts
 const DEFAULT_BASE_URL = "https://gitlab.com/api/v4";

package/dist/{shared-CuiOaaLD.js → http-C3hAQeY0.js}

@@ -1,5 +1,37 @@
 import { n as codeFromStatus, r as parseRetryAfter, t as RepoError } from "./errors-Cxq_CqYv.js";
+//#region src/providers/shared.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function clampPerPage(limit, max = 100) {
+	if (limit === void 0) return void 0;
+	return Math.min(Math.max(1, Math.trunc(limit)), max);
+}
+function parseLinkNext(header) {
+	if (!header) return void 0;
+	for (const part of header.split(",")) {
+		const match = part.match(/<([^>]+)>\s*;\s*rel="([^"]+)"/);
+		if (match && match[2] === "next") return match[1];
+	}
+}
+/** Percent-encodes a ref path while keeping its `/` separators intact. */
+function encodeRefPath(ref) {
+	return ref.split("/").map(encodeURIComponent).join("/");
+}
+function commitWebUrlBuilder(pathSegment) {
+	return function commitWebUrl(repoWebUrl, sha) {
+		return `${repoWebUrl.replace(/\/+$/, "")}/${pathSegment}/${sha}`;
+	};
+}
+function filenameFromContentDisposition(header) {
+	if (!header) return void 0;
+	const extended = header.match(/filename\*=(?:UTF-8'')?([^;]+)/i);
+	if (extended?.[1]) return decodeURIComponent(extended[1].trim().replace(/^"|"$/g, ""));
+	return header.match(/filename="?([^";]+)"?/i)?.[1]?.trim();
+}
+//#endregion
 //#region src/http.ts
+const USER_AGENT = "repo-sdk";
 var HttpClient = class {
 	options;
 	constructor(options) {
@@ -23,6 +55,7 @@ var HttpClient = class {
 				...await this.options.authHeaders({ forceRefresh }),
 				...options.headers
 			};
+			headers["User-Agent"] ??= USER_AGENT;
 			if (body !== void 0) headers["Content-Type"] ??= "application/json";
 			try {
 				return await fetchImpl(url, {
@@ -71,35 +104,4 @@ var HttpClient = class {
 	}
 };
 //#endregion
-//#region src/providers/shared.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function clampPerPage(limit, max = 100) {
-	if (limit === void 0) return void 0;
-	return Math.min(Math.max(1, Math.trunc(limit)), max);
-}
-function parseLinkNext(header) {
-	if (!header) return void 0;
-	for (const part of header.split(",")) {
-		const match = part.match(/<([^>]+)>\s*;\s*rel="([^"]+)"/);
-		if (match && match[2] === "next") return match[1];
-	}
-}
-/** Percent-encodes a ref path while keeping its `/` separators intact. */
-function encodeRefPath(ref) {
-	return ref.split("/").map(encodeURIComponent).join("/");
-}
-function commitWebUrlBuilder(pathSegment) {
-	return function commitWebUrl(repoWebUrl, sha) {
-		return `${repoWebUrl.replace(/\/+$/, "")}/${pathSegment}/${sha}`;
-	};
-}
-function filenameFromContentDisposition(header) {
-	if (!header) return void 0;
-	const extended = header.match(/filename\*=(?:UTF-8'')?([^;]+)/i);
-	if (extended?.[1]) return decodeURIComponent(extended[1].trim().replace(/^"|"$/g, ""));
-	return header.match(/filename="?([^";]+)"?/i)?.[1]?.trim();
-}
-//#endregion
-export { isRecord as a, filenameFromContentDisposition as i, commitWebUrlBuilder as n, parseLinkNext as o, encodeRefPath as r, HttpClient as s, clampPerPage as t };
+export { filenameFromContentDisposition as a, encodeRefPath as i, clampPerPage as n, isRecord as o, commitWebUrlBuilder as r, parseLinkNext as s, HttpClient as t };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as ProviderSearchRefsParams, B as UpdateWebhookParams, C as ListTagsParams, D as Page, E as NamespaceKind, F as Repository, H as Webhook, I as ResolveRefParams, L as SearchRefsParams, M as RefType, N as RepoCapabilities, O as ParsedWebhookEvent, P as RepoProvider, R as Tag, S as ListRepositoriesParams, T as Namespace, U as WebhookEventType, V as UserRef, W as WebhookVerificationMethod, _ as GitActor, a as CloneUrl, b as ListCommitsParams, c as DeleteWebhookParams, d as GetBranchParams, f as GetCloneUrlParams, g as GetWebhookParams, h as GetTagParams, i as Branch, j as RefMatch, k as ProviderName, l as DownloadArchiveParams, m as GetRepositoryParams, n as ArchiveFormat, o as Commit, p as GetCommitParams, r as AuthenticatedUser, s as CreateWebhookParams, t as Archive, u as GetAuthenticatedUserParams, v as IncomingWebhookRequest, w as ListWebhooksParams, x as ListNamespacesParams, y as ListBranchesParams, z as TokenProvider } from "./types-CTeiAxMy.js";
+import { A as ProviderRefMatch, B as TokenProvider, C as ListTagsParams, D as Page, E as NamespaceKind, F as RepoProvider, G as WebhookVerificationMethod, H as UserRef, I as Repository, L as ResolveRefParams, M as RefMatch, N as RefType, O as ParsedWebhookEvent, P as RepoCapabilities, R as SearchRefsParams, S as ListRepositoriesParams, T as Namespace, U as Webhook, V as UpdateWebhookParams, W as WebhookEventType, _ as GitActor, a as CloneUrl, b as ListCommitsParams, c as DeleteWebhookParams, d as GetBranchParams, f as GetCloneUrlParams, g as GetWebhookParams, h as GetTagParams, i as Branch, j as ProviderSearchRefsParams, k as ProviderName, l as DownloadArchiveParams, m as GetRepositoryParams, n as ArchiveFormat, o as Commit, p as GetCommitParams, r as AuthenticatedUser, s as CreateWebhookParams, t as Archive, u as GetAuthenticatedUserParams, v as IncomingWebhookRequest, w as ListWebhooksParams, x as ListNamespacesParams, y as ListBranchesParams, z as Tag } from "./types-DfiRluvJ.js";
 //#region src/client.d.ts
 interface RetryOptions {
   rateLimit?: boolean;
@@ -92,4 +92,4 @@ declare class RepoError extends Error {
   constructor(message: string, options: RepoErrorOptions);
 }
 //#endregion
-export { type Archive, type ArchiveFormat, type AuthenticatedUser, type Branch, type CloneUrl, type Commit, type CreateClientOptions, type CreateWebhookParams, type DeleteWebhookParams, type DetectWebhookProviderInput, type DownloadArchiveParams, type GetAuthenticatedUserParams, type GetBranchParams, type GetCloneUrlParams, type GetCommitParams, type GetRepositoryParams, type GetTagParams, type GetWebhookParams, type GitActor, type IncomingWebhookRequest, type ListBranchesParams, type ListCommitsParams, type ListNamespacesParams, type ListRepositoriesParams, type ListTagsParams, type ListWebhooksParams, type Namespace, type NamespaceKind, type Page, type ParsedWebhookEvent, type ProviderName, type ProviderSearchRefsParams, type RefMatch, type RefType, type RepoCapabilities, type RepoClient, RepoError, type RepoErrorCode, type RepoErrorOptions, type RepoProvider, type Repository, type ResolveRefParams, type RetryOptions, type SearchRefsParams, type Tag, type TokenProvider, type UpdateWebhookParams, type UserRef, type Webhook, type WebhookEventType, type WebhookVerificationMethod, createClient, detectWebhookProvider };
+export { type Archive, type ArchiveFormat, type AuthenticatedUser, type Branch, type CloneUrl, type Commit, type CreateClientOptions, type CreateWebhookParams, type DeleteWebhookParams, type DetectWebhookProviderInput, type DownloadArchiveParams, type GetAuthenticatedUserParams, type GetBranchParams, type GetCloneUrlParams, type GetCommitParams, type GetRepositoryParams, type GetTagParams, type GetWebhookParams, type GitActor, type IncomingWebhookRequest, type ListBranchesParams, type ListCommitsParams, type ListNamespacesParams, type ListRepositoriesParams, type ListTagsParams, type ListWebhooksParams, type Namespace, type NamespaceKind, type Page, type ParsedWebhookEvent, type ProviderName, type ProviderRefMatch, type ProviderSearchRefsParams, type RefMatch, type RefType, type RepoCapabilities, type RepoClient, RepoError, type RepoErrorCode, type RepoErrorOptions, type RepoProvider, type Repository, type ResolveRefParams, type RetryOptions, type SearchRefsParams, type Tag, type TokenProvider, type UpdateWebhookParams, type UserRef, type Webhook, type WebhookEventType, type WebhookVerificationMethod, createClient, detectWebhookProvider };

package/dist/index.js

@@ -10,29 +10,39 @@ const ALL_REF_TYPES = [
 	"commit"
 ];
 const COMMIT_SHA_PATTERN = /^[0-9a-f]{4,40}$/i;
-function branchMatch(branch) {
+const FULL_COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+const BRANCH_REF_PREFIX = "refs/heads/";
+const TAG_REF_PREFIX = "refs/tags/";
+function qualifyRef(match) {
+	const ref = match.type === "branch" ? `${BRANCH_REF_PREFIX}${match.name}` : match.type === "tag" ? `${TAG_REF_PREFIX}${match.name}` : match.sha;
 	return {
+		...match,
+		ref
+	};
+}
+function branchMatch(branch) {
+	return qualifyRef({
 		type: "branch",
 		name: branch.name,
 		sha: branch.sha,
 		raw: branch.raw
-	};
+	});
 }
 function tagMatch(tag) {
-	return {
+	return qualifyRef({
 		type: "tag",
 		name: tag.name,
 		sha: tag.sha,
 		raw: tag.raw
-	};
+	});
 }
 function commitMatch(commit) {
-	return {
+	return qualifyRef({
 		type: "commit",
 		name: commit.sha,
 		sha: commit.sha,
 		raw: commit.raw
-	};
+	});
 }
 function createClient(options) {
 	const { provider } = options;
@@ -192,7 +202,7 @@ function createClient(options) {
 					types: refTypes,
 					limit,
 					signal
-				})) : [], types.includes("commit") && COMMIT_SHA_PATTERN.test(query) ? withRetry(() => provider.getCommit({
+				})).then((matches) => matches.map(qualifyRef)) : [], types.includes("commit") && COMMIT_SHA_PATTERN.test(query) ? withRetry(() => provider.getCommit({
 					repo,
 					ref: query,
 					signal
@@ -205,8 +215,16 @@ function createClient(options) {
 			resolve: async (params) => {
 				requireNonEmpty(params.repo, "repo");
 				requireNonEmpty(params.ref, "ref");
-				const { repo, ref, type, signal } = params;
-				if (ref === "HEAD" && (type === void 0 || type === "branch")) {
+				const { repo, signal } = params;
+				let { ref, type } = params;
+				const impliedType = ref.startsWith(BRANCH_REF_PREFIX) ? "branch" : ref.startsWith(TAG_REF_PREFIX) ? "tag" : void 0;
+				if (impliedType !== void 0) {
+					if (type !== void 0 && type !== impliedType) fail("validation", `Fully-qualified ref '${ref}' contradicts type '${type}'`);
+					type = impliedType;
+					ref = ref.slice(impliedType === "branch" ? 11 : 10);
+					requireNonEmpty(ref, "ref");
+				}
+				if (impliedType === void 0 && ref === "HEAD" && (type === void 0 || type === "branch")) {
 					const defaultBranch = (await withRetry(() => provider.getRepository({
 						repo,
 						signal
@@ -226,6 +244,17 @@ function createClient(options) {
 					ref,
 					signal
 				})));
+				let commitProbeError;
+				if (type === void 0 && FULL_COMMIT_SHA_PATTERN.test(ref)) try {
+					return commitMatch(await withRetry(() => provider.getCommit({
+						repo,
+						ref,
+						signal
+					})));
+				} catch (error) {
+					if (error instanceof RepoError && (error.code === "not_found" || error.code === "validation" || error.code === "unsupported")) commitProbeError = error;
+					else throw error;
+				}
 				const [tagResult, branchResult] = await Promise.allSettled([type === "branch" ? void 0 : withRetry(() => provider.getTag({
 					repo,
 					name: ref,
@@ -242,11 +271,14 @@ function createClient(options) {
 				if (branchResult.status === "fulfilled") {
 					if (branchResult.value !== void 0) return branchMatch(branchResult.value);
 				} else if (!isMiss(branchResult)) throw branchResult.reason;
-				if (type === void 0 && COMMIT_SHA_PATTERN.test(ref)) return commitMatch(await withRetry(() => provider.getCommit({
-					repo,
-					ref,
-					signal
-				})));
+				if (type === void 0 && COMMIT_SHA_PATTERN.test(ref)) {
+					if (commitProbeError !== void 0) throw commitProbeError;
+					return commitMatch(await withRetry(() => provider.getCommit({
+						repo,
+						ref,
+						signal
+					})));
+				}
 				throw new RepoError(`Ref not found: ${ref}`, {
 					code: "not_found",
 					provider: provider.name

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { E as NamespaceKind, F as Repository, H as Webhook, N as RepoCapabilities, P as RepoProvider, R as Tag, T as Namespace, U as WebhookEventType, i as Branch, k as ProviderName, o as Commit } from "./types-CTeiAxMy.js";
+import { E as NamespaceKind, F as RepoProvider, I as Repository, P as RepoCapabilities, T as Namespace, U as Webhook, W as WebhookEventType, i as Branch, k as ProviderName, o as Commit, z as Tag } from "./types-DfiRluvJ.js";
 //#region src/providers/testing/index.d.ts
 interface InMemoryNamespaceSeed {
   id: string;

package/dist/{types-CTeiAxMy.d.ts → types-DfiRluvJ.d.ts}

@@ -93,10 +93,14 @@ type RefType = 'branch' | 'tag' | 'commit';
 interface RefMatch {
   type: RefType;
   name: string;
+  /** Fully-qualified form — `refs/heads/<name>` for branches, `refs/tags/<name>` for tags, the SHA itself for commits. Any `ref` value round-trips through `refs.resolve`. */
+  ref: string;
   /** SHA the ref points to. In `refs.search` results on GitHub and Gitea, annotated tags carry the tag object SHA rather than the commit; `refs.resolve` and `tags.get` always return the peeled commit SHA. */
   sha: string;
   raw: unknown;
 }
+/** `RefMatch` as produced by provider adapters, before the client derives the fully-qualified `ref`. */
+type ProviderRefMatch = Omit<RefMatch, 'ref'>;
 interface Webhook {
   id: string;
   url: string;
@@ -188,8 +192,9 @@ interface GetTagParams extends BaseParams {
 }
 interface ResolveRefParams extends BaseParams {
   repo: string;
+  /** A branch or tag name, a fully-qualified ref (`refs/heads/…`, `refs/tags/…`), a 4–40 hex commit SHA, or `HEAD`. */
   ref: string;
-  /** Restrict resolution to one ref type; when omitted, branches and tags are tried (tag wins on collision) before falling back to commit SHAs. */
+  /** Restrict resolution to one ref type; when omitted, a full 40-hex `ref` is tried as a commit first, then branches and tags (tag wins on collision), then abbreviated commit SHAs. A fully-qualified `ref` implies its type; passing a contradicting `type` throws a validation error. */
   type?: RefType;
 }
 interface SearchRefsParams extends BaseParams {
@@ -269,7 +274,7 @@ interface RepoProvider {
   /** Exact-match a tag by name, peeled to the commit SHA for annotated tags; throws `not_found` on a miss. */
   getTag(params: GetTagParams): Promise<Tag>;
   /** Prefix-match refs of the requested types, branches before tags, at most `limit` results. */
-  searchRefs(params: ProviderSearchRefsParams): Promise<RefMatch[]>;
+  searchRefs(params: ProviderSearchRefsParams): Promise<ProviderRefMatch[]>;
   downloadArchive(params: DownloadArchiveParams): Promise<Archive>;
   getCloneUrl(params: GetCloneUrlParams): Promise<CloneUrl>;
   createWebhook(params: CreateWebhookParams): Promise<Webhook>;
@@ -279,4 +284,4 @@ interface RepoProvider {
   deleteWebhook(params: DeleteWebhookParams): Promise<void>;
 }
 //#endregion
-export { ProviderSearchRefsParams as A, UpdateWebhookParams as B, ListTagsParams as C, Page as D, NamespaceKind as E, Repository as F, Webhook as H, ResolveRefParams as I, SearchRefsParams as L, RefType as M, RepoCapabilities as N, ParsedWebhookEvent as O, RepoProvider as P, Tag as R, ListRepositoriesParams as S, Namespace as T, WebhookEventType as U, UserRef as V, WebhookVerificationMethod as W, GitActor as _, CloneUrl as a, ListCommitsParams as b, DeleteWebhookParams as c, GetBranchParams as d, GetCloneUrlParams as f, GetWebhookParams as g, GetTagParams as h, Branch as i, RefMatch as j, ProviderName as k, DownloadArchiveParams as l, GetRepositoryParams as m, ArchiveFormat as n, Commit as o, GetCommitParams as p, AuthenticatedUser as r, CreateWebhookParams as s, Archive as t, GetAuthenticatedUserParams as u, IncomingWebhookRequest as v, ListWebhooksParams as w, ListNamespacesParams as x, ListBranchesParams as y, TokenProvider as z };
+export { ProviderRefMatch as A, TokenProvider as B, ListTagsParams as C, Page as D, NamespaceKind as E, RepoProvider as F, WebhookVerificationMethod as G, UserRef as H, Repository as I, ResolveRefParams as L, RefMatch as M, RefType as N, ParsedWebhookEvent as O, RepoCapabilities as P, SearchRefsParams as R, ListRepositoriesParams as S, Namespace as T, Webhook as U, UpdateWebhookParams as V, WebhookEventType as W, GitActor as _, CloneUrl as a, ListCommitsParams as b, DeleteWebhookParams as c, GetBranchParams as d, GetCloneUrlParams as f, GetWebhookParams as g, GetTagParams as h, Branch as i, ProviderSearchRefsParams as j, ProviderName as k, DownloadArchiveParams as l, GetRepositoryParams as m, ArchiveFormat as n, Commit as o, GetCommitParams as p, AuthenticatedUser as r, CreateWebhookParams as s, Archive as t, GetAuthenticatedUserParams as u, IncomingWebhookRequest as v, ListWebhooksParams as w, ListNamespacesParams as x, ListBranchesParams as y, Tag as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Unified TypeScript SDK for git providers — GitHub, GitLab, Bitbucket, Azure DevOps, Gitea",
   "license": "MIT",
   "author": "Robin Genz <mail@robingenz.dev>",
@@ -76,8 +76,8 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check .",
     "docs:dev": "blume dev",
     "docs:build": "blume build && rm -rf .blume-dist && cp -R dist .blume-dist",
     "docs:preview": "blume preview",