@gitkraken/core-gitlens 0.4.0 → 0.4.101

package/src/plus/integrations/errors.ts

@@ -7,6 +7,22 @@ export {
 	RequestRateLimitError,
 } from '../../git/errors.js';
 
+import { RequestRateLimitError } from '../../git/errors.js';
+
+/**
+ * Thrown by a provider read when it can't produce a result for a reason that is NOT "the account is empty":
+ * a prerequisite is missing (e.g. Trello has no app key) or a required scope can't be resolved (e.g. the
+ * Linear viewer id, needed to scope "my issues"). Returning an empty/undefined result in these cases would be
+ * indistinguishable from a genuinely empty account; throwing this lets the result cores recover it into an
+ * `{ error }` the facade surfaces as a warning + `fetchFailed`.
+ */
+export class IntegrationReadUnavailableError extends Error {
+	constructor(provider: string, reason: string) {
+		super(`${provider} read unavailable: ${reason}`);
+		Error.captureStackTrace?.(this, new.target);
+	}
+}
+
 /**
  * Thrown by integration provider HTTP clients when an upstream request fails.
  */
@@ -19,6 +35,19 @@ export class ProviderFetchError extends Error {
 		return this.response.statusText;
 	}
 
+	/**
+	 * Builds the error with the upstream body folded into the message, for clients that hold a `Response` whose
+	 * body has not been read (i.e. every non-`ok` path). Use this rather than the constructor whenever the body is
+	 * still available: the status line alone cannot distinguish a throttled request from a permission failure on
+	 * the statuses hosts overload (see {@link isRateLimitResponse}), and only the body says which one it is.
+	 *
+	 * Never throws: the body is best-effort, so an unreadable, empty, or already-consumed one simply yields the
+	 * status-line-only message the constructor would have produced.
+	 */
+	static async fromResponse(provider: string, response: Response): Promise<ProviderFetchError> {
+		return new ProviderFetchError(provider, response, await readErrorBodyMessage(response));
+	}
+
 	constructor(
 		provider: string,
 		public readonly response: Response,
@@ -33,3 +62,127 @@ export class ProviderFetchError extends Error {
 		Error.captureStackTrace?.(this, new.target);
 	}
 }
