@mastra/factory 0.16.0-alpha.9 → 0.16.1-alpha.0

package/dist/integrations/gitlab/integration.js

@@ -0,0 +1,705 @@
+import { GitLabApiClient, GitLabApiError } from "./api.js";
+import { IssueReconcileWorker } from "../issue-reconcile-worker.js";
+import { buildGitLabAgentTools } from "./agent-tools.js";
+import { resolveGitLabRules } from "./default-rules.js";
+import { attachGitLabRules } from "./rules.js";
+import { attachGitLabReconciler } from "./reconciler.js";
+import { gitlabReconciliationEnabled, gitlabReconciliationInterval } from "./reconciliation-config.js";
+import { buildGitLabRoutes } from "./routes.js";
+import { createGitLabSubscriptionTools, parseCreatedMergeRequest, subscribeCurrentSessionToMergeRequest } from "./session-subscriptions.js";
+import { buildGitLabVersionControl } from "./version-control.js";
+//#region src/integrations/gitlab/integration.ts
+const DIRECT_CONNECTION_ID = "direct";
+const GITLAB_CONNECTION_TOKEN_PREFIX = "gitlab-connection:";
+const GITLAB_SOURCE_PREFIX = "gitlab-project:";
+const GITLAB_ISSUE_PREFIX = "gitlab-issue:";
+const GITLAB_MERGE_REQUEST_PREFIX = "gitlab-pr:";
+const GITLAB_TRUSTED_ACCESS_LEVEL = 30;
+const MAX_NOTES_PAGES = 20;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var GitLabIntegrationBase = class {
+	id = "gitlab";
+	#projects;
+	#sourceControl;
+	#integrationStorage;
+	#auth;
+	#orgIdByResourceId = /* @__PURE__ */ new Map();
+	rules;
+	constructor(rules) {
+		this.rules = resolveGitLabRules(rules);
+	}
+	intake = {
+		resolveIntakeDispatch: (input) => this.#resolveIntakeDispatch(input),
+		listSources: () => this.#listSources(),
+		listItems: (input) => this.#listItems(input),
+		listIssues: (input) => this.#listIssues(input),
+		getIssue: (input) => this.#getIssue(input),
+		createComment: (input) => this.#createComment(input),
+		updateIssue: (input) => this.#updateIssue(input)
+	};
+	versionControl = buildGitLabVersionControl({
+		contextForConnection: (connection) => this.#versionControlContext(connection),
+		contextForStoredInstallation: (connection, host) => this.#versionControlContextForInstallation(connection, host)
+	});
+	initialize({ storage, projects, auth, sourceControl }) {
+		this.#projects = projects;
+		this.#auth = auth;
+		this.#sourceControl = sourceControl;
+		this.#integrationStorage = storage;
+	}
+	/** Generic integration persistence (merge-request subscriptions). */
+	get integrationStorage() {
+		if (!this.#integrationStorage) throw new Error(`${this.constructor.name} is not initialized — the factory binds storage during prepare().`);
+		return this.#integrationStorage;
+	}
+	/** Source-control rows for this integration; absent when the host runs without them. */
+	get sourceControlStorage() {
+		return this.#sourceControl;
+	}
+	get authEnabled() {
+		return this.#auth?.enabled() ?? false;
+	}
+	get projects() {
+		if (!this.#projects) throw new Error(`${this.constructor.name} is not initialized — the factory binds storage during prepare().`);
+		return this.#projects;
+	}
+	async resolveOrgId(resourceId) {
+		const cached = this.#orgIdByResourceId.get(resourceId);
+		if (cached !== void 0) return cached;
+		if (!UUID_PATTERN.test(resourceId)) {
+			this.#orgIdByResourceId.set(resourceId, null);
+			return null;
+		}
+		try {
+			await this.projects.ensureReady();
+			const orgId = (await this.projects.getById({ id: resourceId }))?.orgId ?? null;
+			this.#orgIdByResourceId.set(resourceId, orgId);
+			return orgId;
+		} catch {
+			return null;
+		}
+	}
+	clearCaches() {
+		this.#orgIdByResourceId.clear();
+	}
+	/** Resolve only a GitLab repository linked to this Factory in this organization. */
+	async getLinkedRepository(input) {
+		if (!this.#sourceControl) return null;
+		const connections = await this.#sourceControl.connections.list({
+			orgId: input.orgId,
+			factoryProjectId: input.factoryProjectId
+		});
+		for (const connection of connections) {
+			if (connection.integrationId !== "gitlab") continue;
+			const link = (await this.#sourceControl.projectRepositories.list({
+				orgId: input.orgId,
+				connectionId: connection.id
+			})).find((candidate) => candidate.id === input.projectRepositoryId);
+			if (!link) continue;
+			const repository = await this.#sourceControl.repositories.get({
+				orgId: input.orgId,
+				id: link.repositoryId
+			});
+			const installation = await this.#sourceControl.installations.get({
+				orgId: input.orgId,
+				id: connection.installationId
+			});
+			if (!repository || !installation) return null;
+			const host = installation.providerMetadata.host;
+			if (typeof host !== "string" || !host) return null;
+			return {
+				repository,
+				host: normalizeGitLabHost(host)
+			};
+		}
+		return null;
+	}
+	async getProjectMemberAccessLevel(connectionId, projectId, username) {
+		const normalized = username.trim().toLowerCase();
+		if (!normalized) return void 0;
+		return (await (await this.contextById(connectionId)).api.listProjectMembers(projectId, { query: username })).find((candidate) => candidate.username.toLowerCase() === normalized && candidate.state !== "blocked")?.access_level;
+	}
+	async getWorkItemAuthorUsername(connectionId, projectId, kind, iid) {
+		const api = (await this.contextById(connectionId)).api;
+		return (kind === "issue" ? await api.getIssue(projectId, iid) : await api.getMergeRequest(projectId, iid)).author?.username;
+	}
+	async isProjectMemberTrustedForSource(sourceId, username) {
+		const reference = decodeSourceId(sourceId);
+		if (!reference) throw new GitLabApiError("GitLab source identity is invalid.", 400);
+		const { context, source } = await this.#resolveSourceReference(reference);
+		return (await this.getProjectMemberAccessLevel(context.id, source.projectId, username) ?? 0) >= 30;
+	}
+	async getIssueForFactoryProject(input) {
+		if (!this.#sourceControl) throw new GitLabApiError("GitLab source control is unavailable.", 503);
+		const reference = decodeIssueReference(input.issueId);
+		const locator = parseIssueLocator(input.issueId);
+		if (!reference && !locator) throw new GitLabApiError("GitLab issue must include a project and issue IID.", 400);
+		const normalizePath = (value) => value.replace(/^\/+|\/+$/g, "").toLowerCase();
+		const matches = [];
+		const connections = await this.#sourceControl.connections.list({
+			orgId: input.orgId,
+			factoryProjectId: input.factoryProjectId
+		});
+		for (const connection of connections) {
+			const installation = await this.#sourceControl.installations.get({
+				orgId: input.orgId,
+				id: connection.installationId
+			});
+			if (!installation) continue;
+			for (const projectRepository of await this.#sourceControl.projectRepositories.list({
+				orgId: input.orgId,
+				connectionId: connection.id
+			})) {
+				const repository = await this.#sourceControl.repositories.get({
+					orgId: input.orgId,
+					id: projectRepository.repositoryId
+				});
+				if (!repository) continue;
+				if (reference?.projectId && repository.externalId !== reference.projectId) continue;
+				if (reference?.projectPath && normalizePath(repository.slug) !== normalizePath(reference.projectPath)) continue;
+				if (locator?.projectPath && normalizePath(repository.slug) !== normalizePath(locator.projectPath)) continue;
+				if (reference?.connectionId && installation.externalId !== reference.connectionId) continue;
+				const installationHost = typeof installation.providerMetadata.host === "string" ? normalizeGitLabHost(installation.providerMetadata.host) : null;
+				if (reference?.host && installationHost !== normalizeGitLabHost(reference.host)) continue;
+				if (locator?.host && installationHost !== normalizeGitLabHost(locator.host)) continue;
+				matches.push({
+					connectionId: installation.externalId,
+					projectId: repository.externalId,
+					projectPath: repository.slug
+				});
+			}
+		}
+		const match = matches.sort((left, right) => left.connectionId.localeCompare(right.connectionId))[0];
+		if (!match) throw new GitLabApiError("GitLab issue is outside the active Factory project.", 404);
+		return this.intake.getIssue({
+			connection: gitlabConnection(match.connectionId),
+			sourceId: encodeSourceId(match),
+			issueId: input.issueId
+		});
+	}
+	/** Platform mode exposes org connections; direct mode returns undefined. */
+	async statusConnections() {}
+	/** Direct mode verifies its configured credential; Platform mode uses connection status. */
+	async verifyStatus() {}
+	get webhookSecret() {}
+	workers(ctx) {
+		if (!gitlabReconciliationEnabled()) return [];
+		const reconcile = attachGitLabReconciler(this, ctx);
+		if (!reconcile) return [];
+		const intervalMs = gitlabReconciliationInterval();
+		return [new IssueReconcileWorker({
+			integrationId: this.id,
+			reconcile,
+			...intervalMs ? { intervalMs } : {}
+		})];
+	}
+	routes(ctx) {
+		const ingestFactoryEvent = attachGitLabRules(this, ctx);
+		return buildGitLabRoutes({
+			gitlab: this,
+			auth: ctx.auth,
+			intake: ctx.storage?.intake,
+			emitAudit: ctx.hooks?.emitAudit,
+			sandbox: ctx.sandbox,
+			webhookSecret: this.webhookSecret,
+			ingestFactoryEvent,
+			...ctx.controller ? { controller: ctx.controller } : {}
+		});
+	}
+	async agentTools(args) {
+		return buildGitLabAgentTools({
+			requestContext: args.requestContext,
+			gitlab: this
+		});
+	}
+	sessionTools({ requestContext }) {
+		return createGitLabSubscriptionTools(requestContext, this);
+	}
+	async postToolObserver({ toolContext, requestContext }) {
+		const mergeRequestUrl = parseCreatedMergeRequest(toolContext);
+		if (!mergeRequestUrl || !requestContext) return;
+		await subscribeCurrentSessionToMergeRequest(requestContext, mergeRequestUrl, "auto-create-change-request", this);
+	}
+	/** Prefer the configured direct token over an older Platform installation on the same host. */
+	async resolveActiveConnectionForHost(storedConnectionId, host) {
+		if (this.diagnostics().mode !== "direct") return storedConnectionId;
+		const [direct] = await this.activeContexts();
+		return direct && normalizeGitLabHost(direct.host) === normalizeGitLabHost(host) ? direct.id : storedConnectionId;
+	}
+	async #versionControlContext(connection) {
+		const connectionId = connectionIdFromConnection(connection);
+		if (connectionId) return this.contextById(connectionId);
+		const contexts = await this.activeContexts();
+		if (contexts.length !== 1) throw new GitLabApiError("GitLab version-control requests must identify a connection when multiple GitLab accounts are connected.", 400);
+		return contexts[0];
+	}
+	async #versionControlContextForInstallation(connection, host) {
+		if (this.diagnostics().mode === "direct" && host) {
+			const [direct] = await this.activeContexts();
+			if (direct && normalizeGitLabHost(host) === normalizeGitLabHost(direct.host)) return direct;
+		}
+		return this.#versionControlContext(connection);
+	}
+	async #contextForReference(reference) {
+		if (reference.connectionId) return this.contextById(reference.connectionId);
+		const contexts = (await this.activeContexts()).filter((context) => !reference.host || normalizeGitLabHost(context.host) === normalizeGitLabHost(reference.host));
+		if (contexts.length === 0) throw new GitLabApiError("No active GitLab connection can access this source.", 401);
+		if (contexts.length === 1) return contexts[0];
+		if (this.#sourceControl) {
+			const linkedConnectionIds = new Set((await this.#sourceControl.projectRepositories.listConfiguredExternalKeys()).filter((key) => key.repositoryExternalId === reference.projectId).map((key) => key.installationExternalId));
+			const linked = contexts.filter((context) => linkedConnectionIds.has(context.id));
+			if (linked.length > 0) return linked.sort((left, right) => left.id.localeCompare(right.id))[0];
+		}
+		for (const context of contexts.sort((left, right) => left.id.localeCompare(right.id))) try {
+			await context.api.getProject(reference.projectId);
+			return context;
+		} catch (error) {
+			if (!(error instanceof GitLabApiError) || ![
+				401,
+				403,
+				404
+			].includes(error.status ?? 0)) throw error;
+		}
+		throw new GitLabApiError("No active GitLab connection can access this source.", 404);
+	}
+	async #resolveSourceReference(reference) {
+		const context = await this.#contextForReference(reference);
+		const projectPath = reference.projectPath ?? (await context.api.getProject(reference.projectId)).path_with_namespace;
+		return {
+			context,
+			source: {
+				connectionId: context.id,
+				host: normalizeGitLabHost(reference.host ?? context.host),
+				projectId: reference.projectId,
+				projectPath
+			}
+		};
+	}
+	async #resolveIntakeDispatch({ externalSource }) {
+		if (externalSource.type !== "issue") return null;
+		const reference = decodeIssueReference(externalSource.externalId);
+		if (!reference) return null;
+		const { context, source } = await this.#resolveSourceReference(reference);
+		return {
+			connection: context.connection,
+			sourceId: encodeSourceId(source),
+			issueId: String(reference.issueIid)
+		};
+	}
+	async #listSources() {
+		const sources = /* @__PURE__ */ new Map();
+		for (const context of await this.activeContexts()) for (let page = 1;; page++) {
+			const projects = await context.api.listProjects({ page });
+			for (const project of projects) {
+				const source = this.#toIntakeSource(context, project);
+				if (!sources.has(source.id)) sources.set(source.id, source);
+			}
+			if (projects.length < 100) break;
+		}
+		return [...sources.values()];
+	}
+	async #listItems(input) {
+		const result = await this.#listIssuePage(input.sourceIds, input.cursor);
+		return {
+			items: result.issues.map(({ issue, source, context }) => ({
+				source: {
+					type: "issue",
+					externalId: encodeIssueReference({
+						...source,
+						issueIid: issue.iid
+					}),
+					url: issue.web_url
+				},
+				sourceId: encodeSourceId(source),
+				title: `${source.projectPath}#${issue.iid}: ${issue.title}`,
+				status: issue.state,
+				labels: issue.labels ?? [],
+				assignee: displayName(issue.assignee),
+				createdAt: issue.created_at,
+				updatedAt: issue.updated_at,
+				metadata: {
+					identifier: `${source.projectPath}#${issue.iid}`,
+					projectId: source.projectId,
+					projectPath: source.projectPath,
+					connectionId: context.id,
+					accountLabel: context.label,
+					labelColors: Object.fromEntries((issue.labelDetails ?? []).map((label) => [label.name, label.color]))
+				}
+			})),
+			nextCursor: result.nextCursor
+		};
+	}
+	async #listIssues(input) {
+		const result = await this.#listIssuePage(input.sourceIds, input.cursor, input.labels);
+		return {
+			issues: result.issues.map(({ issue, source }) => ({
+				...this.#toIntakeIssue(issue, source.projectPath),
+				sourceId: encodeSourceId(source)
+			})),
+			nextCursor: result.nextCursor
+		};
+	}
+	async #listIssuePage(sourceIds, cursor, labels) {
+		const sources = sourceIds.map(decodeSourceId).filter((source) => source !== null);
+		if (sources.length === 0) return {
+			issues: [],
+			nextCursor: null
+		};
+		const current = decodePageCursor(cursor);
+		if (!current || current.source >= sources.length) return {
+			issues: [],
+			nextCursor: null
+		};
+		for (let sourceIndex = current.source; sourceIndex < sources.length; sourceIndex++) {
+			const { source, context } = await this.#resolveSourceReference(sources[sourceIndex]);
+			const page = sourceIndex === current.source ? current.page : 1;
+			const issues = await context.api.listIssues(source.projectId, {
+				page,
+				labels
+			});
+			const nextCursor = issues.length === 30 ? encodePageCursor({
+				source: sourceIndex,
+				page: page + 1
+			}) : sourceIndex + 1 < sources.length ? encodePageCursor({
+				source: sourceIndex + 1,
+				page: 1
+			}) : null;
+			return {
+				issues: issues.map((issue) => ({
+					issue,
+					source,
+					context
+				})),
+				nextCursor
+			};
+		}
+		return {
+			issues: [],
+			nextCursor: null
+		};
+	}
+	async #getIssue(input) {
+		const resolved = await this.#resolveRequest(input);
+		let issue;
+		try {
+			issue = await resolved.context.api.getIssue(resolved.projectId, resolved.issueIid);
+		} catch (error) {
+			if (error instanceof GitLabApiError && error.status === 404) return null;
+			throw error;
+		}
+		const notes = await this.#listAllNotes(resolved.context.api, resolved.projectId, resolved.issueIid);
+		return {
+			...this.#toIntakeIssue(issue, resolved.projectPath),
+			description: issue.description?.trim() || null,
+			comments: notes.filter((note) => !note.system).map((note) => ({
+				author: displayName(note.author),
+				body: note.body,
+				createdAt: note.created_at
+			}))
+		};
+	}
+	async #listAllNotes(api, projectId, issueIid) {
+		const notes = [];
+		for (let page = 1; page <= MAX_NOTES_PAGES; page++) {
+			const result = await api.listNotes(projectId, issueIid, { page });
+			notes.push(...result);
+			if (result.length < 100) break;
+		}
+		return notes;
+	}
+	async #createComment(input) {
+		const resolved = await this.#resolveRequest(input);
+		try {
+			const issue = await resolved.context.api.getIssue(resolved.projectId, resolved.issueIid);
+			const note = await resolved.context.api.createNote(resolved.projectId, resolved.issueIid, input.body);
+			return {
+				id: String(note.id),
+				url: `${issue.web_url}#note_${note.id}`
+			};
+		} catch (error) {
+			if (error instanceof GitLabApiError && error.status === 404) return null;
+			throw error;
+		}
+	}
+	async #updateIssue(input) {
+		const resolved = await this.#resolveRequest(input);
+		let issue;
+		try {
+			issue = await resolved.context.api.getIssue(resolved.projectId, resolved.issueIid);
+		} catch (error) {
+			if (error instanceof GitLabApiError && error.status === 404) return null;
+			throw error;
+		}
+		const stateEvent = targetStateEvent(input);
+		if (!stateEvent) return null;
+		if (stateEvent === "close" && issue.state === "closed" || stateEvent === "reopen" && issue.state === "opened") return this.#toIntakeIssue(issue, resolved.projectPath);
+		const updated = await resolved.context.api.updateIssueState(resolved.projectId, resolved.issueIid, stateEvent);
+		return this.#toIntakeIssue(updated, resolved.projectPath);
+	}
+	async #resolveRequest(input) {
+		const issueReference = decodeIssueReference(input.issueId);
+		const source = input.sourceId ? decodeSourceId(input.sourceId) : null;
+		const locator = parseIssueLocator(input.issueId);
+		const reference = issueReference ?? source;
+		let context;
+		if (reference) context = await this.#contextForReference(reference);
+		else {
+			const connectionId = connectionIdFromConnection(input.connection);
+			const contexts = connectionId ? [await this.contextById(connectionId)] : await this.activeContexts();
+			if (contexts.length !== 1) throw new GitLabApiError("GitLab issue reference must resolve to exactly one active connection.", 400);
+			context = contexts[0];
+		}
+		const projectId = issueReference?.projectId ?? source?.projectId ?? locator?.projectPath;
+		const issueIid = issueReference?.issueIid ?? locator?.issueIid ?? parsePositiveInteger(input.issueId);
+		if (!projectId || !issueIid) throw new GitLabApiError("GitLab issue must include a project and issue IID (for example, group/project#42).", 400);
+		const projectPath = issueReference?.projectPath ?? source?.projectPath ?? locator?.projectPath ?? (await context.api.getProject(projectId)).path_with_namespace;
+		return {
+			context,
+			projectId,
+			projectPath,
+			issueIid
+		};
+	}
+	#toIntakeSource(context, project) {
+		return {
+			id: encodeSourceId({
+				host: normalizeGitLabHost(context.host),
+				projectId: String(project.id),
+				projectPath: project.path_with_namespace
+			}),
+			name: project.path_with_namespace,
+			type: "project",
+			metadata: {
+				projectId: String(project.id),
+				projectPath: project.path_with_namespace,
+				defaultBranch: project.default_branch ?? null,
+				connectionId: context.id,
+				accountLabel: context.label,
+				url: project.web_url
+			}
+		};
+	}
+	#toIntakeIssue(issue, projectPath) {
+		const assignees = issue.assignees?.map(displayName).filter((name) => name !== null) ?? [];
+		return {
+			id: String(issue.iid),
+			identifier: `${projectPath}#${issue.iid}`,
+			title: issue.title,
+			url: issue.web_url,
+			author: displayName(issue.author),
+			authorUsername: issue.author?.username ?? null,
+			state: issue.state,
+			stateType: issue.state === "closed" ? "completed" : "unstarted",
+			priority: typeof issue.weight === "number" ? String(issue.weight) : null,
+			assignee: displayName(issue.assignee) ?? assignees[0] ?? null,
+			assignees,
+			source: projectPath,
+			labels: issue.labels ?? [],
+			labelColors: Object.fromEntries((issue.labelDetails ?? []).map((label) => [label.name, label.color])),
+			commentCount: issue.user_notes_count ?? null,
+			createdAt: issue.created_at,
+			updatedAt: issue.updated_at
+		};
+	}
+};
+const DIRECT_CONNECTION_TOKEN = "gitlab-direct-access-token";
+var GitLabIntegration = class extends GitLabIntegrationBase {
+	#accessToken;
+	#accessTokenType;
+	#baseUrl;
+	#webhookSecret;
+	#context;
+	constructor(config = {}) {
+		super(config.rules);
+		const accessToken = config.accessToken?.trim() || process.env.GITLAB_ACCESS_TOKEN?.trim();
+		if (!accessToken) throw new Error("GitLabIntegration: missing required GITLAB_ACCESS_TOKEN.");
+		this.#accessToken = accessToken;
+		this.#accessTokenType = parseAccessTokenType(config.accessTokenType ?? process.env.GITLAB_ACCESS_TOKEN_TYPE?.trim());
+		this.#baseUrl = (config.baseUrl ?? process.env.GITLAB_BASE_URL?.trim() ?? "https://gitlab.com").replace(/\/+$/, "");
+		this.#webhookSecret = config.webhookSecret?.trim() || process.env.GITLAB_WEBHOOK_SECRET?.trim() || void 0;
+		const api = new GitLabApiClient({
+			baseUrl: this.#baseUrl,
+			accessToken: this.#accessToken,
+			...config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}
+		});
+		this.#context = {
+			id: DIRECT_CONNECTION_ID,
+			label: new URL(this.#baseUrl).host,
+			api,
+			connection: {
+				type: "oauth",
+				accessToken: DIRECT_CONNECTION_TOKEN
+			},
+			host: new URL(this.#baseUrl).host,
+			webBaseUrl: this.#baseUrl,
+			repositoryAccessToken: async () => this.#accessToken
+		};
+	}
+	get webhookSecret() {
+		return this.#webhookSecret;
+	}
+	async hasActiveConnections() {
+		return true;
+	}
+	async verifyStatus() {
+		await this.#context.api.getCurrentUser();
+	}
+	authFailureMessage() {
+		return `GitLab rejected the configured ${this.#accessTokenType} access token. Check the token and its scopes.`;
+	}
+	async activeContexts() {
+		return [this.#context];
+	}
+	async contextById(connectionId) {
+		if (connectionId !== DIRECT_CONNECTION_ID) throw new GitLabApiError("GitLab connection is unavailable.", 401);
+		return this.#context;
+	}
+	diagnostics() {
+		return {
+			configured: true,
+			mode: "direct",
+			accessTokenType: this.#accessTokenType,
+			endpointHost: new URL(this.#baseUrl).host,
+			webhookConfigured: Boolean(this.#webhookSecret)
+		};
+	}
+};
+function parseAccessTokenType(value) {
+	const normalized = value?.trim().toLowerCase() || "personal";
+	if (normalized === "personal" || normalized === "group") return normalized;
+	throw new Error("GitLabIntegration: GITLAB_ACCESS_TOKEN_TYPE must be 'personal' or 'group'.");
+}
+function encodeSourceId(reference) {
+	if (reference.host) return `${GITLAB_SOURCE_PREFIX}${encodeOpaque({
+		version: 2,
+		host: normalizeGitLabHost(reference.host),
+		projectId: reference.projectId
+	})}`;
+	if (!reference.connectionId || !reference.projectPath) throw new Error("GitLab source reference is missing its instance host.");
+	return `${GITLAB_SOURCE_PREFIX}${encodeOpaque(reference)}`;
+}
+function decodeSourceId(value) {
+	return decodeOpaque(value, GITLAB_SOURCE_PREFIX, isSourceReference);
+}
+function encodeIssueReference(reference) {
+	if (reference.host) return `${GITLAB_ISSUE_PREFIX}${encodeOpaque({
+		version: 2,
+		host: normalizeGitLabHost(reference.host),
+		projectId: reference.projectId,
+		issueIid: reference.issueIid
+	})}`;
+	if (!reference.connectionId || !reference.projectPath) throw new Error("GitLab issue reference is missing its instance host.");
+	return `${GITLAB_ISSUE_PREFIX}${encodeOpaque(reference)}`;
+}
+function decodeIssueReference(value) {
+	return decodeOpaque(value, GITLAB_ISSUE_PREFIX, isIssueReference);
+}
+function decodeMergeRequestReference(value) {
+	return decodeOpaque(value, GITLAB_MERGE_REQUEST_PREFIX, isMergeRequestReference);
+}
+function gitlabConnection(connectionId) {
+	return {
+		type: "oauth",
+		accessToken: `${GITLAB_CONNECTION_TOKEN_PREFIX}${connectionId}`
+	};
+}
+function connectionIdFromConnection(connection) {
+	if (connection.type !== "oauth" || !connection.accessToken.startsWith(GITLAB_CONNECTION_TOKEN_PREFIX)) return null;
+	return connection.accessToken.slice(18) || null;
+}
+function encodeOpaque(value) {
+	return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function decodeOpaque(value, prefix, guard) {
+	if (!value.startsWith(prefix)) return null;
+	try {
+		const decoded = JSON.parse(Buffer.from(value.slice(prefix.length), "base64url").toString("utf8"));
+		return guard(decoded) ? decoded : null;
+	} catch {
+		return null;
+	}
+}
+function normalizeGitLabHost(host) {
+	return host.trim().toLowerCase().replace(/\.$/, "");
+}
+function isSourceReference(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const ref = value;
+	if (typeof ref.projectId !== "string" || ref.projectId.length === 0) return false;
+	const canonical = ref.version === 2 && typeof ref.host === "string" && normalizeGitLabHost(ref.host).length > 0;
+	const legacy = typeof ref.connectionId === "string" && ref.connectionId.length > 0 && typeof ref.projectPath === "string" && ref.projectPath.length > 0;
+	return canonical || legacy;
+}
+function isIssueReference(value) {
+	return isSourceReference(value) && Number.isSafeInteger(value.issueIid) && value.issueIid > 0;
+}
+function isMergeRequestReference(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const ref = value;
+	return ref.version === 1 && typeof ref.host === "string" && normalizeGitLabHost(ref.host).length > 0 && Number.isSafeInteger(ref.projectId) && ref.projectId > 0 && Number.isSafeInteger(ref.mergeRequestIid) && ref.mergeRequestIid > 0;
+}
+function encodePageCursor(cursor) {
+	return encodeOpaque(cursor);
+}
+function decodePageCursor(value) {
+	if (!value) return {
+		source: 0,
+		page: 1
+	};
+	try {
+		const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+		if (!Number.isSafeInteger(decoded.source) || Number(decoded.source) < 0) return null;
+		if (!Number.isSafeInteger(decoded.page) || Number(decoded.page) < 1) return null;
+		return {
+			source: Number(decoded.source),
+			page: Number(decoded.page)
+		};
+	} catch {
+		return null;
+	}
+}
+function displayName(user) {
+	return user?.name?.trim() || user?.username || null;
+}
+function parsePositiveInteger(value) {
+	if (!/^\d+$/.test(value)) return null;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function parseIssueLocator(value) {
+	const shorthand = value.match(/^(.+?)#(\d+)$/);
+	if (shorthand) {
+		const issueIid = parsePositiveInteger(shorthand[2]);
+		const projectPath = shorthand[1].replace(/^\/+|\/+$/g, "");
+		return issueIid && projectPath ? {
+			projectPath,
+			issueIid
+		} : null;
+	}
+	try {
+		const url = new URL(value);
+		const match = url.pathname.match(/^\/(.+)\/-\/issues\/(\d+)\/?$/);
+		if (!match) return null;
+		const issueIid = parsePositiveInteger(match[2]);
+		if (!issueIid) return null;
+		const projectPath = decodeURIComponent(match[1]);
+		return {
+			host: url.host,
+			projectPath,
+			issueIid
+		};
+	} catch {
+		return null;
+	}
+}
+function targetStateEvent(input) {
+	if (input.state.kind === "byType") return input.state.stateType === "completed" || input.state.stateType === "canceled" ? "close" : "reopen";
+	const name = input.state.name.trim().toLowerCase();
+	if (name === "closed" || name === "close") return "close";
+	if (name === "opened" || name === "open" || name === "reopen") return "reopen";
+	return null;
+}
+//#endregion
+export { GITLAB_TRUSTED_ACCESS_LEVEL, GitLabIntegration, GitLabIntegrationBase, decodeIssueReference, decodeMergeRequestReference, decodeSourceId, encodeIssueReference, encodeSourceId, gitlabConnection, normalizeGitLabHost };
+
+//# sourceMappingURL=integration.js.map