@gitkraken/core-gitlens 0.4.0 → 0.4.101

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,73 @@ 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>;
 
+	/**
+	 * Project discovery for a set of resources, returning 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. Thrown errors are recovered into `{ error }` for the same reason: a caller
+	 * surfaces them as a warning rather than swallowing them to `undefined`.
+	 */
 	@trace()
-	async getProjectsForResources(resources: T[]): Promise<T[] | undefined> {
+	async getProjectsForResourcesWithMetadataResult(
+		resources: T[],
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderApiCollectionResult<T> | undefined>> {
 		const scope = getScopedLogger();
-		const connected = this.maybeConnected ?? (await this.isConnected());
-		if (!connected) return undefined;
-
-		await this.refreshSessionIfExpired(scope);
+		// `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;
-
-		return this.getProjectsForResources(resources);
+	/**
+	 * 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 +136,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;
 
-		await this.refreshSessionIfExpired(scope);
+		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) };
+		}
+	}
+
+	/**
+	 * 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 +198,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),
+	};
+}

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

@@ -1,30 +1,37 @@
 import type { UnidentifiedAuthor } from '../../../../git/models/author.js';
+import type { DefaultBranch } from '../../../../git/models/defaultBranch.js';
 import type { Issue } from '../../../../git/models/issue.js';
 import type { IssueOrPullRequest, IssueOrPullRequestType } from '../../../../git/models/issueOrPullRequest.js';
 import type { PullRequest } from '../../../../git/models/pullRequest.js';
 import type { Provider } from '../../../../git/models/remoteProvider.js';
+import type { RepositoryMetadata } from '../../../../git/models/repositoryMetadata.js';
 import { base64 } from '../../../../utils/base64.js';
-import { CancellationError } from '../../../../utils/cancellation.js';
+import { CancellationError, isCancellationError } from '../../../../utils/cancellation.js';
 import { trace } from '../../../../utils/decorators/log.js';
 import type { Disposable } from '../../../../utils/disposable.js';
 import { Logger } from '../../../../utils/logger.js';
 import type { ScopedLogger } from '../../../../utils/logger.scoped.js';
 import { getScopedLogger } from '../../../../utils/logger.scoped.js';
 import { maybeStopWatch } from '../../../../utils/stopwatch.js';
-import type { TokenInfo, TokenWithInfo } from '../../authentication/models.js';
+import type { TokenWithInfo } from '../../authentication/models.js';
 import type { IntegrationServiceContext } from '../../context.js';
 import {
 	AuthenticationError,
 	AuthenticationErrorReason,
+	isRateLimitResponse,
 	ProviderFetchError,
 	RequestClientError,
 	RequestNotFoundError,
+	toRateLimitError,
 } from '../../errors.js';
+import type { ProviderApiConfig } from '../apiConfig.js';
+import { baseProviderApiConfig } from '../apiConfig.js';
 import type {
 	AzureGitCommit,
 	AzureProjectDescriptor,
 	AzurePullRequest,
 	AzurePullRequestWithLinks,
+	AzureRepositoryWithMetadata,
 	AzureWorkItemState,
 	AzureWorkItemStateCategory,
 	WorkItem,
@@ -37,6 +44,7 @@ import {
 	getAzurePullRequestWebUrl,
 	isClosedAzurePullRequestStatus,
 	isClosedAzureWorkItemStateCategory,
+	normalizeAzureBranchName,
 } from './models.js';
 
 class WorkItemStates {
@@ -89,19 +97,15 @@ class WorkItemStates {
 }
 
 export class AzureDevOpsApi implements Disposable {
-	private readonly _disposable: Disposable;
+	private readonly _disposable: Disposable | undefined;
 	private _workItemStates: WorkItemStates = new WorkItemStates();
 
-	constructor(private readonly ctx: IntegrationServiceContext) {
-		this._disposable = ctx.config.onDidChange(e => {
-			if (e.httpProxy) {
-				this.resetCaches();
-			}
-		});
+	constructor(private readonly config: ProviderApiConfig) {
+		this._disposable = config.onConfigChanged?.(() => this.resetCaches());
 	}
 
 	dispose(): void {
-		this._disposable.dispose();
+		this._disposable?.dispose();
 	}
 
 	private resetCaches(): void {
@@ -574,6 +578,132 @@ export class AzureDevOpsApi implements Disposable {
 		}
 	}
 
+	@trace({
+		args: (provider, token, owner, repo) => ({
+			provider: provider.name,
+			token: `<token:${token.microHash}>`,
+			owner: owner,
+			repo: repo,
+		}),
+	})
+	async getRepositoryMetadata(
+		provider: Provider,
+		token: TokenWithInfo,
+		owner: string,
+		repo: string,
+		options: {
+			baseUrl: string;
+		},
+		cancellation?: AbortSignal,
+	): Promise<RepositoryMetadata | undefined> {
+		const scope = getScopedLogger();
+
+		try {
+			const response = await this.getRepository(
+				provider,
+				token,
+				owner,
+				repo,
+				options.baseUrl,
+				scope,
+				cancellation,
+			);
+			if (response == null) return undefined;
+
+			// Azure's `parentRepository` only reliably carries the repo name and its project; a fork's parent
+			// lives in the same organization, so the org (`owner`) is the parent owner. Only report `parent`
+			// when the parent's name is actually present — never fall back to the fork's own name.
+			return {
+				provider: provider,
+				owner: owner,
+				// Prefer the API's canonical name over parsing the composite `repo` descriptor string.
+				name: response.name,
+				isFork: response.isFork ?? false,
+				parent:
+					response.isFork && response.parentRepository?.name != null
+						? { owner: owner, name: response.parentRepository.name }
+						: undefined,
+			} satisfies RepositoryMetadata;
+		} catch (ex) {
+			// Cancellations and 404s are expected outcomes for a probe; don't log them as errors.
+			if (!isCancellationError(ex) && !(ex instanceof RequestNotFoundError)) {
+				scope?.error(ex);
+			}
+			return undefined;
+		}
+	}
+
+	@trace({
+		args: (provider, token, owner, repo) => ({
+			provider: provider.name,
+			token: `<token:${token.microHash}>`,
+			owner: owner,
+			repo: repo,
+		}),
+	})
+	async getDefaultBranch(
+		provider: Provider,
+		token: TokenWithInfo,
+		owner: string,
+		repo: string,
+		options: {
+			baseUrl: string;
+		},
+		cancellation?: AbortSignal,
+	): Promise<DefaultBranch | undefined> {
+		const scope = getScopedLogger();
+
+		try {
+			const response = await this.getRepository(
+				provider,
+				token,
+				owner,
+				repo,
+				options.baseUrl,
+				scope,
+				cancellation,
+			);
+			if (response?.defaultBranch == null) return undefined;
+
+			return {
+				provider: provider,
+				name: normalizeAzureBranchName(response.defaultBranch),
+			} satisfies DefaultBranch;
+		} catch (ex) {
+			// Cancellations and 404s are expected outcomes for a probe; don't log them as errors.
+			if (!isCancellationError(ex) && !(ex instanceof RequestNotFoundError)) {
+				scope?.error(ex);
+			}
+			return undefined;
+		}
+	}
+
+	private getRepository(
+		provider: Provider,
+		token: TokenWithInfo,
+		owner: string,
+		repo: string,
+		baseUrl: string,
+		scope: ScopedLogger | undefined,
+		cancellation?: AbortSignal,
+	): Promise<AzureRepositoryWithMetadata | undefined> {
+		const parts = repo.split('/');
+		const [projectName, segment, repoName] = parts;
+		// The descriptor must be exactly `"{project}/_git/{repoName}"`; bail before issuing a bogus request.
+		if (parts.length !== 3 || segment !== '_git' || !projectName || !repoName) {
+			throw new Error(`Invalid Azure repository descriptor '${repo}'; expected '{project}/_git/{repoName}'.`);
+		}
+		return this.request<AzureRepositoryWithMetadata>(
+			provider,
+			token,
+			baseUrl,
+			`${owner}/${projectName}/_apis/git/repositories/${repoName}?api-version=7.1`,
+			{ method: 'GET' },
+			scope,
+			cancellation,
+		);
+	}
+
 	private async request<T>(
 		provider: Provider,
 		token: TokenWithInfo,
@@ -583,7 +713,7 @@ export class AzureDevOpsApi implements Disposable {
 		scope: ScopedLogger | undefined,
 		cancellation?: AbortSignal | undefined,
 	): Promise<T | undefined> {
-		const { accessToken, ...tokenInfo } = token;
+		const { accessToken } = token;
 		const url = baseUrl ? `${baseUrl}/${route}` : route;
 
 		let rsp: Response;
@@ -593,8 +723,8 @@ export class AzureDevOpsApi implements Disposable {
 			try {
 				if (cancellation?.aborted) throw new CancellationError();
 
-				rsp = await this.ctx.http.wrapForForcedInsecureSSL(provider.getIgnoreSSLErrors(), () =>
-					this.ctx.http.fetch(url, {
+				rsp = await this.config.wrapForForcedInsecureSSL(provider.getIgnoreSSLErrors(), () =>
+					this.config.fetch(url, {
 						headers: {
 							Authorization: `Basic ${base64(`PAT:${accessToken}`)}`,
 							'Content-Type': 'application/json',
@@ -608,15 +738,16 @@ export class AzureDevOpsApi implements Disposable {
 					return (await rsp.json()) as T;
 				}
 
-				throw new ProviderFetchError('AzureDevOps', rsp);
+				// Reads the body so the 403 branch below can tell a throttled request from a permission failure.
+				throw await ProviderFetchError.fromResponse('AzureDevOps', rsp);
 			} finally {
 				sw?.stop();
 			}
 		} catch (ex) {
 			if (ex instanceof ProviderFetchError || ex.name === 'AbortError') {
-				this.handleRequestError(provider, tokenInfo, ex, scope);
+				this.handleRequestError(provider, token, ex, scope);
 			} else if (Logger.isDebugging) {
-				this.ctx.hooks?.ui?.onError?.(`AzureDevOps request failed: ${ex.message}`);
+				this.config.onError?.(`AzureDevOps request failed: ${ex.message}`);
 			}
 
 			throw ex;
@@ -625,12 +756,13 @@ export class AzureDevOpsApi implements Disposable {
 
 	private handleRequestError(
 		provider: Provider | undefined,
-		tokenInfo: TokenInfo,
+		token: TokenWithInfo,
 		ex: ProviderFetchError | (Error & { name: 'AbortError' }),
 		scope: ScopedLogger | undefined,
 	): void {
 		if (ex.name === 'AbortError' || !(ex instanceof ProviderFetchError)) throw new CancellationError(ex);
 
+		const { accessToken, ...tokenInfo } = token;
 		switch (ex.status) {
 			case 404: // Not found
 			case 410: // Gone
@@ -638,27 +770,21 @@ export class AzureDevOpsApi implements Disposable {
 				throw new RequestNotFoundError(ex);
 			case 401: // Unauthorized
 				throw new AuthenticationError(tokenInfo, AuthenticationErrorReason.Unauthorized, ex);
+			case 429: // Too Many Requests
+				throw toRateLimitError(ex, accessToken);
 			case 403: // Forbidden
-				// TODO: Learn the Azure API docs and put it in order:
-				// 	if (ex.message.includes('rate limit')) {
-				// 		let resetAt: number | undefined;
-
-				// 		const reset = ex.response?.headers?.get('x-ratelimit-reset');
-				// 		if (reset != null) {
-				// 			resetAt = parseInt(reset, 10);
-				// 			if (Number.isNaN(resetAt)) {
-				// 				resetAt = undefined;
-				// 			}
-				// 		}
-
-				// 		throw new RequestRateLimitError(ex, token, resetAt);
-				// 	}
+				// Azure returns 403 for both a permission failure and a throttled request ("Request was blocked
+				// due to exceeding usage of resource 'RateLimit'"), so the message is the discriminant. Reporting
+				// a throttle as `auth` would prompt the user to re-authenticate a healthy connection instead of
+				// retrying (see `isRateLimitResponse`).
+				if (isRateLimitResponse(ex)) throw toRateLimitError(ex, accessToken);
+
 				throw new AuthenticationError(tokenInfo, AuthenticationErrorReason.Forbidden, ex);
 			case 500: // Internal Server Error
 				scope?.error(ex);
 				if (ex.response != null) {
 					provider?.trackRequestException();
-					this.ctx.hooks?.ui?.onRequestFailed?.(
+					this.config.onRequestFailed?.(
 						`${provider?.name ?? 'AzureDevOps'} failed to respond and might be experiencing issues.${
 							provider == null || provider.id === 'azure'
 								? ' Please visit the [AzureDevOps status page](https://status.dev.azure.com) for more information.'
@@ -683,9 +809,14 @@ export class AzureDevOpsApi implements Disposable {
 
 		scope?.error(ex);
 		if (Logger.isDebugging) {
-			this.ctx.hooks?.ui?.onError?.(
+			this.config.onError?.(
 				`AzureDevOps request failed: ${(ex.response as any)?.errors?.[0]?.message ?? ex.message}`,
 			);
 		}
 	}
 }
+
+/** Wires an {@link AzureDevOpsApi} from the full runtime context, mapping `ctx` down to the narrow config. */
+export function createAzureDevOpsApi(ctx: IntegrationServiceContext): AzureDevOpsApi {
+	return new AzureDevOpsApi(baseProviderApiConfig(ctx));
+}