+
+/** Cap on the body text folded into an error message, so an HTML error page can't become the message. */
+const maxErrorBodyLength = 500;
+
+/**
+ * Best-effort human-readable message from an error response body, in the `errors` shape the
+ * {@link ProviderFetchError} constructor takes. Tolerant by design — every host in use words its errors
+ * differently and some do not send JSON at all:
+ *   - Azure DevOps — `{ message: "TF400733: ..." }`
+ *   - Bitbucket    — `{ error: { message: "..." } }`, and bare text for a throttled request
+ *   - GitLab       — `{ message: "..." }` or `{ error: "..." }`
+ * Anything unrecognized falls back to the raw text, which is what the substring check wants anyway.
+ */
+async function readErrorBodyMessage(response: Response): Promise<{ message: string }[] | undefined> {
+	let text;
+	try {
+		// `bodyUsed` is not a guarantee (a stream can fail mid-read), hence the catch — but it avoids the throw
+		// entirely on the common path where something upstream already consumed the body.
+		if (response.bodyUsed) return undefined;
+
+		text = (await response.text())?.trim();
+	} catch {
+		return undefined;
+	}
+	if (!text) return undefined;
+
+	let message: string | undefined;
+	try {
+		const body: unknown = JSON.parse(text);
+		if (body != null && typeof body === 'object') {
+			const { message: m, error } = body as { message?: unknown; error?: unknown };
+			if (typeof m === 'string') {
+				message = m;
+			} else if (typeof error === 'string') {
+				message = error;
+			} else if (error != null && typeof error === 'object') {
+				// Some hosts nest it as `{ error: { message } }`; narrow the same way as the outer object.
+				const nested = (error as { message?: unknown }).message;
+				if (typeof nested === 'string') {
+					message = nested;
+				}
+			}
+		}
+	} catch {
+		// Not JSON — Bitbucket sends bare text for a throttled request, and any host can send an HTML error page.
+	}
+
+	message = (message ?? text).trim();
+	return message ? [{ message: message.slice(0, maxErrorBodyLength) }] : undefined;
+}
+
+/**
+ * Whether a provider's error response denotes a rate limit rather than a permission failure. Kept here, in one
+ * place, because the distinction is consequential: a rate limit is retryable, while a permission failure is
+ * surfaced as `auth` and drives a reconnect prompt — misclassifying one as the other asks the user to
+ * re-authenticate a perfectly healthy connection.
+ *
+ * Which status a throttled request arrives on varies by host, which is why this takes both:
+ *   - Azure DevOps and Bitbucket Cloud document 429 (learn.microsoft.com .../integrate/concepts/rate-limits).
+ *   - GitHub documents "a `403` or `429` response" for both its primary and secondary limits
+ *     (docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api).
+ *   - GitLab uses 403 for some throttles.
+ * So 429 alone is decisive, and on 403 the message decides.
+ *
+ * NOTE the message must actually carry the host's body for the 403 path to work — see
+ * {@link ProviderFetchError.fromResponse}. A `ProviderFetchError` built from the status line alone reads
+ * "(403) Forbidden." and can never match, which is what made this check dead code on the direct-fetch clients.
+ */
+export function isRateLimitResponse(ex: { status: number; message?: string }): boolean {
+	// Matches the phrasing hosts actually use: GitHub/Bitbucket "API rate limit exceeded", GitLab "rate limit
+	// exceeded", Azure "Request was blocked due to exceeding usage of resource 'RateLimit'" / "TF400733: The
+	// request has been canceled: Request was blocked due to exceeding usage".
+	if (ex.status === 429) return true;
+
+	const message = ex.message?.toLowerCase();
+	return message != null && (message.includes('rate limit') || message.includes('ratelimit'));
+}
+
+/**
+ * A response's headers as either a `fetch` `Headers` instance or the plain object an SDK error carries. Read via
+ * duck-typing on `get` rather than `instanceof Headers`, so this works in both the Node and webworker builds
+ * without depending on the global being present.
+ */
+type ResponseHeaders = Pick<Headers, 'get'> | Record<string, unknown>;
+
+/**
+ * Builds a {@link RequestRateLimitError} from a provider error response, reading the reset epoch from the
+ * standard `x-ratelimit-reset` header when present. Accepts both header shapes in use: the `fetch` `Headers`
+ * instance the direct clients get, and the plain object the SDK attaches to its errors.
+ */
+export function toRateLimitError(
+	ex: Error & { response?: { headers?: ResponseHeaders } },
+	token: string | undefined,
+): RequestRateLimitError {
+	const headers = ex.response?.headers as { get?: unknown } & Record<string, unknown>;
+	const raw =
+		headers == null
+			? undefined
+			: typeof headers.get === 'function'
+				? (headers.get as (name: string) => string | null)('x-ratelimit-reset')
+				: headers['x-ratelimit-reset'];
+
+	// Only a header that actually came back as a string/number can be a reset epoch; anything else (a nested SDK
+	// object, an array of values) would stringify to garbage and parse to NaN anyway.
+	let resetAt: number | undefined;
+	if (typeof raw === 'string' || typeof raw === 'number') {
+		resetAt = parseInt(String(raw), 10);
+		if (Number.isNaN(resetAt)) {
+			resetAt = undefined;
+		}
+	}
+
+	return new RequestRateLimitError(ex, token, resetAt);
+}
+
+/**
+ * Normalizes a caught `unknown` into an `Error`. Result cores type their failure channel as `error: Error`,
+ * but a `catch` binding is `unknown` and a provider (or a third-party SDK) can throw a non-Error value;
+ * returning it raw would leak a non-Error through the public result surface and break downstream `instanceof`
+ * classification. Passes an existing `Error` through unchanged and wraps anything else with `String(ex)`.
+ */
+export function toError(ex: unknown): Error {
+	return ex instanceof Error ? ex : new Error(String(ex));
+}

