@apiclient.xyz/gitlab 2.4.0 → 2.6.0

package/readme.md

@@ -1,16 +1,82 @@
 # @apiclient.xyz/gitlab
 
-A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.
+A powerful, fully-typed TypeScript client for the GitLab API 🚀
+
+[![npm version](https://img.shields.io/npm/v/@apiclient.xyz/gitlab.svg)](https://www.npmjs.com/package/@apiclient.xyz/gitlab)
+[![license](https://img.shields.io/npm/l/@apiclient.xyz/gitlab.svg)](./LICENSE)
+
+`@apiclient.xyz/gitlab` gives you a clean, object-oriented interface to the GitLab REST API. It wraps projects, groups, pipelines, jobs, CI/CD variables, branches, tags, protected branches, and test reports into rich domain classes with full auto-pagination support. Works with any GitLab instance -- cloud or self-hosted.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
 ## Install
 
 ```bash
 npm install @apiclient.xyz/gitlab
+# or
+pnpm install @apiclient.xyz/gitlab
 ```
 
-## Usage
+## Quick Start ⚡
+
+```typescript
+import { GitLabClient } from '@apiclient.xyz/gitlab';
+
+const client = new GitLabClient('https://gitlab.example.com', 'your-private-token');
+
+// Verify connectivity
+const { ok, error } = await client.testConnection();
+console.log(ok ? '✅ Connected!' : `❌ ${error}`);
+
+// Grab all your projects
+const projects = await client.getProjects();
+for (const project of projects) {
+  console.log(`${project.name} — ${project.webUrl}`);
+}
+```
+
+That's it. No boilerplate, no callback soup, just straightforward async/await.
+
+## Core Concepts 🧠
+
+### Rich Domain Objects
+
+Every API response is wrapped in a **domain class** that exposes typed properties and chainable methods. You never deal with raw JSON unless you want to -- every class has a `.toJSON()` escape hatch.
+
+```
+GitLabClient
+  ├── GitLabGroup          → .getProjects(), .getVariables(), .update(), .delete(), ...
+  ├── GitLabProject        → .getPipelines(), .getBranches(), .getVariables(), .triggerPipeline(), ...
+  │     ├── GitLabBranch
+  │     ├── GitLabTag
+  │     ├── GitLabProtectedBranch
+  │     └── GitLabVariable
+  ├── GitLabPipeline       → .getJobs(), .getTestReport(), .retry(), .cancel(), .delete()
+  │     ├── GitLabJob      → .getLog(), .retry(), .cancel(), .play(), .erase()
+  │     ├── GitLabPipelineVariable
+  │     └── GitLabTestReport
+  │           └── GitLabTestSuite
+  │                 └── GitLabTestCase
+  └── GitLabVariable
+```
+
+### Auto-Pagination 🔄
+
+List endpoints automatically page through **all** results by default. Need just one page? Pass `{ page: N }` explicitly.
+
+```typescript
+// Fetches ALL groups (auto-paginates transparently)
+const allGroups = await client.getGroups();
+
+// Fetches only page 2, 10 per page
+const page2 = await client.getGroups({ page: 2, perPage: 10 });
+```
 
-All examples below use ESM imports and async/await.
+The `autoPaginate` helper is also exported if you want to use it in custom integrations.
+
+## Usage
 
 ### Creating a Client
 
@@ -20,7 +86,7 @@ import { GitLabClient } from '@apiclient.xyz/gitlab';
 const client = new GitLabClient('https://gitlab.example.com', 'your-private-token');
 ```
 
-The constructor accepts the base URL of your GitLab instance and a personal access token (or project/group token) used for authentication via the `PRIVATE-TOKEN` header.
+The constructor takes the base URL of your GitLab instance and a personal access token (or project/group token) for `PRIVATE-TOKEN` header authentication.
 
 ### Testing the Connection
 
@@ -34,263 +100,502 @@ if (result.ok) {
 }
 ```
 
-### Listing Projects
+---
 
-Retrieve projects you are a member of, ordered by most recently updated.
+### Groups 🏢
+
+#### List All Groups
+
+```typescript
+const groups = await client.getGroups();
+
+// Search by name
+const devGroups = await client.getGroups({ search: 'platform' });
+
+for (const group of devGroups) {
+  console.log(`${group.id} — ${group.fullPath} (${group.visibility})`);
+}
+```
+
+#### Get a Single Group
+
+```typescript
+const group = await client.getGroup('my-org/my-team');
+console.log(group.name, group.webUrl);
+```
+
+#### Create a Group
+
+```typescript
+const newGroup = await client.createGroup('backend-team', 'backend-team');
+
+// Create a sub-group under an existing parent
+const subGroup = await client.createGroup('api-squad', 'api-squad', parentGroup.id);
+```
+
+#### Group Operations
+
+```typescript
+// Update properties
+await group.update({ description: 'The backend crew 🔧', visibility: 'internal' });
+
+// Upload / remove avatar
+await group.setAvatar(imageBytes, 'logo.png');
+await group.deleteAvatar();
+
+// Transfer to another parent group
+await group.transfer(targetGroupId);
+
+// List descendant sub-groups
+const children = await group.getDescendantGroups();
+
+// List projects inside the group
+const projects = await group.getProjects({ search: 'api' });
+
+// Delete
+await group.delete();
+```
+
+---
+
+### Projects 📦
+
+#### List All Projects
 
 ```typescript
-// First page, default 50 per page
 const projects = await client.getProjects();
 
 // Search with pagination
-const filtered = await client.getProjects({
-  search: 'my-service',
-  page: 1,
-  perPage: 20,
-});
+const matches = await client.getProjects({ search: 'my-service', perPage: 20 });
 
-for (const project of filtered) {
-  console.log(`${project.id} - ${project.path_with_namespace}`);
+for (const p of matches) {
+  console.log(`${p.id} — ${p.fullPath} [${p.defaultBranch}]`);
 }
 ```
 
-### Listing Groups
+#### Get a Single Project
 
 ```typescript
-const groups = await client.getGroups();
+// By numeric ID
+const project = await client.getProject(42);
+
+// By full path
+const project = await client.getProject('my-org/my-repo');
+```
+
+#### Create a Project
+
+```typescript
+const project = await client.createProject('new-service', {
+  namespaceId: group.id,
+  visibility: 'internal',
+  description: 'Our shiny new microservice',
+});
+```
 
-// Search groups by name
-const matchingGroups = await client.getGroups({ search: 'platform' });
+#### Project Operations
 
-for (const group of matchingGroups) {
-  console.log(`${group.id} - ${group.full_path}`);
+```typescript
+// Update properties
+await project.update({
+  description: 'Updated description',
+  defaultBranch: 'develop',
+  topics: ['typescript', 'api'],
+});
+
+// Avatar management
+await project.setAvatar(imageBytes, 'project-logo.png');
+await project.deleteAvatar();
+
+// Transfer to a different namespace
+await project.transfer(otherNamespaceId);
+
+// Delete
+await project.delete();
+```
+
+---
+
+### Branches & Tags 🌿
+
+```typescript
+// List all branches (auto-paginated)
+const branches = await project.getBranches();
+for (const b of branches) {
+  console.log(`${b.name} @ ${b.commitSha}`);
+}
+
+// List all tags
+const tags = await project.getTags();
+for (const t of tags) {
+  console.log(`${t.name} @ ${t.commitSha}`);
 }
 ```
 
-### Managing Project Variables
+#### Protected Branches 🔒
 
 ```typescript
-const projectId = 42;
+const protectedBranches = await project.getProtectedBranches();
+for (const pb of protectedBranches) {
+  console.log(`${pb.name} — force push: ${pb.allowForcePush}`);
+}
+
+// Remove branch protection
+await project.unprotectBranch('develop');
+```
+
+---
 
-// List all variables
-const vars = await client.getProjectVariables(projectId);
+### CI/CD Variables 🔑
 
-// Create a variable
-await client.createProjectVariable(projectId, 'DATABASE_URL', 'postgres://...', {
+Variables work identically on both projects and groups.
+
+#### Project Variables
+
+```typescript
+// List all
+const vars = await project.getVariables();
+
+// Create
+const dbVar = await project.createVariable('DATABASE_URL', 'postgres://localhost/db', {
   protected: true,
   masked: true,
   environment_scope: 'production',
 });
 
-// Update a variable
-await client.updateProjectVariable(projectId, 'DATABASE_URL', 'postgres://new-host/...', {
+// Update
+await project.updateVariable('DATABASE_URL', 'postgres://newhost/db', {
   protected: true,
 });
 
-// Delete a variable
-await client.deleteProjectVariable(projectId, 'DATABASE_URL');
+// Delete
+await project.deleteVariable('DATABASE_URL');
 ```
 
-### Managing Group Variables
-
-The group variable API mirrors the project variable API.
+#### Group Variables
 
 ```typescript
-const groupId = 7;
+const groupVars = await group.getVariables();
 
-// List all variables
-const groupVars = await client.getGroupVariables(groupId);
-
-// Create a variable
-await client.createGroupVariable(groupId, 'NPM_TOKEN', 'tok-xxx', {
+await group.createVariable('NPM_TOKEN', 'tok-xxx', {
   protected: false,
   masked: true,
   environment_scope: '*',
 });
 
-// Update a variable
-await client.updateGroupVariable(groupId, 'NPM_TOKEN', 'tok-yyy', {
-  masked: true,
+await group.updateVariable('NPM_TOKEN', 'tok-yyy');
+await group.deleteVariable('NPM_TOKEN');
+```
+
+Each `GitLabVariable` instance exposes typed properties:
+
+```typescript
+console.log(dbVar.key);              // 'DATABASE_URL'
+console.log(dbVar.value);            // 'postgres://...'
+console.log(dbVar.variableType);     // 'env_var'
+console.log(dbVar.protected);        // true
+console.log(dbVar.masked);           // true
+console.log(dbVar.environmentScope); // 'production'
+```
+
+---
+
+### Pipelines 🚀
+
+#### List & Filter Pipelines
+
+```typescript
+// Recent pipelines (auto-paginated)
+const pipelines = await project.getPipelines();
+
+// Advanced filtering
+const failed = await project.getPipelines({
+  status: 'failed',
+  ref: 'main',
+  source: 'push',
+  orderBy: 'updated_at',
+  sort: 'desc',
+  updatedAfter: '2025-01-01T00:00:00Z',
 });
 
-// Delete a variable
-await client.deleteGroupVariable(groupId, 'NPM_TOKEN');
+for (const p of failed) {
+  console.log(`Pipeline #${p.id} [${p.status}] on ${p.ref} — ${p.webUrl}`);
+}
+```
+
+#### Trigger a Pipeline
+
+```typescript
+const pipeline = await project.triggerPipeline('main', [
+  { key: 'DEPLOY_ENV', value: 'staging' },
+]);
+console.log(`Triggered pipeline #${pipeline.id}`);
 ```
 
-### Working with Pipelines
+#### Pipeline Actions
 
 ```typescript
-const projectId = 42;
+// Retry all failed jobs
+const retried = await pipeline.retry();
 
-// List recent pipelines
-const pipelines = await client.getPipelines(projectId, { page: 1, perPage: 10 });
+// Cancel a running pipeline
+const cancelled = await pipeline.cancel();
+
+// Delete a pipeline
+await pipeline.delete();
+```
 
-for (const pipeline of pipelines) {
-  console.log(`Pipeline #${pipeline.id} [${pipeline.status}] on ${pipeline.ref}`);
+#### Pipeline Variables & Test Reports
+
+```typescript
+// Get variables used in a pipeline run
+const pipelineVars = await pipeline.getVariables();
+for (const v of pipelineVars) {
+  console.log(`${v.key} = ${v.value} (${v.variableType})`);
 }
 
-// Get jobs for a specific pipeline
-const jobs = await client.getPipelineJobs(projectId, pipelines[0].id);
+// Get the test report
+const report = await pipeline.getTestReport();
+console.log(`Tests: ${report.totalCount} total, ${report.successCount} passed, ${report.failedCount} failed`);
+
+for (const suite of report.testSuites) {
+  console.log(`  Suite "${suite.name}": ${suite.totalCount} tests (${suite.failedCount} failures)`);
+  for (const tc of suite.testCases) {
+    if (tc.status === 'failed') {
+      console.log(`    ❌ ${tc.name}: ${tc.systemOutput}`);
+    }
+  }
+}
+```
+
+---
+
+### Jobs ⚙️
+
+```typescript
+// Get all jobs for a pipeline
+const jobs = await pipeline.getJobs();
+
+// Filter by scope
+const failedJobs = await pipeline.getJobs({ scope: ['failed'] });
+
 for (const job of jobs) {
-  console.log(`  Job "${job.name}" (${job.stage}): ${job.status}`);
+  console.log(`Job "${job.name}" (${job.stage}) — ${job.status} [${job.duration}s]`);
 }
+```
+
+#### Job Actions
 
-// Read the raw log output of a job
-const log = await client.getJobLog(projectId, jobs[0].id);
+```typescript
+// Read the raw log output
+const log = await job.getLog();
 console.log(log);
 
-// Retry a failed pipeline
-await client.retryPipeline(projectId, pipelines[0].id);
+// Retry a failed job
+const retriedJob = await job.retry();
 
-// Cancel a running pipeline
-await client.cancelPipeline(projectId, pipelines[0].id);
+// Cancel a running job
+const cancelledJob = await job.cancel();
+
+// Trigger a manual job
+const played = await job.play();
+
+// Erase job artifacts and trace
+await job.erase();
+```
+
+#### Job Properties
+
+Each `GitLabJob` exposes rich metadata:
+
+```typescript
+job.id              // number
+job.name            // 'build'
+job.stage           // 'test'
+job.status          // 'success' | 'failed' | 'running' | ...
+job.ref             // 'main'
+job.tag             // false
+job.webUrl          // full URL to the job
+job.duration        // seconds
+job.queuedDuration  // seconds waiting in queue
+job.coverage        // code coverage percentage
+job.allowFailure    // whether failure is acceptable
+job.failureReason   // reason for failure, if any
 ```
 
-## API Reference
+---
+
+## API Reference 📚
 
 ### `GitLabClient`
 
-| Method | Signature | Returns | Description |
-|---|---|---|---|
-| `constructor` | `(baseUrl: string, token: string)` | `GitLabClient` | Create a new client instance. |
-| `testConnection` | `()` | `Promise<ITestConnectionResult>` | Verify the token and connectivity. |
-| `getProjects` | `(opts?: IListOptions)` | `Promise<IGitLabProject[]>` | List projects you are a member of. |
-| `getGroups` | `(opts?: IListOptions)` | `Promise<IGitLabGroup[]>` | List accessible groups. |
-| `getProjectVariables` | `(projectId: number \| string)` | `Promise<IGitLabVariable[]>` | List all CI/CD variables for a project. |
-| `createProjectVariable` | `(projectId: number \| string, key: string, value: string, opts?: IVariableOptions)` | `Promise<IGitLabVariable>` | Create a CI/CD variable on a project. |
-| `updateProjectVariable` | `(projectId: number \| string, key: string, value: string, opts?: IVariableOptions)` | `Promise<IGitLabVariable>` | Update an existing project variable. |
-| `deleteProjectVariable` | `(projectId: number \| string, key: string)` | `Promise<void>` | Delete a project variable. |
-| `getGroupVariables` | `(groupId: number \| string)` | `Promise<IGitLabVariable[]>` | List all CI/CD variables for a group. |
-| `createGroupVariable` | `(groupId: number \| string, key: string, value: string, opts?: IVariableOptions)` | `Promise<IGitLabVariable>` | Create a CI/CD variable on a group. |
-| `updateGroupVariable` | `(groupId: number \| string, key: string, value: string, opts?: IVariableOptions)` | `Promise<IGitLabVariable>` | Update an existing group variable. |
-| `deleteGroupVariable` | `(groupId: number \| string, key: string)` | `Promise<void>` | Delete a group variable. |
-| `getPipelines` | `(projectId: number \| string, opts?: IListOptions)` | `Promise<IGitLabPipeline[]>` | List pipelines for a project, newest first. |
-| `getPipelineJobs` | `(projectId: number \| string, pipelineId: number)` | `Promise<IGitLabJob[]>` | Get all jobs for a pipeline. |
-| `getJobLog` | `(projectId: number \| string, jobId: number)` | `Promise<string>` | Retrieve the raw trace/log of a job. |
-| `retryPipeline` | `(projectId: number \| string, pipelineId: number)` | `Promise<void>` | Retry all failed jobs in a pipeline. |
-| `cancelPipeline` | `(projectId: number \| string, pipelineId: number)` | `Promise<void>` | Cancel a running pipeline. |
-
-## Types
+| Method | Returns | Description |
+|---|---|---|
+| `new GitLabClient(baseUrl, token)` | `GitLabClient` | Create a client instance |
+| `.testConnection()` | `Promise<ITestConnectionResult>` | Verify token and connectivity |
+| `.getGroups(opts?)` | `Promise<GitLabGroup[]>` | List all accessible groups (auto-paginated) |
+| `.getGroup(fullPath)` | `Promise<GitLabGroup>` | Get a single group by full path |
+| `.createGroup(name, path, parentId?)` | `Promise<GitLabGroup>` | Create a new group |
+| `.getProjects(opts?)` | `Promise<GitLabProject[]>` | List your projects (auto-paginated) |
+| `.getProject(idOrPath)` | `Promise<GitLabProject>` | Get a single project by ID or path |
+| `.createProject(name, opts?)` | `Promise<GitLabProject>` | Create a new project |
+
+### `GitLabGroup`
+
+| Method | Returns | Description |
+|---|---|---|
+| `.getProjects(opts?)` | `Promise<GitLabProject[]>` | List projects in the group |
+| `.getDescendantGroups(opts?)` | `Promise<GitLabGroup[]>` | List descendant sub-groups |
+| `.getVariables()` | `Promise<GitLabVariable[]>` | List CI/CD variables |
+| `.createVariable(key, value, opts?)` | `Promise<GitLabVariable>` | Create a CI/CD variable |
+| `.updateVariable(key, value, opts?)` | `Promise<GitLabVariable>` | Update a CI/CD variable |
+| `.deleteVariable(key)` | `Promise<void>` | Delete a CI/CD variable |
+| `.update(data)` | `Promise<void>` | Update group properties |
+| `.setAvatar(imageData, filename)` | `Promise<void>` | Upload avatar image |
+| `.deleteAvatar()` | `Promise<void>` | Remove avatar |
+| `.transfer(parentGroupId)` | `Promise<void>` | Transfer to another parent group |
+| `.delete()` | `Promise<void>` | Delete the group |
+| `.toJSON()` | `IGitLabGroup` | Serialize to raw interface |
+
+### `GitLabProject`
+
+| Method | Returns | Description |
+|---|---|---|
+| `.getBranches(opts?)` | `Promise<GitLabBranch[]>` | List repository branches |
+| `.getTags(opts?)` | `Promise<GitLabTag[]>` | List repository tags |
+| `.getProtectedBranches()` | `Promise<GitLabProtectedBranch[]>` | List protected branches |
+| `.unprotectBranch(name)` | `Promise<void>` | Remove branch protection |
+| `.getVariables()` | `Promise<GitLabVariable[]>` | List CI/CD variables |
+| `.createVariable(key, value, opts?)` | `Promise<GitLabVariable>` | Create a CI/CD variable |
+| `.updateVariable(key, value, opts?)` | `Promise<GitLabVariable>` | Update a CI/CD variable |
+| `.deleteVariable(key)` | `Promise<void>` | Delete a CI/CD variable |
+| `.getPipelines(opts?)` | `Promise<GitLabPipeline[]>` | List pipelines (with rich filtering) |
+| `.triggerPipeline(ref, variables?)` | `Promise<GitLabPipeline>` | Trigger a new pipeline |
+| `.update(data)` | `Promise<void>` | Update project properties |
+| `.setAvatar(imageData, filename)` | `Promise<void>` | Upload avatar image |
+| `.deleteAvatar()` | `Promise<void>` | Remove avatar |
+| `.transfer(namespaceId)` | `Promise<void>` | Transfer to another namespace |
+| `.delete()` | `Promise<void>` | Delete the project |
+| `.toJSON()` | `IGitLabProject` | Serialize to raw interface |
+
+### `GitLabPipeline`
+
+| Method | Returns | Description |
+|---|---|---|
+| `.getJobs(opts?)` | `Promise<GitLabJob[]>` | List jobs (with scope filtering) |
+| `.getVariables()` | `Promise<GitLabPipelineVariable[]>` | Get pipeline variables |
+| `.getTestReport()` | `Promise<GitLabTestReport>` | Get the test report |
+| `.retry()` | `Promise<GitLabPipeline>` | Retry failed jobs |
+| `.cancel()` | `Promise<GitLabPipeline>` | Cancel the pipeline |
+| `.delete()` | `Promise<void>` | Delete the pipeline |
+| `.toJSON()` | `IGitLabPipeline` | Serialize to raw interface |
+
+### `GitLabJob`
+
+| Method | Returns | Description |
+|---|---|---|
+| `.getLog()` | `Promise<string>` | Get raw job trace/log |
+| `.retry()` | `Promise<GitLabJob>` | Retry the job |
+| `.cancel()` | `Promise<GitLabJob>` | Cancel the job |
+| `.play()` | `Promise<GitLabJob>` | Trigger a manual job |
+| `.erase()` | `Promise<void>` | Erase artifacts and trace |
+| `.toJSON()` | `IGitLabJob` | Serialize to raw interface |
+
+### Value Classes
+
+| Class | Key Properties |
+|---|---|
+| `GitLabBranch` | `name`, `commitSha` |
+| `GitLabTag` | `name`, `commitSha` |
+| `GitLabProtectedBranch` | `id`, `name`, `allowForcePush` |
+| `GitLabVariable` | `key`, `value`, `variableType`, `protected`, `masked`, `environmentScope` |
+| `GitLabPipelineVariable` | `key`, `value`, `variableType` |
+| `GitLabTestReport` | `totalTime`, `totalCount`, `successCount`, `failedCount`, `skippedCount`, `errorCount`, `testSuites` |
+| `GitLabTestSuite` | `name`, `totalTime`, `totalCount`, `successCount`, `failedCount`, `skippedCount`, `errorCount`, `testCases` |
+| `GitLabTestCase` | `status`, `name`, `classname`, `executionTime`, `systemOutput`, `stackTrace` |
+
+---
+
+## TypeScript Interfaces 🏗️
+
+All raw GitLab API shapes are exported as TypeScript interfaces so you can use them in your own type definitions.
 
 ### `IListOptions`
 
-Pagination and search options used by `getProjects`, `getGroups`, and `getPipelines`.
-
 ```typescript
 interface IListOptions {
   search?: string;   // Filter results by keyword
   page?: number;     // Page number (default: 1)
-  perPage?: number;  // Items per page (default: 50 for projects/groups, 30 for pipelines)
+  perPage?: number;  // Items per page (default: 50)
 }
 ```
 
-### `IVariableOptions`
+### `IPipelineListOptions`
 
-Options when creating or updating CI/CD variables.
+Extends `IListOptions` with pipeline-specific filters:
 
 ```typescript
-interface IVariableOptions {
-  protected?: boolean;         // Only expose to protected branches/tags (default: false)
-  masked?: boolean;            // Mask the value in job logs (default: false)
-  environment_scope?: string;  // Environment scope (default: '*' for all environments)
+interface IPipelineListOptions extends IListOptions {
+  status?: string;          // Filter by pipeline status
+  ref?: string;             // Filter by branch/tag ref
+  source?: string;          // Filter by trigger source (push, web, schedule, api, ...)
+  scope?: string;           // Filter by scope (running, pending, finished, branches, tags)
+  username?: string;        // Filter by the triggering user
+  updatedAfter?: string;    // ISO 8601 date — only pipelines updated after this
+  updatedBefore?: string;   // ISO 8601 date — only pipelines updated before this
+  orderBy?: string;         // Order by field (id, status, ref, updated_at, user_id)
+  sort?: string;            // Sort direction (asc, desc)
 }
 ```
 
-### `ITestConnectionResult`
+### `IJobListOptions`
 
 ```typescript
-interface ITestConnectionResult {
-  ok: boolean;
-  error?: string;  // Present when ok is false
+interface IJobListOptions extends IListOptions {
+  scope?: string[];  // Filter by job scope(s): created, pending, running, failed, success, ...
 }
 ```
 
-### `IGitLabProject`
+### `IVariableOptions`
 
 ```typescript
-interface IGitLabProject {
-  id: number;
-  name: string;
-  path_with_namespace: string;
-  description: string;
-  default_branch: string;
-  web_url: string;
-  visibility: string;
-  topics: string[];
-  last_activity_at: string;
+interface IVariableOptions {
+  protected?: boolean;         // Only expose to protected branches/tags
+  masked?: boolean;            // Mask the value in job logs
+  environment_scope?: string;  // Environment scope (default: '*')
 }
 ```
 
-### `IGitLabGroup`
+### `ITestConnectionResult`
 
 ```typescript
-interface IGitLabGroup {
-  id: number;
-  name: string;
-  full_path: string;
-  description: string;
-  web_url: string;
-  visibility: string;
+interface ITestConnectionResult {
+  ok: boolean;
+  error?: string;  // Present when ok is false
 }
 ```
 
-### `IGitLabVariable`
+All raw data interfaces (`IGitLabProject`, `IGitLabGroup`, `IGitLabPipeline`, `IGitLabJob`, `IGitLabVariable`, `IGitLabBranch`, `IGitLabTag`, `IGitLabProtectedBranch`, `IGitLabPipelineVariable`, `IGitLabTestReport`, `IGitLabTestSuite`, `IGitLabTestCase`, `IGitLabUser`) are also exported for advanced use cases.
 
-```typescript
-interface IGitLabVariable {
-  key: string;
-  value: string;
-  variable_type: string;
-  protected: boolean;
-  masked: boolean;
-  environment_scope: string;
-}
-```
+---
 
-### `IGitLabPipeline`
+## License and Legal Information
 
-```typescript
-interface IGitLabPipeline {
-  id: number;
-  project_id: number;
-  status: string;
-  ref: string;
-  sha: string;
-  web_url: string;
-  duration: number;
-  created_at: string;
-  source: string;
-}
-```
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
-### `IGitLabJob`
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
-```typescript
-interface IGitLabJob {
-  id: number;
-  name: string;
-  stage: string;
-  status: string;
-  duration: number;
-}
-```
+### Trademarks
 
-### `IGitLabUser`
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
 
-Returned internally by `testConnection` to verify credentials.
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
-```typescript
-interface IGitLabUser {
-  id: number;
-  username: string;
-  name: string;
-  email: string;
-  avatar_url: string;
-  web_url: string;
-  state: string;
-}
-```
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-## License
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-MIT
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.