feat(gitea): add domain model classes, helpers, and refactor GiteaClient internals; expand README with usage and docs
This commit is contained in:
@@ -1,5 +1,4 @@
|
||||
import * as plugins from './gitea.plugins.js';
|
||||
import { logger } from './gitea.logging.js';
|
||||
import type {
|
||||
IGiteaUser,
|
||||
IGiteaRepository,
|
||||
@@ -13,23 +12,26 @@ import type {
|
||||
IListOptions,
|
||||
IActionRunListOptions,
|
||||
} from './gitea.interfaces.js';
|
||||
import { GiteaOrganization } from './gitea.classes.organization.js';
|
||||
import { GiteaRepository } from './gitea.classes.repository.js';
|
||||
import { autoPaginate, toGiteaApiStatus } from './gitea.helpers.js';
|
||||
|
||||
export class GiteaClient {
|
||||
private baseUrl: string;
|
||||
private token: string;
|
||||
|
||||
constructor(baseUrl: string, token: string) {
|
||||
// Remove trailing slash if present
|
||||
this.baseUrl = baseUrl.replace(/\/+$/, '');
|
||||
this.token = token;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// HTTP helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
// ===========================================================================
|
||||
// HTTP helpers (internal)
|
||||
// ===========================================================================
|
||||
|
||||
private async request<T = any>(
|
||||
method: 'GET' | 'POST' | 'PUT' | 'DELETE',
|
||||
/** @internal */
|
||||
async request<T = any>(
|
||||
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
|
||||
path: string,
|
||||
data?: any,
|
||||
customHeaders?: Record<string, string>,
|
||||
@@ -62,6 +64,9 @@ export class GiteaClient {
|
||||
case 'PUT':
|
||||
response = await builder.put();
|
||||
break;
|
||||
case 'PATCH':
|
||||
response = await builder.patch();
|
||||
break;
|
||||
case 'DELETE':
|
||||
response = await builder.delete();
|
||||
break;
|
||||
@@ -79,7 +84,8 @@ export class GiteaClient {
|
||||
}
|
||||
}
|
||||
|
||||
private async requestText(
|
||||
/** @internal */
|
||||
async requestText(
|
||||
method: 'GET' | 'POST' | 'PUT' | 'DELETE',
|
||||
path: string,
|
||||
): Promise<string> {
|
||||
@@ -114,9 +120,22 @@ export class GiteaClient {
|
||||
return response.text();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Connection
|
||||
// ---------------------------------------------------------------------------
|
||||
/** @internal — fetch binary data (e.g. avatar images) */
|
||||
async requestBinary(path: string): Promise<Uint8Array> {
|
||||
const url = `${this.baseUrl}${path}`;
|
||||
const response = await fetch(url, {
|
||||
headers: { 'Authorization': `token ${this.token}` },
|
||||
});
|
||||
if (!response.ok) {
|
||||
throw new Error(`GET ${path}: ${response.status} ${response.statusText}`);
|
||||
}
|
||||
const buf = await response.arrayBuffer();
|
||||
return new Uint8Array(buf);
|
||||
}
|
||||
|
||||
// ===========================================================================
|
||||
// Public API — Connection
|
||||
// ===========================================================================
|
||||
|
||||
public async testConnection(): Promise<ITestConnectionResult> {
|
||||
try {
|
||||
@@ -127,11 +146,81 @@ export class GiteaClient {
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Repositories
|
||||
// ---------------------------------------------------------------------------
|
||||
// ===========================================================================
|
||||
// Public API — Organizations (returns rich objects)
|
||||
// ===========================================================================
|
||||
|
||||
public async getRepos(opts?: IListOptions): Promise<IGiteaRepository[]> {
|
||||
/**
|
||||
* Get all organizations (auto-paginated).
|
||||
*/
|
||||
public async getOrgs(opts?: IListOptions): Promise<GiteaOrganization[]> {
|
||||
return autoPaginate(
|
||||
(page, perPage) => this.requestGetOrgs({ ...opts, page, perPage }),
|
||||
opts,
|
||||
).then(orgs => orgs.map(o => new GiteaOrganization(this, o)));
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a single organization by name.
|
||||
*/
|
||||
public async getOrg(orgName: string): Promise<GiteaOrganization> {
|
||||
const raw = await this.requestGetOrg(orgName);
|
||||
return new GiteaOrganization(this, raw);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new organization.
|
||||
*/
|
||||
public async createOrg(name: string, opts?: {
|
||||
fullName?: string;
|
||||
description?: string;
|
||||
visibility?: string;
|
||||
}): Promise<GiteaOrganization> {
|
||||
const raw = await this.requestCreateOrg(name, opts);
|
||||
return new GiteaOrganization(this, raw);
|
||||
}
|
||||
|
||||
// ===========================================================================
|
||||
// Public API — Repositories (returns rich objects)
|
||||
// ===========================================================================
|
||||
|
||||
/**
|
||||
* Search/list all repositories (auto-paginated).
|
||||
*/
|
||||
public async getRepos(opts?: IListOptions): Promise<GiteaRepository[]> {
|
||||
return autoPaginate(
|
||||
(page, perPage) => this.requestGetRepos({ ...opts, page, perPage }),
|
||||
opts,
|
||||
).then(repos => repos.map(r => new GiteaRepository(this, r)));
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a single repository by owner/repo.
|
||||
*/
|
||||
public async getRepo(ownerRepo: string): Promise<GiteaRepository> {
|
||||
const raw = await this.requestGetRepo(ownerRepo);
|
||||
return new GiteaRepository(this, raw);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a repository within an organization.
|
||||
*/
|
||||
public async createOrgRepo(orgName: string, name: string, opts?: {
|
||||
description?: string;
|
||||
private?: boolean;
|
||||
}): Promise<GiteaRepository> {
|
||||
const raw = await this.requestCreateOrgRepo(orgName, name, opts);
|
||||
return new GiteaRepository(this, raw);
|
||||
}
|
||||
|
||||
// ===========================================================================
|
||||
// Internal request methods — called by domain classes
|
||||
// ===========================================================================
|
||||
|
||||
// --- Repos ---
|
||||
|
||||
/** @internal */
|
||||
async requestGetRepos(opts?: IListOptions): Promise<IGiteaRepository[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
let url = `/api/v1/repos/search?page=${page}&limit=${limit}&sort=updated`;
|
||||
@@ -142,40 +231,104 @@ export class GiteaClient {
|
||||
return body.data || body;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Organizations
|
||||
// ---------------------------------------------------------------------------
|
||||
/** @internal */
|
||||
async requestGetRepo(ownerRepo: string): Promise<IGiteaRepository> {
|
||||
return this.request<IGiteaRepository>('GET', `/api/v1/repos/${ownerRepo}`);
|
||||
}
|
||||
|
||||
public async getOrgs(opts?: IListOptions): Promise<IGiteaOrganization[]> {
|
||||
/** @internal */
|
||||
async requestCreateOrgRepo(orgName: string, name: string, opts?: {
|
||||
description?: string;
|
||||
private?: boolean;
|
||||
}): Promise<IGiteaRepository> {
|
||||
return this.request<IGiteaRepository>('POST', `/api/v1/orgs/${encodeURIComponent(orgName)}/repos`, {
|
||||
name,
|
||||
description: opts?.description || '',
|
||||
private: opts?.private ?? true,
|
||||
});
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestPatchRepo(ownerRepo: string, data: Record<string, any>): Promise<void> {
|
||||
await this.request('PATCH', `/api/v1/repos/${ownerRepo}`, data);
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestSetRepoTopics(ownerRepo: string, topics: string[]): Promise<void> {
|
||||
await this.request('PUT', `/api/v1/repos/${ownerRepo}/topics`, { topics });
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestPostRepoAvatar(ownerRepo: string, imageBase64: string): Promise<void> {
|
||||
await this.request('POST', `/api/v1/repos/${ownerRepo}/avatar`, { image: imageBase64 });
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestDeleteRepoAvatar(ownerRepo: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/repos/${ownerRepo}/avatar`);
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestTransferRepo(ownerRepo: string, newOwner: string, teamIds?: number[]): Promise<void> {
|
||||
const body: any = { new_owner: newOwner };
|
||||
if (teamIds?.length) body.team_ids = teamIds;
|
||||
await this.request('POST', `/api/v1/repos/${ownerRepo}/transfer`, body);
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestDeleteRepo(owner: string, repo: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`);
|
||||
}
|
||||
|
||||
// --- Repo Branches & Tags ---
|
||||
|
||||
/** @internal */
|
||||
async requestGetRepoBranches(ownerRepo: string, opts?: IListOptions): Promise<IGiteaBranch[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
return this.request<IGiteaBranch[]>('GET', `/api/v1/repos/${ownerRepo}/branches?page=${page}&limit=${limit}`);
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestGetRepoTags(ownerRepo: string, opts?: IListOptions): Promise<IGiteaTag[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
return this.request<IGiteaTag[]>('GET', `/api/v1/repos/${ownerRepo}/tags?page=${page}&limit=${limit}`);
|
||||
}
|
||||
|
||||
// --- Repo Secrets ---
|
||||
|
||||
/** @internal */
|
||||
async requestGetRepoSecrets(ownerRepo: string): Promise<IGiteaSecret[]> {
|
||||
return this.request<IGiteaSecret[]>('GET', `/api/v1/repos/${ownerRepo}/actions/secrets`);
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestSetRepoSecret(ownerRepo: string, key: string, value: string): Promise<void> {
|
||||
await this.request('PUT', `/api/v1/repos/${ownerRepo}/actions/secrets/${key}`, { data: value });
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestDeleteRepoSecret(ownerRepo: string, key: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/repos/${ownerRepo}/actions/secrets/${key}`);
|
||||
}
|
||||
|
||||
// --- Organizations ---
|
||||
|
||||
/** @internal */
|
||||
async requestGetOrgs(opts?: IListOptions): Promise<IGiteaOrganization[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
return this.request<IGiteaOrganization[]>('GET', `/api/v1/orgs?page=${page}&limit=${limit}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a single organization by name
|
||||
*/
|
||||
public async getOrg(orgName: string): Promise<IGiteaOrganization> {
|
||||
/** @internal */
|
||||
async requestGetOrg(orgName: string): Promise<IGiteaOrganization> {
|
||||
return this.request<IGiteaOrganization>('GET', `/api/v1/orgs/${encodeURIComponent(orgName)}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* List repositories within an organization
|
||||
*/
|
||||
public async getOrgRepos(orgName: string, opts?: IListOptions): Promise<IGiteaRepository[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
let url = `/api/v1/orgs/${encodeURIComponent(orgName)}/repos?page=${page}&limit=${limit}&sort=updated`;
|
||||
if (opts?.search) {
|
||||
url += `&q=${encodeURIComponent(opts.search)}`;
|
||||
}
|
||||
return this.request<IGiteaRepository[]>('GET', url);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new organization
|
||||
*/
|
||||
public async createOrg(name: string, opts?: {
|
||||
/** @internal */
|
||||
async requestCreateOrg(name: string, opts?: {
|
||||
fullName?: string;
|
||||
description?: string;
|
||||
visibility?: string;
|
||||
@@ -188,87 +341,66 @@ export class GiteaClient {
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a repository within an organization
|
||||
*/
|
||||
public async createOrgRepo(orgName: string, name: string, opts?: {
|
||||
description?: string;
|
||||
private?: boolean;
|
||||
}): Promise<IGiteaRepository> {
|
||||
return this.request<IGiteaRepository>('POST', `/api/v1/orgs/${encodeURIComponent(orgName)}/repos`, {
|
||||
name,
|
||||
description: opts?.description || '',
|
||||
private: opts?.private ?? true,
|
||||
});
|
||||
/** @internal */
|
||||
async requestPatchOrg(orgName: string, data: Record<string, any>): Promise<void> {
|
||||
await this.request('PATCH', `/api/v1/orgs/${encodeURIComponent(orgName)}`, data);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Repository Branches & Tags
|
||||
// ---------------------------------------------------------------------------
|
||||
/** @internal */
|
||||
async requestPostOrgAvatar(orgName: string, imageBase64: string): Promise<void> {
|
||||
await this.request('POST', `/api/v1/orgs/${encodeURIComponent(orgName)}/avatar`, { image: imageBase64 });
|
||||
}
|
||||
|
||||
public async getRepoBranches(ownerRepo: string, opts?: IListOptions): Promise<IGiteaBranch[]> {
|
||||
/** @internal */
|
||||
async requestDeleteOrgAvatar(orgName: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/orgs/${encodeURIComponent(orgName)}/avatar`);
|
||||
}
|
||||
|
||||
/** @internal */
|
||||
async requestDeleteOrg(orgName: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/orgs/${encodeURIComponent(orgName)}`);
|
||||
}
|
||||
|
||||
// --- Org repos ---
|
||||
|
||||
/** @internal */
|
||||
async requestGetOrgRepos(orgName: string, opts?: IListOptions): Promise<IGiteaRepository[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
return this.request<IGiteaBranch[]>(
|
||||
'GET',
|
||||
`/api/v1/repos/${ownerRepo}/branches?page=${page}&limit=${limit}`,
|
||||
);
|
||||
let url = `/api/v1/orgs/${encodeURIComponent(orgName)}/repos?page=${page}&limit=${limit}&sort=updated`;
|
||||
if (opts?.search) {
|
||||
url += `&q=${encodeURIComponent(opts.search)}`;
|
||||
}
|
||||
return this.request<IGiteaRepository[]>('GET', url);
|
||||
}
|
||||
|
||||
public async getRepoTags(ownerRepo: string, opts?: IListOptions): Promise<IGiteaTag[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 50;
|
||||
return this.request<IGiteaTag[]>(
|
||||
'GET',
|
||||
`/api/v1/repos/${ownerRepo}/tags?page=${page}&limit=${limit}`,
|
||||
);
|
||||
}
|
||||
// --- Org Secrets ---
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Repository Secrets
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
public async getRepoSecrets(ownerRepo: string): Promise<IGiteaSecret[]> {
|
||||
return this.request<IGiteaSecret[]>('GET', `/api/v1/repos/${ownerRepo}/actions/secrets`);
|
||||
}
|
||||
|
||||
public async setRepoSecret(ownerRepo: string, key: string, value: string): Promise<void> {
|
||||
await this.request('PUT', `/api/v1/repos/${ownerRepo}/actions/secrets/${key}`, { data: value });
|
||||
}
|
||||
|
||||
public async deleteRepoSecret(ownerRepo: string, key: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/repos/${ownerRepo}/actions/secrets/${key}`);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Organization Secrets
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
public async getOrgSecrets(orgName: string): Promise<IGiteaSecret[]> {
|
||||
/** @internal */
|
||||
async requestGetOrgSecrets(orgName: string): Promise<IGiteaSecret[]> {
|
||||
return this.request<IGiteaSecret[]>('GET', `/api/v1/orgs/${orgName}/actions/secrets`);
|
||||
}
|
||||
|
||||
public async setOrgSecret(orgName: string, key: string, value: string): Promise<void> {
|
||||
/** @internal */
|
||||
async requestSetOrgSecret(orgName: string, key: string, value: string): Promise<void> {
|
||||
await this.request('PUT', `/api/v1/orgs/${orgName}/actions/secrets/${key}`, { data: value });
|
||||
}
|
||||
|
||||
public async deleteOrgSecret(orgName: string, key: string): Promise<void> {
|
||||
/** @internal */
|
||||
async requestDeleteOrgSecret(orgName: string, key: string): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/orgs/${orgName}/actions/secrets/${key}`);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Action Runs
|
||||
// ---------------------------------------------------------------------------
|
||||
// --- Action Runs ---
|
||||
|
||||
/**
|
||||
* List action runs for a repository with optional filters.
|
||||
* Supports status, branch, event, actor filtering.
|
||||
*/
|
||||
public async getActionRuns(ownerRepo: string, opts?: IActionRunListOptions): Promise<IGiteaActionRun[]> {
|
||||
/** @internal */
|
||||
async requestGetActionRuns(ownerRepo: string, opts?: IActionRunListOptions): Promise<IGiteaActionRun[]> {
|
||||
const page = opts?.page || 1;
|
||||
const limit = opts?.perPage || 30;
|
||||
let url = `/api/v1/repos/${ownerRepo}/actions/runs?page=${page}&limit=${limit}`;
|
||||
if (opts?.status) url += `&status=${encodeURIComponent(opts.status)}`;
|
||||
// Translate user-friendly status names to Gitea API values
|
||||
const apiStatus = toGiteaApiStatus(opts?.status);
|
||||
if (apiStatus) url += `&status=${encodeURIComponent(apiStatus)}`;
|
||||
if (opts?.branch) url += `&branch=${encodeURIComponent(opts.branch)}`;
|
||||
if (opts?.event) url += `&event=${encodeURIComponent(opts.event)}`;
|
||||
if (opts?.actor) url += `&actor=${encodeURIComponent(opts.actor)}`;
|
||||
@@ -276,49 +408,24 @@ export class GiteaClient {
|
||||
return body.workflow_runs || body;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a single action run's full details.
|
||||
*/
|
||||
public async getActionRun(ownerRepo: string, runId: number): Promise<IGiteaActionRun> {
|
||||
return this.request<IGiteaActionRun>(
|
||||
'GET',
|
||||
`/api/v1/repos/${ownerRepo}/actions/runs/${runId}`,
|
||||
);
|
||||
/** @internal */
|
||||
async requestGetActionRun(ownerRepo: string, runId: number): Promise<IGiteaActionRun> {
|
||||
return this.request<IGiteaActionRun>('GET', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* List jobs for an action run.
|
||||
*/
|
||||
public async getActionRunJobs(ownerRepo: string, runId: number): Promise<IGiteaActionRunJob[]> {
|
||||
/** @internal */
|
||||
async requestGetActionRunJobs(ownerRepo: string, runId: number): Promise<IGiteaActionRunJob[]> {
|
||||
const body = await this.request<any>('GET', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}/jobs`);
|
||||
return body.jobs || body;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a job's raw log output.
|
||||
*/
|
||||
public async getJobLog(ownerRepo: string, jobId: number): Promise<string> {
|
||||
/** @internal */
|
||||
async requestGetJobLog(ownerRepo: string, jobId: number): Promise<string> {
|
||||
return this.requestText('GET', `/api/v1/repos/${ownerRepo}/actions/jobs/${jobId}/logs`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Re-run an action run.
|
||||
*/
|
||||
public async rerunAction(ownerRepo: string, runId: number): Promise<void> {
|
||||
await this.request('POST', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}/rerun`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel a running action run.
|
||||
*/
|
||||
public async cancelAction(ownerRepo: string, runId: number): Promise<void> {
|
||||
await this.request('POST', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}/cancel`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Dispatch a workflow (trigger manually).
|
||||
*/
|
||||
public async dispatchWorkflow(
|
||||
/** @internal */
|
||||
async requestDispatchWorkflow(
|
||||
ownerRepo: string,
|
||||
workflowId: string,
|
||||
ref: string,
|
||||
@@ -331,14 +438,8 @@ export class GiteaClient {
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Repository Deletion
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
public async deleteRepo(owner: string, repo: string): Promise<void> {
|
||||
await this.request(
|
||||
'DELETE',
|
||||
`/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`,
|
||||
);
|
||||
/** @internal */
|
||||
async requestDeleteActionRun(ownerRepo: string, runId: number): Promise<void> {
|
||||
await this.request('DELETE', `/api/v1/repos/${ownerRepo}/actions/runs/${runId}`);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user