Projects

/**
 * Projects resource class for project management
 */
class Projects<C extends boolean = false> {
  /**
   * List all projects with filtering and pagination
   * @param options - Query options for filtering projects
   * @returns Array of projects
   */
  all<E extends boolean = false, P extends PaginationTypes = 'keyset'>(
    options?: AllProjectsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProjectSchema[], C, E, P>>;

  /**
   * Get details of a single project
   * @param projectId - Project ID or URL-encoded path
   * @param options - Additional options (statistics, license, customAttributes)
   * @returns Project details
   */
  show<E extends boolean = false>(
    projectId: string | number,
    options?: ShowProjectOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

  /**
   * Create a new project
   * @param options - Project configuration including name, path, and settings
   * @returns Created project
   */
  create<E extends boolean = false>(
    options: CreateProjectOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

  /**
   * Update an existing project
   * @param projectId - Project ID or URL-encoded path
   * @param options - Fields to update
   * @returns Updated project
   */
  edit<E extends boolean = false>(
    projectId: string | number,
    options?: EditProjectOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

  /**
   * Delete a project
   * @param projectId - Project ID or URL-encoded path
   * @param options - Additional deletion options (permanentlyRemove, fullPath)
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    options?: { permanentlyRemove?: boolean; fullPath?: string } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

/**
 * Options for filtering and querying projects
 */
type AllProjectsOptions = {
  /** Filter by user ID */
  userId?: string;
  /** Include archived projects */
  archived?: boolean;
  /** Return projects with IDs greater than specified */
  idAfter?: number;
  /** Return projects with IDs less than specified */
  idBefore?: number;
  /** Show imported projects */
  imported?: boolean;
  /** Include hidden projects */
  includeHidden?: boolean;
  /** Include projects pending deletion */
  includePendingDelete?: boolean;
  /** Filter by last activity date (after) */
  lastActivityAfter?: string;
  /** Filter by last activity date (before) */
  lastActivityBefore?: string;
  /** Limit to projects user is a member of */
  membership?: boolean;
  /** Minimum access level required */
  minAccessLevel?: Exclude<AccessLevel, AccessLevel.ADMIN>;
  /** Order results by field */
  orderBy?: 'id' | 'name' | 'path' | 'created_at' | 'updated_at' | 'last_activity_at'
    | 'similarity' | 'repository_size' | 'storage_size' | 'packages_size' | 'wiki_size';
  /** Limit to owned projects */
  owned?: boolean;
  /** Filter by repository checksum failure */
  repositoryChecksumFailed?: boolean;
  /** Filter by repository storage */
  repositoryStorage?: string;
  /** Search in namespace names */
  searchNamespaces?: boolean;
  /** Search term */
  search?: string;
  /** Return simple project information */
  simple?: boolean;
  /** Sort direction */
  sort?: 'asc' | 'desc';
  /** Limit to starred projects */
  starred?: boolean;
  /** Include statistics */
  statistics?: boolean;
  /** Filter by topic */
  topic?: string;
  /** Filter by topic ID */
  topicId?: number;
  /** Filter by visibility level */
  visibility?: 'public' | 'internal' | 'private';
  /** Filter by wiki checksum failure */
  wikiChecksumFailed?: boolean;
  /** Include custom attributes */
  withCustomAttributes?: boolean;
  /** Include only projects with issues enabled */
  withIssuesEnabled?: boolean;
  /** Include only projects with merge requests enabled */
  withMergeRequestsEnabled?: boolean;
  /** Filter by programming language */
  withProgrammingLanguage?: string;
  /** Filter by update date (before) */
  updatedBefore?: string;
  /** Filter by update date (after) */
  updatedAfter?: string;
  /** Filter by marked for deletion date */
  markedForDeletionOn?: string;
  /** Show only active projects */
  active?: boolean;
};

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({ token: process.env.GITLAB_TOKEN });

// List all projects user is a member of
const myProjects = await api.Projects.all({
  membership: true,
  orderBy: 'last_activity_at',
  sort: 'desc'
});

// Get project with statistics
const project = await api.Projects.show(123, {
  statistics: true
});

// Search for projects
const results = await api.Projects.all({
  search: 'frontend',
  withIssuesEnabled: true
});

// List starred projects
const starred = await api.Projects.all({
  starred: true
});

/**
 * Options for creating a new project
 */
type CreateProjectOptions = {
  /** User ID for admin project creation */
  userId?: number;
  /** Project avatar image */
  avatar?: { content: Blob; filename: string };
  /** Allow merge on skipped pipeline */
  allowMergeOnSkippedPipeline?: boolean;
  /** Only allow merge if all status checks passed */
  onlyAllowMergeIfAllStatusChecksPassed?: boolean;
  /** Analytics access level */
  analyticsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Approvals required before merge */
  approvalsBeforeMerge?: number;
  /** Auto cancel pending pipelines */
  autoCancelPendingPipelines?: string;
  /** Auto DevOps deployment strategy */
  autoDevopsDeployStrategy?: 'continuous' | 'manual' | 'timed_incremental';
  /** Enable Auto DevOps */
  autoDevopsEnabled?: boolean;
  /** Auto-close referenced issues on merge */
  autocloseReferencedIssues?: boolean;
  /** Build git strategy */
  buildGitStrategy?: string;
  /** Build timeout in seconds */
  buildTimeout?: number;
  /** Builds/jobs access level */
  buildsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Custom CI config path */
  ciConfigPath?: string;
  /** CI pipeline deletion delay in seconds */
  ciDeletePipelinesInSeconds?: number;
  /** Container registry expiration policy */
  containerExpirationPolicyAttributes?: Record<string, string>;
  /** Container registry access level */
  containerRegistryAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Default branch name */
  defaultBranch?: string;
  /** Project description */
  description?: string;
  /** Disable email notifications */
  emailsDisabled?: boolean;
  /** External authorization classification label */
  externalAuthorizationClassificationLabel?: string;
  /** Forking access level */
  forkingAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Project template group ID */
  groupWithProjectTemplatesId?: number;
  /** Import from URL */
  importUrl?: string;
  /** Initialize with README */
  initializeWithReadme?: boolean;
  /** Issues access level */
  issuesAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Enable Git LFS */
  lfsEnabled?: boolean;
  /** Merge method */
  mergeMethod?: string;
  /** Enable merge pipelines */
  mergePipelinesEnabled?: boolean;
  /** Merge requests access level */
  mergeRequestsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Enable merge trains */
  mergeTrainsEnabled?: boolean;
  /** Mirror trigger builds */
  mirrorTriggerBuilds?: boolean;
  /** Enable repository mirroring */
  mirror?: boolean;
  /** Namespace ID */
  namespaceId?: number;
  /** Only allow merge if all discussions resolved */
  onlyAllowMergeIfAllDiscussionsAreResolved?: boolean;
  /** Only allow merge if pipeline succeeds */
  onlyAllowMergeIfPipelineSucceeds?: boolean;
  /** Enable package registry */
  packagesEnabled?: boolean;
  /** Pages access level */
  pagesAccessLevel?: 'disabled' | 'enabled' | 'private' | 'public';
  /** Print merge request link */
  printingMergeRequestLinkEnabled?: boolean;
  /** Make jobs public */
  publicBuilds?: boolean;
  /** Releases access level */
  releasesAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Environments access level */
  environmentsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Feature flags access level */
  featureFlagsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Infrastructure access level */
  infrastructureAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Monitor access level */
  monitorAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Remove source branch after merge */
  removeSourceBranchAfterMerge?: boolean;
  /** Repository access level */
  repositoryAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Repository storage location */
  repositoryStorage?: string;
  /** Allow access requests */
  requestAccessEnabled?: boolean;
  /** Requirements access level */
  requirementsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Resolve outdated diff discussions */
  resolveOutdatedDiffDiscussions?: boolean;
  /** Security and compliance access level */
  securityAndComplianceAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Enable shared runners */
  sharedRunnersEnabled?: boolean;
  /** Enable group runners */
  groupRunnersEnabled?: boolean;
  /** Snippets access level */
  snippetsAccessLevel?: 'disabled' | 'enabled' | 'private';
  /** Squash option for merge requests */
  squashOption?: 'never' | 'always' | 'default_on' | 'default_off';
  /** Project template name */
  templateName?: string;
  /** Template project ID */
  templateProjectId?: number;
  /** Project topics/tags */
  topics?: string[];
  /** Use custom template */
  useCustomTemplate?: boolean;
  /** Project visibility */
  visibility?: 'public' | 'internal' | 'private';
  /** Wiki access level */
  wikiAccessLevel?: 'disabled' | 'enabled' | 'private';
};

// Create a new project
const newProject = await api.Projects.create({
  name: 'My New Project',
  path: 'my-new-project',
  description: 'A sample project',
  visibility: 'private',
  initializeWithReadme: true,
  issuesAccessLevel: 'enabled',
  mergeRequestsAccessLevel: 'enabled'
});

// Create project in specific namespace
const groupProject = await api.Projects.create({
  name: 'Team Project',
  namespaceId: 456,
  visibility: 'internal'
});

// Update project settings
const updated = await api.Projects.edit(123, {
  description: 'Updated description',
  visibility: 'public',
  issuesAccessLevel: 'enabled',
  onlyAllowMergeIfPipelineSucceeds: true
});

/**
 * Fork a project
 * @param projectId - Project to fork
 * @param options - Fork configuration
 * @returns Forked project
 */
fork<E extends boolean = false>(
  projectId: string | number,
  options?: ForkProjectOptions & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

/**
 * List all forks of a project
 * @param projectId - Project ID
 * @param options - Query options
 * @returns Array of forked projects
 */
allForks<E extends boolean = false>(
  projectId: string | number,
  options?: AllForksOptions & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema[], C, E, void>>;

/**
 * Create a fork relationship between projects
 * @param projectId - Forked project ID
 * @param forkedFromId - Source project ID
 */
createForkRelationship<E extends boolean = false>(
  projectId: string | number,
  forkedFromId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * Remove fork relationship
 * @param projectId - Project ID
 */
removeForkRelationship<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

// Fork a project
const forked = await api.Projects.fork(123, {
  name: 'My Fork',
  namespaceId: 789,
  path: 'my-fork'
});

// List all forks
const forks = await api.Projects.allForks(123, {
  orderBy: 'created_at',
  sort: 'desc'
});

// Create fork relationship
await api.Projects.createForkRelationship(456, 123);

// Remove fork relationship
await api.Projects.removeForkRelationship(456);

/**
 * Share project with a group
 * @param projectId - Project ID
 * @param groupId - Group ID to share with
 * @param groupAccess - Access level for the group
 * @param options - Additional options (expiration date)
 */
share<E extends boolean = false>(
  projectId: string | number,
  groupId: string | number,
  groupAccess: number,
  options?: { expiresAt?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * Remove project share with a group
 * @param projectId - Project ID
 * @param groupId - Group ID to unshare from
 */
unshare<E extends boolean = false>(
  projectId: string | number,
  groupId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * List groups a project is shared with
 * @param projectId - Project ID
 * @returns Array of groups
 */
allGroups<E extends boolean = false>(
  projectId: string | number,
  options?: GroupQueryOptions & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleGroupSchema[], C, E, void>>;

/**
 * List groups invited to the project
 * @param projectId - Project ID
 * @returns Array of invited groups
 */
allInvitedGroups<E extends boolean = false>(
  projectId: string | number,
  options?: { search?: string; sharedMinAccessLevel?: number; relation?: 'direct' | 'inherited' }
    & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleGroupSchema[], C, E, void>>;

import { AccessLevel } from '@gitbeaker/rest';

// Share project with a group (Developer access)
await api.Projects.share(123, 456, AccessLevel.DEVELOPER, {
  expiresAt: '2024-12-31'
});

// List groups project is shared with
const sharedGroups = await api.Projects.allGroups(123, {
  withShared: true
});

// Remove share
await api.Projects.unshare(123, 456);

/**
 * List users of a project
 * @param projectId - Project ID
 * @param options - Query options
 * @returns Array of users
 */
allUsers<E extends boolean = false>(
  projectId: string | number,
  options?: { search?: string; skipUsers?: number[] } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleUserSchema[], C, E, void>>;

/**
 * Import project members from another project
 * @param projectId - Target project ID
 * @param sourceProjectId - Source project ID
 */
importProjectMembers<E extends boolean = false>(
  projectId: string | number,
  sourceProjectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * Star a project
 * @param projectId - Project ID
 * @returns Updated project
 */
star<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

/**
 * Unstar a project
 * @param projectId - Project ID
 * @returns Updated project
 */
unstar<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

/**
 * List users who starred a project
 * @param projectId - Project ID
 * @param options - Query options
 * @returns Array of starrers with timestamps
 */
allStarrers<E extends boolean = false>(
  projectId: string | number,
  options?: { search?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectStarrerSchema[], C, E, void>>;

// Star a project
await api.Projects.star(123);

// Unstar a project
await api.Projects.unstar(123);

// List starrers
const starrers = await api.Projects.allStarrers(123);
console.log(starrers[0].starred_since);

/**
 * Archive a project
 * @param projectId - Project ID
 * @returns Archived project
 */
archive<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

/**
 * Unarchive a project
 * @param projectId - Project ID
 * @returns Unarchived project
 */
unarchive<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

/**
 * Restore a deleted project (Premium/Ultimate)
 * @param projectId - Project ID
 */
restore<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

// Archive a project
const archived = await api.Projects.archive(123);

// Unarchive a project
const active = await api.Projects.unarchive(123);

// Restore deleted project
await api.Projects.restore(123);

/**
 * Transfer project to different namespace
 * @param projectId - Project ID
 * @param namespaceId - Target namespace ID
 * @returns Updated project
 */
transfer<E extends boolean = false>(
  projectId: string | number,
  namespaceId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema, C, E, void>>;

/**
 * List groups project can be transferred to
 * @param projectId - Project ID
 * @returns Array of transfer location groups
 */
allTransferLocations<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  projectId: string | number,
  options?: { search?: string } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleGroupSchema[], C, E, P>>;

/**
 * Upload file for reference in issues, MRs, or comments
 * @param projectId - Project ID
 * @param file - File content and filename
 * @returns File upload information with markdown link
 */
uploadForReference<E extends boolean = false>(
  projectId: string | number,
  file: { content: Blob; filename: string },
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectFileUploadSchema, C, E, void>>;

/**
 * Upload project avatar
 * @param projectId - Project ID
 * @param avatar - Avatar image
 * @returns Avatar URL
 */
uploadAvatar<E extends boolean = false>(
  projectId: string | number,
  avatar: { content: Blob; filename: string },
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<{ avatar_url: string }, C, E, void>>;

/**
 * Remove project avatar
 * @param projectId - Project ID
 */
removeAvatar<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

// Upload image for use in issues/MRs
const upload = await api.Projects.uploadForReference(123, {
  content: imageBlob,
  filename: 'screenshot.png'
});
console.log(upload.markdown); // ![screenshot](url)

// Upload project avatar
const avatarResult = await api.Projects.uploadAvatar(123, {
  content: avatarBlob,
  filename: 'avatar.png'
});

// Remove avatar
await api.Projects.removeAvatar(123);

/**
 * Search projects by name
 * @param projectName - Search term
 * @param options - Additional query options
 * @returns Matching projects
 */
search<E extends boolean = false>(
  projectName: string,
  options?: { sort?: 'asc' | 'desc'; orderBy?: 'id' | 'name' | 'created_at' | 'last_activity_at' }
    & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema[], C, E, void>>;

/**
 * Show project languages (programming languages used)
 * @param projectId - Project ID
 * @returns Language percentages
 */
showLanguages<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<{ [name: string]: number }, C, E, void>>;

/**
 * Download project snapshot as archive
 * @param projectId - Project ID
 * @param options - Include wiki option
 * @returns Archive blob
 */
downloadSnapshot<E extends boolean = false>(
  projectId: string | number,
  options?: { wiki?: boolean } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<Blob, void, E, void>>;

/**
 * Trigger housekeeping tasks (git maintenance)
 * @param projectId - Project ID
 * @param options - Task type option
 */
housekeeping<E extends boolean = false>(
  projectId: string | number,
  options?: { task?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * List storage paths for project
 * @param projectId - Project ID
 * @returns Storage path information
 */
allStoragePaths<E extends boolean = false>(
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectStoragePath[], C, E, void>>;

// Search for projects
const results = await api.Projects.search('backend', {
  orderBy: 'last_activity_at',
  sort: 'desc'
});

// Get language breakdown
const languages = await api.Projects.showLanguages(123);
console.log(languages); // { "TypeScript": 75.5, "JavaScript": 24.5 }

// Download project snapshot
const snapshot = await api.Projects.downloadSnapshot(123, {
  wiki: true
});

// Trigger housekeeping
await api.Projects.housekeeping(123);