package/src/plus/integrations/index.ts

@@ -1,22 +1,120 @@
 // Public facade for `@gitkraken/core-gitlens/plus/integrations`.
 //
 // External consumers should import from this entry point only, not from the
-// package's internal subpaths. The internal classes (IntegrationService,
+// package's internal subpaths, with one exception: the lightweight, token-scoped
+// read API is a supported public subpath (`./lite.js`). It's kept out of this
+// facade on purpose so importing the session-managed manager doesn't eagerly pull
+// in every provider API client. The internal classes (IntegrationService,
 // IntegrationAuthenticationService, etc.) are not part of the public API and
 // may be refactored without semver bumps.
 
-import { CloudIntegrationService } from './authentication/cloudIntegrationService.js';
-import { ConfiguredIntegrationService } from './authentication/configuredIntegrationService.js';
-import { IntegrationAuthenticationService } from './authentication/integrationAuthenticationService.js';
-import type { IntegrationServiceContext } from './context.js';
-import { IntegrationService } from './integrationService.js';
+import type { Account } from '../../git/models/author.js';
+import { CacheController } from '../../utils/promiseCache.js';
+import type { IntegrationIds } from './constants.js';
+import type {
+	AccountProvider,
+	ConfigProvider,
+	HttpProvider,
+	IntegrationCacheProvider,
+	IntegrationServiceHooks,
+	IntegrationStorageProvider,
+	RepositoriesProvider,
+} from './context.js';
+import { createIntegrationService } from './integrationService.js';
+import type { IntegrationManager } from './manager.js';
+
+/** A cached provider value, which may still be resolving. */
+export type IntegrationManagerCacheResult<T> = Promise<T | undefined> | T | undefined;
+
+/** Produces an account value on a cache miss. */
+export type IntegrationManagerCacheLoader<T> = (cacheable: CacheController) => {
+	value: IntegrationManagerCacheResult<T>;
+	expiresAt?: number;
+};
+
+/** Stable integration identity supplied to the consumer-owned account cache. */
+export interface IntegrationAccountCacheDescriptor {
+	readonly id: IntegrationIds;
+	readonly domain?: string;
+}
+
+/** Cache controls attached to a provider account lookup. */
+export interface IntegrationManagerCacheOptions {
+	readonly connectionId?: string;
+	readonly etag?: string;
+	readonly expiryOverride?: boolean | number;
+	readonly expireOnError?: boolean;
+}
+
+/**
+ * Optional consumer-owned cache for values reused by the public manager facade.
+ *
+ * The manager only needs cross-call caching for provider identity lookups. Other caches used by the GitLens
+ * extension host are implementation details and deliberately stay out of this contract.
+ */
+export interface IntegrationManagerCacheProvider {
+	getCurrentAccount(
+		integration: IntegrationAccountCacheDescriptor,
+		cacheable: IntegrationManagerCacheLoader<Account>,
+		options?: IntegrationManagerCacheOptions,
+	): IntegrationManagerCacheResult<Account>;
+}
+
+function loadUncached<T>(loader: IntegrationManagerCacheLoader<T>): IntegrationManagerCacheResult<T> {
+	return loader(new CacheController()).value;
+}
+
+const uncachedIntegrationCacheProvider: IntegrationCacheProvider = {
+	getRepositoryMetadata: (_repo, _integration, loader) => loadUncached(loader),
+	getRepositoryDefaultBranch: (_repo, _integration, loader) => loadUncached(loader),
+	getPullRequestForSha: (_sha, _repo, _integration, loader) => loadUncached(loader),
+	getPullRequestForBranch: (_branch, _repo, _integration, loader) => loadUncached(loader),
+	getPullRequest: (_id, _resource, _integration, loader) => loadUncached(loader),
+	getIssueOrPullRequest: (_id, _type, _resource, _integration, loader) => loadUncached(loader),
+	getIssue: (_id, _resource, _integration, loader) => loadUncached(loader),
+	getCurrentAccount: (_integration, loader) => loadUncached(loader),
+};
+
+function toIntegrationCacheProvider(cache: IntegrationManagerCacheProvider | undefined): IntegrationCacheProvider {
+	if (cache == null) return uncachedIntegrationCacheProvider;
+
+	return {
+		...uncachedIntegrationCacheProvider,
+		getCurrentAccount: (integration, loader, options) =>
+			cache.getCurrentAccount({ id: integration.id, domain: integration.domain }, loader, options),
+	};
+}
 
 /**
- * The public manager — what consumers get back from
- * {@link createIntegrationManager}. Identical shape to {@link IntegrationService}
- * for now (we may narrow this surface in a future major).
+ * Consumer-facing runtime for {@link createIntegrationManager}.
+ *
+ * External consumers may omit `cache`; reads then execute their loaders directly without cross-call caching.
+ * The extension host's broader integration context remains private to the implementation.
  */
