@canyonjs/git-provider 0.0.1

package/README.md

@@ -0,0 +1,49 @@
+# git-provider
+
+统一封装 GitHub / GitLab / Gitea 的常见仓库 API。
+
+## Development
+
+- Install dependencies:
+
+```bash
+npm install
+```
+
+- Run the unit tests:
+
+```bash
+npm run test
+```
+
+- Build the library:
+
+```bash
+npm run build
+```
+
+## Usage
+
+```ts
+import { createGitProviderClient } from 'git-provider'
+
+const client = createGitProviderClient({
+  provider: 'gitlab', // 'github' | 'gitlab' | 'gitea'
+  token: process.env.GIT_TOKEN
+})
+
+// 1) 根据 id 或 owner/repo 获取仓库摘要
+const repo = await client.getRepositorySummary('canyon-project/canyon')
+
+// 2) 获取 commit 摘要
+const commit = await client.getCommitSummary('canyon-project/canyon', 'abc123')
+
+// 3) 获取单个文件内容
+const file = await client.getFileContent('canyon-project/canyon', 'README.md', 'main')
+
+// 4) 获取指定 commit 的 zip 产物
+const archive = await client.downloadArchive('canyon-project/canyon', 'abc123')
+
+// 5) 比较两个 commit
+const compare = await client.compareCommits('canyon-project/canyon', 'fromSha', 'toSha')
+```

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+//#region src/index.d.ts
+type GitProvider = 'github' | 'gitlab' | 'gitea';
+interface GitProviderClientOptions {
+  provider: GitProvider;
+  token?: string;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+}
+interface RepositorySummary {
+  provider: GitProvider;
+  id: string;
+  fullName: string;
+  name: string;
+  defaultBranch?: string;
+  webUrl?: string;
+  private?: boolean;
+  description?: string | null;
+}
+interface CommitSummary {
+  provider: GitProvider;
+  sha: string;
+  shortSha: string;
+  title: string;
+  message: string;
+  authorName?: string;
+  authorEmail?: string;
+  authoredAt?: string;
+  webUrl?: string;
+}
+interface CompareSummary {
+  provider: GitProvider;
+  fromSha: string;
+  toSha: string;
+  status?: string;
+  aheadBy?: number;
+  behindBy?: number;
+  totalCommits: number;
+}
+interface FileContentResult {
+  provider: GitProvider;
+  path: string;
+  ref: string;
+  sha?: string;
+  size?: number;
+  content: string;
+}
+interface ArchiveResult {
+  provider: GitProvider;
+  ref: string;
+  contentType?: string | null;
+  fileName?: string;
+  size: number;
+  data: Uint8Array;
+}
+declare class GitProviderClient {
+  private readonly provider;
+  private readonly token?;
+  private readonly baseUrl;
+  private readonly extraHeaders;
+  constructor(options: GitProviderClientOptions);
+  getRepositorySummary(idOrPath: string | number): Promise<RepositorySummary>;
+  getCommitSummary(repo: string | number, sha: string): Promise<CommitSummary>;
+  compareCommits(repo: string | number, fromSha: string, toSha: string): Promise<CompareSummary>;
+  getFileContent(repo: string | number, filePath: string, ref: string): Promise<FileContentResult>;
+  downloadArchive(repo: string | number, ref: string): Promise<ArchiveResult>;
+  private fetchGiteaProject;
+  private resolveOwnerRepo;
+  private parseOwnerRepo;
+  private encodeGitLabProjectId;
+  private encodePath;
+  private parseFileNameFromHeaders;
+  private requestJson;
+  private fetchWithAuth;
+  private getAuthHeaders;
+}
+declare function createGitProviderClient(options: GitProviderClientOptions): GitProviderClient;
+//#endregion
+export { ArchiveResult, CommitSummary, CompareSummary, FileContentResult, GitProvider, GitProviderClient, GitProviderClientOptions, RepositorySummary, createGitProviderClient };

package/dist/index.mjs

