@gitkraken/core-gitlens 0.4.0 → 0.4.100

package/src/plus/integrations/models/issuesIntegration.ts

@@ -1,3 +1,4 @@
+import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { Account } from '../../../git/models/author.js';
 import type { IssueShape } from '../../../git/models/issue.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
@@ -6,8 +7,9 @@ import { trace } from '../../../utils/decorators/log.js';
 import { getScopedLogger } from '../../../utils/logger.scoped.js';
 import type { ProviderAuthenticationSession } from '../authentication/models.js';
 import type { IntegrationIds } from '../constants.js';
-import type { IssueFilter } from '../providers/models.js';
-import type { Integration, IntegrationType } from './integration.js';
+import { toError } from '../errors.js';
+import type { IssueFilter, ProviderApiCollectionResult } from '../providers/models.js';
+import type { Integration, IntegrationResult, IntegrationType } from './integration.js';
 import { IntegrationBase } from './integration.js';
 
 export function isIssuesIntegration(integration: Integration): integration is IssuesIntegration {
@@ -20,22 +22,34 @@ export abstract class IssuesIntegration<
 > extends IntegrationBase<ID> {
 	readonly type: IntegrationType = 'issues';
 
-	@gate()
 	@trace()
-	async getAccountForResource(resource: T): Promise<Account | undefined> {
-		const scope = getScopedLogger();
-		const connected = this.maybeConnected ?? (await this.isConnected());
-		if (!connected) return undefined;
+	async getAccountForResource(resource: T, connectionId?: string): Promise<Account | undefined> {
+		return (await this.getAccountForResourceResult(resource, connectionId))?.value;
+	}
 
-		await this.refreshSessionIfExpired(scope);
+	/**
+	 * Result-returning core of {@link getAccountForResource}. Recovers a thrown error into `{ error }` so
+	 * callers can preserve its classification (e.g. a 401/403 → an `auth` warning that drives re-auth)
+	 * instead of collapsing every failure into an untyped `undefined`. Gated here (not on the wrapper) so
+	 * direct callers such as the ProviderBackend facade share the same dedup as `getAccountForResource`.
+	 */
+	@gate()
+	async getAccountForResourceResult(
+		resource: T,
+		connectionId?: string,
+	): Promise<IntegrationResult<Account | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
 
 		try {
-			const account = await this.getProviderAccountForResource(this._session!, resource);
+			const account = await this.getProviderAccountForResource(session, resource);
 			this.resetRequestExceptionCount('getAccountForResource');
-			return account;
+			return { value: account };
 		} catch (ex) {
 			this.handleProviderException('getAccountForResource', ex);
-			return undefined;
+			return { error: toError(ex) };
 		}
 	}
 
@@ -44,50 +58,120 @@ export abstract class IssuesIntegration<
 		resource: T,
 	): Promise<Account | undefined>;
 
-	@gate()
 	@trace()
-	async getResourcesForUser(): Promise<T[] | undefined> {
-		const scope = getScopedLogger();
-		const connected = this.maybeConnected ?? (await this.isConnected());
-		if (!connected) return undefined;
+	async getResourcesForUser(connectionId?: string): Promise<T[] | undefined> {
+		return (await this.getResourcesForUserResult(connectionId))?.value;
+	}
 
-		await this.refreshSessionIfExpired(scope);
+	/**
+	 * Result-returning core of {@link getResourcesForUser}. Recovers thrown errors into `{ error }` so callers
+	 * can surface them as warnings rather than silently swallowing them to `undefined`. Gated here (not on the
+	 * wrapper) so direct callers such as the ProviderBackend facade share the same dedup as `getResourcesForUser`.
+	 */
+	@gate()
+	async getResourcesForUserResult(connectionId?: string): Promise<IntegrationResult<T[] | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
 
 		try {
-			const resources = await this.getProviderResourcesForUser(this._session!);
+			const resources = await this.getProviderResourcesForUser(session);
 			this.resetRequestExceptionCount('getResourcesForUser');
-			return resources;
+			return { value: resources };
 		} catch (ex) {
 			this.handleProviderException('getResourcesForUser', ex);
-			return undefined;
+			return { error: toError(ex) };
 		}
 	}
 
 	protected abstract getProviderResourcesForUser(session: ProviderAuthenticationSession): Promise<T[] | undefined>;
 
 	@trace()
-	async getProjectsForResources(resources: T[]): Promise<T[] | undefined> {
-		const scope = getScopedLogger();
-		const connected = this.maybeConnected ?? (await this.isConnected());
-		if (!connected) return undefined;
+	async getProjectsForResources(resources: T[], connectionId?: string): Promise<T[] | undefined> {
+		return (await this.getProjectsForResourcesResult(resources, connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getProjectsForResources}. Recovers thrown errors into `{ error }` so callers
+	 * can surface them as warnings rather than silently swallowing them to `undefined`. Implemented by unwrapping
+	 * the metadata-aware path's `values` so the array-returning contract stays backward compatible.
+	 */
+	async getProjectsForResourcesResult(
+		resources: T[],
+		connectionId?: string,
+	): Promise<IntegrationResult<T[] | undefined>> {
+		const result = await this.getProjectsForResourcesWithMetadataResult(resources, connectionId);
+		if (result == null) return undefined;
+		if (result.error != null) return { value: result.value?.values, error: result.error };
+		return { value: result.value?.values };
+	}
 
-		await this.refreshSessionIfExpired(scope);
+	/**
+	 * Metadata-aware counterpart of {@link getProjectsForResourcesResult} for ProviderBackend composition:
+	 * returns the SDK collection `{ values, metadata }` (completeness + per-resource failures) so callers can
+	 * warn on failed resources and set `fetchFailed` without discarding the resources that succeeded.
+	 */
+	async getProjectsForResourcesWithMetadataResult(
+		resources: T[],
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderApiCollectionResult<T> | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
 
 		try {
-			const projects = await this.getProviderProjectsForResources(this._session!, resources);
+			const projects = await this.getProviderProjectsForResourcesWithMetadata(session, resources);
 			this.resetRequestExceptionCount('getProjectsForResources');
-			return projects;
+			return { value: projects };
 		} catch (ex) {
 			this.handleProviderException('getProjectsForResources', ex);
-			return undefined;
+			return { error: toError(ex) };
 		}
 	}
 
-	async getProjectsForUser(): Promise<T[] | undefined> {
-		const resources = await this.getResourcesForUser();
-		if (resources == null) return undefined;
+	async getProjectsForUser(connectionId?: string): Promise<T[] | undefined> {
+		return (await this.getProjectsForUserResult(connectionId))?.value;
+	}
 
-		return this.getProjectsForResources(resources);
+	/**
+	 * Result-returning core of {@link getProjectsForUser}. Composes the resource and project result methods so
+	 * callers can surface per-step warnings. Unwraps the metadata-aware path for the array-returning contract.
+	 */
+	async getProjectsForUserResult(connectionId?: string): Promise<IntegrationResult<T[] | undefined>> {
+		const result = await this.getProjectsForUserWithMetadataResult(connectionId);
+		if (result == null) return undefined;
+		if (result.error != null) return { value: result.value?.values, error: result.error };
+		return { value: result.value?.values };
+	}
+
+	/**
+	 * Metadata-aware counterpart of {@link getProjectsForUserResult}: composes resource discovery with the
+	 * metadata-aware project read so ProviderBackend consumers get completeness/failures across resources.
+	 */
+	async getProjectsForUserWithMetadataResult(
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderApiCollectionResult<T> | undefined>> {
+		const resources = await this.getResourcesForUserResult(connectionId);
+		if (resources?.error != null) return { error: resources.error };
+		if (resources?.value == null) return undefined;
+
+		return this.getProjectsForResourcesWithMetadataResult(resources.value, connectionId);
+	}
+
+	/**
+	 * Metadata-aware provider project discovery. The default wraps the array-returning
+	 * {@link getProviderProjectsForResources} in `{ values }` with no metadata, so providers without a
+	 * fan-out completeness signal (Linear, Trello) need no change; Jira overrides it to preserve the SDK's
+	 * per-resource completeness/failures.
+	 */
+	protected async getProviderProjectsForResourcesWithMetadata(
+		session: ProviderAuthenticationSession,
+		resources: T[],
+	): Promise<ProviderApiCollectionResult<T>> {
+		const projects = await this.getProviderProjectsForResources(session, resources);
+		return { values: projects ?? [] };
 	}
 
 	protected abstract getProviderProjectsForResources(
@@ -99,20 +183,60 @@ export abstract class IssuesIntegration<
 	async getIssuesForProject(
 		project: T,
 		options?: { user?: string; filters?: IssueFilter[] },
+		connectionId?: string,
 	): Promise<IssueShape[] | undefined> {
+		return (await this.getIssuesForProjectResult(project, options, connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getIssuesForProject}. Recovers thrown errors into `{ error }` so callers
+	 * (e.g. the ProviderBackend facade) can surface a per-provider warning instead of a silent empty read —
+	 * important for providers that throw on unsupported operations (e.g. Linear's not-implemented issue read).
+	 */
+	async getIssuesForProjectResult(
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+		connectionId?: string,
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
 		const scope = getScopedLogger();
-		const connected = this.maybeConnected ?? (await this.isConnected());
-		if (!connected) return undefined;
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		try {
+			const issues = await this.getProviderIssuesForProject(session, project, options);
+			this.resetRequestExceptionCount('getIssuesForProject');
+			return { value: issues };
+		} catch (ex) {
+			this.handleProviderException('getIssuesForProject', ex);
+			return { error: toError(ex) };
+		}
+	}
 
-		await this.refreshSessionIfExpired(scope);
+	/**
+	 * Truncation-aware variant of {@link getIssuesForProjectResult}. A provider that drains a project's issues
+	 * with an internal page backstop (Jira/Linear) overrides {@link getProviderIssuesForProjectWithTruncation}
+	 * to report when that backstop was hit, so the facade can surface an incomplete project read instead of
+	 * publishing it as complete. The default reports `truncated: false`.
+	 */
+	async getIssuesForProjectWithTruncationResult(
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+		connectionId?: string,
+	): Promise<
+		IntegrationResult<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined>
+	> {
+		const scope = getScopedLogger();
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
 
 		try {
-			const issues = await this.getProviderIssuesForProject(this._session!, project, options);
+			const result = await this.getProviderIssuesForProjectWithTruncation(session, project, options);
 			this.resetRequestExceptionCount('getIssuesForProject');
-			return issues;
+			return { value: result };
 		} catch (ex) {
 			this.handleProviderException('getIssuesForProject', ex);
-			return undefined;
+			return { error: toError(ex) };
 		}
 	}
 
@@ -121,4 +245,20 @@ export abstract class IssuesIntegration<
 		project: T,
 		options?: { user?: string; filters?: IssueFilter[] },
 	): Promise<IssueShape[] | undefined>;
+
+	/**
+	 * Truncation-aware core of {@link getProviderIssuesForProject}. The default wraps the plain read and
+	 * reports `truncated: false`; a provider whose per-project drain is capped by a page backstop overrides
+	 * this to report incompleteness. Optional metadata lets providers surface structured per-project failures
+	 * (e.g. a page-level auth rejection) without discarding the already-fetched prefix.
+	 */
+	protected async getProviderIssuesForProjectWithTruncation(
+		session: ProviderAuthenticationSession,
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
+		const values = await this.getProviderIssuesForProject(session, project, options);
+		if (values == null) return undefined;
+		return { values: values, truncated: false };
+	}
 }

package/src/plus/integrations/providerFilters.ts

@@ -0,0 +1,12 @@
+export enum PullRequestFilter {
+	Author = 'author',
+	Assignee = 'assignee',
+	ReviewRequested = 'review-requested',
+	Mention = 'mention',
+}
+
+export enum IssueFilter {
+	Author = 'author',
+	Assignee = 'assignee',
+	Mention = 'mention',
+}

package/src/plus/integrations/providers/apiClients.ts

@@ -49,23 +49,20 @@ export function createApiClients(ctx: IntegrationServiceContext, disposables: Di
 			));
 		},
 		get gitlab() {
-			return (gitlab ??= build(
-				async () =>
-					new (await import(/* webpackChunkName: "integrations" */ './gitlab/gitlab.js')).GitLabApi(ctx),
+			return (gitlab ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './gitlab/gitlab.js')).createGitLabApi(ctx),
 			));
 		},
 		get bitbucket() {
-			return (bitbucket ??= build(
-				async () =>
-					new (await import(/* webpackChunkName: "integrations" */ './bitbucket/bitbucket.js')).BitbucketApi(
-						ctx,
-					),
+			return (bitbucket ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './bitbucket/bitbucket.js')).createBitbucketApi(
+					ctx,
+				),
 			));
 		},
 		get azure() {
-			return (azure ??= build(
-				async () =>
-					new (await import(/* webpackChunkName: "integrations" */ './azure/azure.js')).AzureDevOpsApi(ctx),
+			return (azure ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './azure/azure.js')).createAzureDevOpsApi(ctx),
 			));
 		},
 	};

package/src/plus/integrations/providers/apiConfig.ts

@@ -0,0 +1,71 @@
+import type { IntegrationServiceContext } from '../context.js';
+
+/**
+ * VS Code-free configuration for the package-owned provider API clients
+ * ({@link GitLabApi}, {@link BitbucketApi}, {@link AzureDevOpsApi}).
+ *
+ * Mirrors the role {@link import('../../git-github/api/config.js').GitHubApiConfig}
+ * plays for `GitHubApi`: instead of taking the full {@link IntegrationServiceContext},
+ * a client takes only the narrow HTTP + callback surface it actually uses. The
+ * `createIntegrationManager` path wires this from `ctx` (see the `create*Api`
+ * factories); a token-scoped consumer builds it from a `fetch` plus a
+ * `wrapForForcedInsecureSSL` (a pass-through is fine when not toggling SSL).
+ *
+ * Every field beyond `fetch`/`wrapForForcedInsecureSSL` is optional — a client omits
+ * the call when unset, so a minimal consumer only supplies the two required members.
+ */
+export interface ProviderApiConfig {
+	/** The `fetch` implementation to use for HTTP requests. */
+	fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+
+	/**
+	 * Wraps an async operation so that TLS certificate validation is disabled when the
+	 * provider's `getIgnoreSSLErrors()` returns `'force'`. On the browser it's a no-op.
+	 */
+	wrapForForcedInsecureSSL<T>(ignoreSSLErrors: boolean | 'force', fn: () => Promise<T> | PromiseLike<T>): Promise<T>;
+
+	/**
+	 * Fires when the HTTP proxy configuration changes, so the client can reset its HTTP caches.
+	 * The factory filters the underlying config-change event down to the keys the client cares about.
+	 */
+	onConfigChanged?(listener: () => void): { dispose(): void };
+
+	/**
+	 * Ask the consumer to confirm reauthentication after an auth/permission failure (401/403). Resolves to
+	 * the user's choice; the client performs the actual `provider.reauthenticate()` when this is truthy.
+	 * Only GitLab wires this today.
+	 */
+	onReauthenticationRequired?(message: string): Promise<boolean | undefined>;
+
+	/** A non-fatal error to surface (debug display / notification). */
+	onError?(message: string): void;
+
+	/** The provider API returned a server-side (500-level) error. */
+	onRequestFailed?(message: string): void;
+
+	/** The provider API request timed out; `providerName` names the integration for the message. */
+	onRequestTimedOut?(providerName: string): void;
+
+	/** Bitbucket's "Pull Requests for Commit" app isn't installed; `revLink` opens the install page. */
+	onBitbucketCommitLinksAppMissing?(revLink: string): void;
+}
+
+/**
+ * The `ctx` → {@link ProviderApiConfig} mapping shared by every `create*Api` factory. Each provider
+ * spreads this and layers on its own deltas (GitLab also resets on `remotes` + wires reauth/timeout;
+ * Bitbucket adds the commit-links-app hook). Resets HTTP caches on HTTP proxy config changes.
+ */
+export function baseProviderApiConfig(ctx: IntegrationServiceContext): ProviderApiConfig {
+	return {
+		fetch: ctx.http.fetch.bind(ctx.http),
+		wrapForForcedInsecureSSL: ctx.http.wrapForForcedInsecureSSL.bind(ctx.http),
+		onConfigChanged: listener =>
+			ctx.config.onDidChange(e => {
+				if (e.httpProxy) {
+					listener();
+				}
+			}),
+		onError: message => ctx.hooks?.ui?.onError?.(message),
+		onRequestFailed: message => ctx.hooks?.ui?.onRequestFailed?.(message),
+	};
+}