-export type IntegrationManager = IntegrationService;
+export interface IntegrationManagerContext {
+	readonly storage: IntegrationStorageProvider;
+	readonly account: AccountProvider;
+	readonly config: ConfigProvider;
+	readonly http: HttpProvider;
+	readonly cache?: IntegrationManagerCacheProvider;
+	readonly repositories: RepositoriesProvider;
+	readonly hooks?: IntegrationServiceHooks;
+}
+
+export type {
+	ClosedPullRequestSweepOptions,
+	IntegrationManager,
+	ListOrgsOptions,
+	ListProjectsOptions,
+	// Every option shape a caller has to BUILD is exported, not just the ones the manager returns:
+	// `manager.js` is not a public subpath, so a type omitted here can't be named by a consumer at all
+	// (`broadenIssues`' `orgs` needed `ProviderBroadenOrg` and had to be re-declared downstream).
+	ProviderBroadenOrg,
+	ProviderRepositoriesInput,
+	ProviderRepositoryInput,
+	ProviderSweepTarget,
+	PullRequestSweepOptions,
+} from './manager.js';
 
 /**
  * Construct an `@gitkraken/core-gitlens/plus/integrations` manager bound to the supplied runtime.
@@ -30,61 +128,27 @@ export type IntegrationManager = IntegrationService;
  * containing scope) to release every cached integration plus the runtime's
  * own VS Code subscriptions.
  */