@@ -0,0 +1,289 @@
+//#region src/index.ts
+function stripTrailingSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function normalizeProviderBaseUrl(provider, baseUrl) {
+	if (baseUrl) return stripTrailingSlash(baseUrl);
+	if (provider === "github") return "https://api.github.com";
+	if (provider === "gitlab") return "https://gitlab.com/api/v4";
+	return "https://gitea.com/api/v1";
+}
+function shortSha(sha) {
+	return sha.slice(0, 8);
+}
+function decodeBase64ToUtf8(value) {
+	return Buffer.from(value.replace(/\n/g, ""), "base64").toString("utf-8");
+}
+function isLikelyNumericRepoId(repo) {
+	return typeof repo === "number" || /^\d+$/.test(repo);
+}
+var GitProviderClient = class {
+	provider;
+	token;
+	baseUrl;
+	extraHeaders;
+	constructor(options) {
+		this.provider = options.provider;
+		this.token = options.token;
+		this.baseUrl = normalizeProviderBaseUrl(options.provider, options.baseUrl);
+		this.extraHeaders = options.headers ?? {};
+	}
+	async getRepositorySummary(idOrPath) {
+		if (this.provider === "github") {
+			const url = isLikelyNumericRepoId(idOrPath) ? `${this.baseUrl}/repositories/${idOrPath}` : `${this.baseUrl}/repos/${encodeURIComponent(String(idOrPath).split("/")[0])}/${encodeURIComponent(String(idOrPath).split("/")[1] ?? "")}`;
+			const project = await this.requestJson(url);
+			return {
+				provider: this.provider,
+				id: String(project.id),
+				fullName: project.full_name,
+				name: project.name,
+				defaultBranch: project.default_branch,
+				webUrl: project.html_url,
+				private: project.private,
+				description: project.description
+			};
+		}
+		if (this.provider === "gitlab") {
+			const projectId = this.encodeGitLabProjectId(idOrPath);
+			const project = await this.requestJson(`${this.baseUrl}/projects/${projectId}`);
+			return {
+				provider: this.provider,
+				id: String(project.id),
+				fullName: project.path_with_namespace,
+				name: project.name,
+				defaultBranch: project.default_branch,
+				webUrl: project.web_url,
+				private: project.visibility ? project.visibility !== "public" : void 0,
+				description: project.description
+			};
+		}
+		const project = await this.fetchGiteaProject(idOrPath);
+		return {
+			provider: this.provider,
+			id: String(project.id),
+			fullName: project.full_name,
+			name: project.name,
+			defaultBranch: project.default_branch,
+			webUrl: project.html_url,
+			private: project.private,
+			description: project.description
+		};
+	}
+	async getCommitSummary(repo, sha) {
+		if (this.provider === "github") {
+			const ownerRepo = await this.resolveOwnerRepo(repo);
+			const commit = await this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/commits/${encodeURIComponent(sha)}`);
+			return {
+				provider: this.provider,
+				sha: commit.sha,
+				shortSha: shortSha(commit.sha),
+				title: commit.commit?.message?.split("\n")[0] ?? "",
+				message: commit.commit?.message ?? "",
+				authorName: commit.commit?.author?.name,
+				authorEmail: commit.commit?.author?.email,
+				authoredAt: commit.commit?.author?.date,
+				webUrl: commit.html_url
+			};
+		}
+		if (this.provider === "gitlab") {
+			const pid = this.encodeGitLabProjectId(repo);
+			const commit = await this.requestJson(`${this.baseUrl}/projects/${pid}/repository/commits/${encodeURIComponent(sha)}`);
+			return {
+				provider: this.provider,
+				sha: commit.id,
+				shortSha: shortSha(commit.short_id ?? commit.id),
+				title: commit.title ?? commit.message?.split("\n")[0] ?? "",
+				message: commit.message ?? "",
+				authorName: commit.author_name,
+				authorEmail: commit.author_email,
+				authoredAt: commit.authored_date,
+				webUrl: commit.web_url
+			};
+		}
+		const ownerRepo = await this.resolveOwnerRepo(repo);
+		const commit = await this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/commits/${encodeURIComponent(sha)}`);
+		return {
+			provider: this.provider,
+			sha: commit.sha,
+			shortSha: shortSha(commit.sha),
+			title: commit.commit?.message?.split("\n")[0] ?? "",
+			message: commit.commit?.message ?? "",
+			authorName: commit.commit?.author?.name,
+			authorEmail: commit.commit?.author?.email,
+			authoredAt: commit.commit?.author?.date,
+			webUrl: commit.html_url
+		};
+	}
+	async compareCommits(repo, fromSha, toSha) {
+		if (this.provider === "github") {
+			const ownerRepo = await this.resolveOwnerRepo(repo);
+			const compare = await this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/compare/${encodeURIComponent(fromSha)}...${encodeURIComponent(toSha)}`);
+			return {
+				provider: this.provider,
+				fromSha,
+				toSha,
+				status: compare.status,
+				aheadBy: compare.ahead_by,
+				behindBy: compare.behind_by,
+				totalCommits: compare.total_commits ?? compare.commits?.length ?? 0
+			};
+		}
+		if (this.provider === "gitlab") {
+			const pid = this.encodeGitLabProjectId(repo);
+			const compare = await this.requestJson(`${this.baseUrl}/projects/${pid}/repository/compare?from=${encodeURIComponent(fromSha)}&to=${encodeURIComponent(toSha)}`);
+			return {
+				provider: this.provider,
+				fromSha,
+				toSha,
+				status: compare.compare_same_ref ? "identical" : "different",
+				totalCommits: compare.commits?.length ?? 0
+			};
+		}
+		const ownerRepo = await this.resolveOwnerRepo(repo);
+		const compare = await this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/compare/${encodeURIComponent(fromSha)}...${encodeURIComponent(toSha)}`);
+		return {
+			provider: this.provider,
+			fromSha,
+			toSha,
+			status: compare.status,
+			aheadBy: compare.ahead_by,
+			behindBy: compare.behind_by,
+			totalCommits: compare.total_commits ?? compare.commits?.length ?? 0
+		};
+	}
+	async getFileContent(repo, filePath, ref) {
+		if (this.provider === "github") {
+			const ownerRepo = await this.resolveOwnerRepo(repo);
+			const payload = await this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/contents/${this.encodePath(filePath)}?ref=${encodeURIComponent(ref)}`);
+			return {
+				provider: this.provider,
+				path: payload.path ?? filePath,
+				ref,
+				sha: payload.sha,
+				size: payload.size,
+				content: decodeBase64ToUtf8(payload.content ?? "")
+			};
+		}
+		if (this.provider === "gitlab") {
+			const pid = this.encodeGitLabProjectId(repo);
+			const payload = await this.requestJson(`${this.baseUrl}/projects/${pid}/repository/files/${this.encodePath(filePath)}?ref=${encodeURIComponent(ref)}`);
+			return {
+				provider: this.provider,
+				path: payload.file_path ?? filePath,
+				ref,
+				sha: payload.blob_id,
+				size: payload.size,
+				content: decodeBase64ToUtf8(payload.content ?? "")
+			};
+		}
+		const ownerRepo = await this.resolveOwnerRepo(repo);
+		const payload = await this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/contents/${this.encodePath(filePath)}?ref=${encodeURIComponent(ref)}`);
+		return {
+			provider: this.provider,
+			path: payload.path ?? filePath,
+			ref,
+			sha: payload.sha,
+			size: payload.size,
+			content: decodeBase64ToUtf8(payload.content ?? "")
+		};
+	}
+	async downloadArchive(repo, ref) {
+		let url;
+		if (this.provider === "gitlab") {
+			const pid = this.encodeGitLabProjectId(repo);
+			url = `${this.baseUrl}/projects/${pid}/repository/archive.zip?sha=${encodeURIComponent(ref)}`;
+		} else {
+			const ownerRepo = await this.resolveOwnerRepo(repo);
+			if (this.provider === "github") url = `${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/zipball/${encodeURIComponent(ref)}`;
+			else url = `${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}/archive/${encodeURIComponent(ref)}.zip`;
+		}
+		const response = await this.fetchWithAuth(url, { headers: { Accept: "application/zip" } });
+		if (!response.ok) {
+			const body = await response.text();
+			throw new Error(`[${this.provider}] request failed (${response.status}): ${body}`);
+		}
+		const data = new Uint8Array(await response.arrayBuffer());
+		return {
+			provider: this.provider,
+			ref,
+			contentType: response.headers.get("content-type"),
+			fileName: this.parseFileNameFromHeaders(response.headers),
+			size: data.byteLength,
+			data
+		};
+	}
+	async fetchGiteaProject(idOrPath) {
+		if (!isLikelyNumericRepoId(idOrPath)) {
+			const ownerRepo = this.parseOwnerRepo(String(idOrPath));
+			return this.requestJson(`${this.baseUrl}/repos/${encodeURIComponent(ownerRepo.owner)}/${encodeURIComponent(ownerRepo.repo)}`);
+		}
+		try {
+			return await this.requestJson(`${this.baseUrl}/repositories/${idOrPath}`);
+		} catch {
+			throw new Error("[gitea] numeric repository id not found; try owner/repo form");
+		}
+	}
+	async resolveOwnerRepo(repo) {
+		if (!isLikelyNumericRepoId(repo)) return this.parseOwnerRepo(String(repo));
+		if (this.provider === "gitlab") {
+			const project = await this.getRepositorySummary(repo);
+			return this.parseOwnerRepo(project.fullName);
+		}
+		const project = await this.getRepositorySummary(repo);
+		return this.parseOwnerRepo(project.fullName);
+	}
+	parseOwnerRepo(raw) {
+		const parts = raw.split("/");
+		if (parts.length < 2 || !parts[0] || !parts[1]) throw new Error(`invalid repository identifier "${raw}", expected "owner/repo" or numeric id`);
+		return {
+			owner: parts[0],
+			repo: parts.slice(1).join("/")
+		};
+	}
+	encodeGitLabProjectId(idOrPath) {
+		if (isLikelyNumericRepoId(idOrPath)) return String(idOrPath);
+		return this.encodePath(String(idOrPath));
+	}
+	encodePath(path) {
+		return path.split("/").filter(Boolean).map((piece) => encodeURIComponent(piece)).join("%2F");
+	}
+	parseFileNameFromHeaders(headers) {
+		const disposition = headers.get("content-disposition");
+		if (!disposition) return;
+		const utf8Match = disposition.match(/filename\*=UTF-8''([^;]+)/i);
+		if (utf8Match?.[1]) return decodeURIComponent(utf8Match[1]);
+		return disposition.match(/filename="([^"]+)"/i)?.[1];
+	}
+	async requestJson(url) {
+		const response = await this.fetchWithAuth(url);
+		if (!response.ok) {
+			const body = await response.text();
+			throw new Error(`[${this.provider}] request failed (${response.status}): ${body}`);
+		}
+		return response.json();
+	}
+	async fetchWithAuth(url, init) {
+		const headers = new Headers(init?.headers);
+		for (const [key, value] of Object.entries(this.getAuthHeaders())) headers.set(key, value);
+		for (const [key, value] of Object.entries(this.extraHeaders)) headers.set(key, value);
+		return fetch(url, {
+			...init,
+			headers
+		});
+	}
+	getAuthHeaders() {
+		const headers = {};
+		if (this.provider === "github") headers.Accept = "application/vnd.github+json";
+		else headers.Accept = "application/json";
+		if (!this.token) return headers;
+		if (this.provider === "gitlab") headers["PRIVATE-TOKEN"] = this.token;
+		else if (this.provider === "gitea") headers.Authorization = `token ${this.token}`;
+		else headers.Authorization = `Bearer ${this.token}`;
+		return headers;
+	}
+};
+function createGitProviderClient(options) {
+	return new GitProviderClient(options);
+}
+//#endregion
+export { GitProviderClient, createGitProviderClient };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@canyonjs/git-provider",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Unified Git provider client for GitHub, GitLab, and Gitea.",
+  "keywords": [
+    "git",
+    "github",
+    "gitlab",
+    "gitea",
+    "api"
+  ],
+  "author": "canyonjs",
+  "license": "MIT",
+  "homepage": "https://git.dev.sh.ctripcorp.com/canyon-project/git-provider#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.dev.sh.ctripcorp.com/canyon-project/git-provider.git"
+  },
+  "bugs": {
+    "url": "https://git.dev.sh.ctripcorp.com/canyon-project/git-provider/issues"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "bumpp": "^11.0.1",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp"
+  }
+}