feat(client): add rich domain classes, helpers, and refactor GitLabClient internals

ts/gitlab.classes.project.ts

@@ -0,0 +1,177 @@
+import type { GitLabClient } from './gitlab.classes.gitlabclient.js';
+import type { IGitLabProject, IListOptions, IVariableOptions, IPipelineListOptions } from './gitlab.interfaces.js';
+import { GitLabBranch } from './gitlab.classes.branch.js';
+import { GitLabTag } from './gitlab.classes.tag.js';
+import { GitLabProtectedBranch } from './gitlab.classes.protectedbranch.js';
+import { GitLabVariable } from './gitlab.classes.variable.js';
+import { GitLabPipeline } from './gitlab.classes.pipeline.js';
+import { autoPaginate } from './gitlab.helpers.js';
+
+export class GitLabProject {
+  // Raw data
+  public readonly id: number;
+  public readonly name: string;
+  public readonly fullPath: string;
+  public readonly description: string;
+  public readonly defaultBranch: string;
+  public readonly webUrl: string;
+  public readonly visibility: string;
+  public readonly topics: string[];
+  public readonly lastActivityAt: string;
+
+  /** @internal */
+  constructor(
+    private client: GitLabClient,
+    raw: IGitLabProject,
+  ) {
+    this.id = raw.id;
+    this.name = raw.name || '';
+    this.fullPath = raw.path_with_namespace || '';
+    this.description = raw.description || '';
+    this.defaultBranch = raw.default_branch || 'main';
+    this.webUrl = raw.web_url || '';
+    this.visibility = raw.visibility || 'private';
+    this.topics = raw.topics || [];
+    this.lastActivityAt = raw.last_activity_at || '';
+  }
+
+  // ---------------------------------------------------------------------------
+  // Branches & Tags
+  // ---------------------------------------------------------------------------
+
+  async getBranches(opts?: IListOptions): Promise<GitLabBranch[]> {
+    return autoPaginate(
+      (page, perPage) => this.client.requestGetRepoBranches(this.id, { ...opts, page, perPage }),
+      opts,
+    ).then(branches => branches.map(b => new GitLabBranch(b)));
+  }
+
+  async getTags(opts?: IListOptions): Promise<GitLabTag[]> {
+    return autoPaginate(
+      (page, perPage) => this.client.requestGetRepoTags(this.id, { ...opts, page, perPage }),
+      opts,
+    ).then(tags => tags.map(t => new GitLabTag(t)));
+  }
+
+  async getProtectedBranches(): Promise<GitLabProtectedBranch[]> {
+    const branches = await this.client.requestGetProtectedBranches(this.id);
+    return branches.map(b => new GitLabProtectedBranch(b));
+  }
+
+  async unprotectBranch(branchName: string): Promise<void> {
+    await this.client.requestUnprotectBranch(this.id, branchName);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Variables (CI/CD)
+  // ---------------------------------------------------------------------------
+
+  async getVariables(): Promise<GitLabVariable[]> {
+    const vars = await this.client.requestGetProjectVariables(this.id);
+    return vars.map(v => new GitLabVariable(v));
+  }
+
+  async createVariable(key: string, value: string, opts?: IVariableOptions): Promise<GitLabVariable> {
+    const raw = await this.client.requestCreateProjectVariable(this.id, key, value, opts);
+    return new GitLabVariable(raw);
+  }
+
+  async updateVariable(key: string, value: string, opts?: IVariableOptions): Promise<GitLabVariable> {
+    const raw = await this.client.requestUpdateProjectVariable(this.id, key, value, opts);
+    return new GitLabVariable(raw);
+  }
+
+  async deleteVariable(key: string): Promise<void> {
+    await this.client.requestDeleteProjectVariable(this.id, key);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Pipelines
+  // ---------------------------------------------------------------------------
+
+  async getPipelines(opts?: IPipelineListOptions): Promise<GitLabPipeline[]> {
+    return autoPaginate(
+      (page, perPage) => this.client.requestGetPipelines(this.id, { ...opts, page, perPage }),
+      opts,
+    ).then(pipelines => pipelines.map(p => new GitLabPipeline(this.client, p)));
+  }
+
+  async triggerPipeline(
+    ref: string,
+    variables?: { key: string; value: string; variable_type?: string }[],
+  ): Promise<GitLabPipeline> {
+    const raw = await this.client.requestTriggerPipeline(this.id, ref, variables);
+    return new GitLabPipeline(this.client, raw);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Mutation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Update project properties.
+   */
+  async update(data: {
+    name?: string;
+    path?: string;
+    description?: string;
+    defaultBranch?: string;
+    visibility?: string;
+    topics?: string[];
+  }): Promise<void> {
+    await this.client.requestUpdateProject(this.id, {
+      name: data.name,
+      path: data.path,
+      description: data.description,
+      default_branch: data.defaultBranch,
+      visibility: data.visibility,
+      topics: data.topics,
+    });
+  }
+
+  /**
+   * Upload an avatar image for this project (multipart FormData).
+   */
+  async setAvatar(imageData: Uint8Array, filename: string): Promise<void> {
+    await this.client.requestSetProjectAvatar(this.id, imageData, filename);
+  }
+
+  /**
+   * Remove the project's avatar.
+   */
+  async deleteAvatar(): Promise<void> {
+    await this.client.requestUpdateProject(this.id, { avatar: '' });
+  }
+
+  /**
+   * Transfer this project to a different namespace.
+   */
+  async transfer(namespaceId: number): Promise<void> {
+    await this.client.requestTransferProject(this.id, namespaceId);
+  }
+
+  /**
+   * Delete this project.
+   */
+  async delete(): Promise<void> {
+    await this.client.requestDeleteProject(this.id);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+
+  toJSON(): IGitLabProject {
+    return {
+      id: this.id,
+      name: this.name,
+      path_with_namespace: this.fullPath,
+      description: this.description,
+      default_branch: this.defaultBranch,
+      web_url: this.webUrl,
+      visibility: this.visibility,
+      topics: this.topics,
+      last_activity_at: this.lastActivityAt,
+    };
+  }
+}