# @apiclient.xyz/gitlab

A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.

## Install

```bash
npm install @apiclient.xyz/gitlab
```

## Usage

All examples below use ESM imports and async/await.

### Creating a Client

```typescript
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.

### Testing the Connection

```typescript
const result = await client.testConnection();

if (result.ok) {
  console.log('Connected successfully.');
} else {
  console.error('Connection failed:', result.error);
}
```

### Listing Projects

Retrieve projects you are a member of, ordered by most recently updated.

```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,
});

for (const project of filtered) {
  console.log(`${project.id} - ${project.path_with_namespace}`);
}
```

### Listing Groups

```typescript
const groups = await client.getGroups();

// Search groups by name
const matchingGroups = await client.getGroups({ search: 'platform' });

for (const group of matchingGroups) {
  console.log(`${group.id} - ${group.full_path}`);
}
```

### Managing Project Variables

```typescript
const projectId = 42;

// List all variables
const vars = await client.getProjectVariables(projectId);

// Create a variable
await client.createProjectVariable(projectId, 'DATABASE_URL', 'postgres://...', {
  protected: true,
  masked: true,
  environment_scope: 'production',
});

// Update a variable
await client.updateProjectVariable(projectId, 'DATABASE_URL', 'postgres://new-host/...', {
  protected: true,
});

// Delete a variable
await client.deleteProjectVariable(projectId, 'DATABASE_URL');
```

### Managing Group Variables

The group variable API mirrors the project variable API.

```typescript
const groupId = 7;

// List all variables
const groupVars = await client.getGroupVariables(groupId);

// Create a variable
await client.createGroupVariable(groupId, 'NPM_TOKEN', 'tok-xxx', {
  protected: false,
  masked: true,
  environment_scope: '*',
});

// Update a variable
await client.updateGroupVariable(groupId, 'NPM_TOKEN', 'tok-yyy', {
  masked: true,
});

// Delete a variable
await client.deleteGroupVariable(groupId, 'NPM_TOKEN');
```

### Working with Pipelines

```typescript
const projectId = 42;

// List recent pipelines
const pipelines = await client.getPipelines(projectId, { page: 1, perPage: 10 });

for (const pipeline of pipelines) {
  console.log(`Pipeline #${pipeline.id} [${pipeline.status}] on ${pipeline.ref}`);
}

// Get jobs for a specific pipeline
const jobs = await client.getPipelineJobs(projectId, pipelines[0].id);
for (const job of jobs) {
  console.log(`  Job "${job.name}" (${job.stage}): ${job.status}`);
}

// Read the raw log output of a job
const log = await client.getJobLog(projectId, jobs[0].id);
console.log(log);

// Retry a failed pipeline
await client.retryPipeline(projectId, pipelines[0].id);

// Cancel a running pipeline
await client.cancelPipeline(projectId, pipelines[0].id);
```

## 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

### `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)
}
```

### `IVariableOptions`

Options when creating or updating CI/CD variables.

```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)
}
```

### `ITestConnectionResult`

```typescript
interface ITestConnectionResult {
  ok: boolean;
  error?: string;  // Present when ok is false
}
```

### `IGitLabProject`

```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;
}
```

### `IGitLabGroup`

```typescript
interface IGitLabGroup {
  id: number;
  name: string;
  full_path: string;
  description: string;
  web_url: string;
  visibility: string;
}
```

### `IGitLabVariable`

```typescript
interface IGitLabVariable {
  key: string;
  value: string;
  variable_type: string;
  protected: boolean;
  masked: boolean;
  environment_scope: string;
}
```

### `IGitLabPipeline`

```typescript
interface IGitLabPipeline {
  id: number;
  project_id: number;
  status: string;
  ref: string;
  sha: string;
  web_url: string;
  duration: number;
  created_at: string;
  source: string;
}
```

### `IGitLabJob`

```typescript
interface IGitLabJob {
  id: number;
  name: string;
  stage: string;
  status: string;
  duration: number;
}
```

### `IGitLabUser`

Returned internally by `testConnection` to verify credentials.

```typescript
interface IGitLabUser {
  id: number;
  username: string;
  name: string;
  email: string;
  avatar_url: string;
  web_url: string;
  state: string;
}
```

## License

MIT