-export function createIntegrationManager(ctx: IntegrationServiceContext): IntegrationManager {
-	const configured = new ConfiguredIntegrationService(ctx);
-	// The cloud token-exchange client is a pure package service (needs only `ctx`); construct it here
-	// rather than round-tripping through a host hook.
-	const cloud = new CloudIntegrationService(ctx);
-	// Cloud auth providers need to (re)initiate the connect flow that lives on the service, but the
-	// service is constructed after the auth service (it depends on it). Break the cycle here at the
-	// composition root with a lazy, readonly accessor — preserving constructor injection while
-	// keeping the flow in-package (no host round-trip).
-	let service: IntegrationService;
-	const auth = new IntegrationAuthenticationService(configured, ctx, () => service, cloud);
-	service = new IntegrationService(auth, configured, ctx);
-	// One-time cleanup of storage left behind by integration ids retired in the cloud-only refactor (the
-	// local self-managed `github-enterprise`/`gitlab-self-hosted` providers). Best-effort and guarded so it
-	// runs once; a no-op for consumers that never stored those ids.
-	void purgeRetiredIntegrationStorage(ctx, configured);
-	return service;
-}
-
-const retiredIntegrationsStorageKey = 'integrations:migrated:cloudOnly';
-async function purgeRetiredIntegrationStorage(
-	ctx: IntegrationServiceContext,
-	configured: ConfiguredIntegrationService,
-): Promise<void> {
-	if (ctx.storage.get<boolean>(retiredIntegrationsStorageKey)) return;
-
-	try {
-		await configured.purgeStoredConfiguration(['github-enterprise', 'gitlab-self-hosted']);
-		// Only mark the migration done once the purge fully succeeds. A partial/failed purge stays
-		// un-flagged so it retries (idempotently) on the next startup, rather than orphaning the
-		// retired-id config/secrets forever.
-		await ctx.storage.store(retiredIntegrationsStorageKey, true);
-	} catch {
-		// Best-effort cleanup: swallow so the failure doesn't reject the fire-and-forget caller; the
-		// unset flag guarantees a retry next startup.
-	}
+export function createIntegrationManager(ctx: IntegrationManagerContext): IntegrationManager {
+	return createIntegrationService({
+		...ctx,
+		cache: toIntegrationCacheProvider(ctx.cache),
+	});
 }
 
 // Re-exports for the public API surface.
 export type {
 	AccountProvider,
 	AuthenticationSessionsChangeEvent,
-	IntegrationCacheProvider,
 	ConfigChangeEvent,
 	ConfigProvider,
 	RepositoriesProvider,
 	HttpProvider,
-	IntegrationServiceContext,
+	IntegrationsRemoteConfig,
 	IntegrationServiceHooks,
 	IntegrationStorageProvider,
 } from './context.js';
-export type { ApiClients } from './providers/apiClients.js';
-export type { Source } from './telemetry.js';
+export type { Source, Sources } from './telemetry.js';
 export type { IntegrationIds, SupportedCloudIntegrationIds } from './constants.js';
-export type { ConnectionStateChangeEvent, IntegrationConnectionChangeEvent } from './integrationService.js';
 export type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
 
 // Authentication contract — what `IntegrationServiceHooks.createAuthenticationProvider`
@@ -99,8 +163,17 @@ export type {
 export type {
 	AuthenticationSessionLike,
 	CloudIntegrationAuthType,
+	CloudIntegrationConnection,
+	CloudIntegrationType,
+	ConfiguredIntegrationDescriptor,
 	ProviderAuthenticationSession,
 } from './authentication/models.js';
+// Provider-id mapping helpers for consumers bridging their own provider ids to `IntegrationIds`
+// (e.g. mapping multi-account connections from `getConfigured` back to a provider) and vice versa.
+export { toCloudIntegrationType, toIntegrationId } from './authentication/models.js';
+// Domain normalization is part of connection selection and repository resolution; consumers should use the
+// same implementation rather than importing an internal utility subpath or maintaining a divergent copy.
+export { areDomainsOnSameHost, hostFromDomain } from './utils/domain.utils.js';
 
 // Convenience: wrap a static access token (env var, CLI flag, secret manager)
 // as an `IntegrationAuthenticationProvider`. For OAuth/refresh flows, implement
@@ -117,3 +190,27 @@ export {
 	isIntegrationId,
 	isSupportedCloudIntegrationId,
 } from './constants.js';
+
+// Neutral pagination + warning result types the Kepler ProviderBackend adapter maps to its own DTOs.
+// These carry no `@gitkraken/provider-apis` types, so consumers depend only on `@gitkraken/core-gitlens`.
+export type {
+	ConnectionStateChangeEvent,
+	ProviderBroadenResult,
+	ProviderPagedResult,
+	ProviderPageInfo,
+	ProviderResult,
+	ProviderSweepResult,
+	ProviderWarning,
+	ProviderWarningKind,
+	ProviderOrganization,
+	ProviderRepositoryShape,
+	RepositoryIdentity,
+	RepositoryResolution,
+	RepositoryResolutionStatus,
+	ResolveRepositoryResult,
+} from './results.js';
+// Runtime enums — re-exported as values (not `export type`) so consumers can read their members.
+export { IssueFilter, PullRequestFilter } from './providerFilters.js';
+// Cross-provider PR/issue state filters (string unions in the git models).
+export type { PullRequestStateFilter } from '../../git/models/pullRequest.js';
+export type { IssueStateFilter } from '../../git/models/issue.js';