@apiclient.xyz/gitlab 2.0.2 → 2.0.3

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@apiclient.xyz/gitlab',
-    version: '2.0.2',
+    version: '2.0.3',
     description: 'A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx1QkFBdUI7SUFDN0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLG9IQUFvSDtDQUNsSSxDQUFBIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apiclient.xyz/gitlab",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "private": false,
   "description": "A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.",
   "main": "dist_ts/index.js",

package/readme.md

@@ -4,25 +4,291 @@ A TypeScript client for the GitLab API, providing easy access to projects, group
 
 ## Install
 
-```sh
+```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.com', 'your-private-token');
+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
 
-// Test connection
+```typescript
 const result = await client.testConnection();
 
-// List projects
+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();
 
-// Manage CI/CD variables
-await client.createProjectVariable(123, 'SECRET_KEY', 'secret-value');
+// 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

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@apiclient.xyz/gitlab',
-  version: '2.0.2',
+  version: '2.0.3',
   description: 'A TypeScript client for the GitLab API, providing easy access to projects, groups, CI/CD variables, and pipelines.'
 }