@gitkraken/core-gitlens 0.4.0 → 0.4.101

package/src/plus/integrations/reads/sweeps.ts

@@ -0,0 +1,185 @@
+import type { PullRequestShape } from '../../../git/models/pullRequest.js';
+import { mapBounded } from '../../../utils/promise.js';
+import type { IntegrationIds } from '../constants.js';
+import { providerFanOutConcurrency } from '../constants.js';
+import type { ClosedPullRequestSweepOptions, PullRequestSweepOptions } from '../manager.js';
+import { fromProviderPullRequest } from '../providers/models.js';
+import type { ProviderSweepResult, ProviderWarning } from '../results.js';
+import { appendDedupedWarning } from '../results.js';
+import { isGitHostIntegration, isIssuesHostIntegrationId } from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { drainPullRequests, getCurrentAccountId, resolvePullRequestSweepTargets } from './drains.js';
+import { resolveAccountWidePullRequestFilters, resolvePullRequestFilters } from './filters.js';
+import {
+	gitHostOnlySurfaceWarning,
+	noConnectionWarning,
+	unsupportedAccountWidePullRequestFiltersWarning,
+	unsupportedFiltersWarning,
+} from './warnings.js';
+
+/**
+ * The all-pages pull request reads: one drain per provider target, aggregated into a single sweep result.
+ *
+ * A sweep exposes no continuation of its own — it drains everything it can reach — so its whole contract lives in
+ * the completeness signals it returns: `page.allPages` asserts every page of every target was read,
+ * `page.truncated` says pages remain unread, and `failedProviderIds`/`incompleteProviderIds` separate a provider
+ * that produced nothing from one that produced a slice with a gap. That split is why the aggregation below can't
+ * be collapsed into the generic fan-out merge the hierarchy reads use.
+ */
+
+/** One provider target's drained slice, before the cross-provider aggregation. */
+interface SweepSlice {
+	items: PullRequestShape[];
+	warnings: ProviderWarning[];
+	fetchFailed: boolean;
+	truncated: boolean;
+	providerId: IntegrationIds;
+	failedProvider: boolean;
+}
+
+export async function sweepPullRequests(
+	ctx: ProviderReadContext,
+	options?: PullRequestSweepOptions,
+): Promise<ProviderSweepResult<PullRequestShape>> {
+	const { targets, attributeUnavailableProviders } = resolvePullRequestSweepTargets(options);
+	const maxPages = options?.maxPages ?? 100;
+	const repos = options?.repos ?? [];
+
+	const results = await mapBounded(targets, providerFanOutConcurrency, async target => {
+		const { providerId: id, connectionId, domain: requestedDomain } = target;
+		/** A target that never reached a drain: the provider itself failed, so its slice is empty and attributed. */
+		const rejectedTarget = (warnings: ProviderWarning[]): SweepSlice => ({
+			items: [],
+			warnings: warnings,
+			fetchFailed: true,
+			truncated: false,
+			providerId: id,
+			failedProvider: true,
+		});
+
+		if (isIssuesHostIntegrationId(id)) {
+			return rejectedTarget([
+				gitHostOnlySurfaceWarning(id, requestedDomain, connectionId, 'pull request sweeps'),
+			]);
+		}
+
+		const integration = await ctx.getIntegrationForRead(id, connectionId, requestedDomain);
+		if (integration == null) {
+			// A requested connection that can't be resolved is a broken connection — surface it as a
+			// warning + fetchFailed rather than dropping the provider's slice silently.
+			const early = ctx.earlyReturnConnectionWarnings(id, connectionId, requestedDomain);
+			if (early.warnings.length === 0 && !attributeUnavailableProviders) return undefined;
+
+			return rejectedTarget(
+				early.warnings.length !== 0 ? early.warnings : [noConnectionWarning(id, requestedDomain, connectionId)],
+			);
+		}
+		if (!isGitHostIntegration(integration)) {
+			return rejectedTarget([
+				gitHostOnlySurfaceWarning(id, requestedDomain, connectionId, 'pull request sweeps'),
+			]);
+		}
+
+		await ctx.forceRefreshIfRequested(integration, options?.forceSync, connectionId);
+
+		const domain = ctx.domainForRead(integration, id, connectionId, requestedDomain);
+		const accountWide = repos.length === 0;
+		const requestedFilters = target.filters ?? options?.filters;
+		const resolved = accountWide
+			? resolveAccountWidePullRequestFilters(id, requestedFilters)
+			: resolvePullRequestFilters(id, requestedFilters);
+		if (resolved.unsupported) {
+			return rejectedTarget([
+				accountWide
+					? unsupportedAccountWidePullRequestFiltersWarning(id, domain, connectionId, requestedFilters ?? [])
+					: unsupportedFiltersWarning(id, domain, connectionId),
+			]);
+		}
+
+		const drain = await drainPullRequests(
+			integration,
+			id,
+			domain,
+			repos,
+			options?.states,
+			resolved.filters,
+			accountWide ? (options?.includeReviewRequested ?? false) : false,
+			connectionId,
+			maxPages,
+			attributeUnavailableProviders,
+		);
+		const currentAccountId = drain.items.some(pr => pr.author != null)
+			? await getCurrentAccountId(integration, connectionId)
+			: undefined;
+		// Normalize the raw provider-apis PRs to the GitLens-owned shape here, where the per-provider
+		// `integration` (the mapper's provider reference) is in scope; the aggregation below only sees drains.
+		return {
+			...drain,
+			items: drain.items.map(pr =>
+				fromProviderPullRequest(pr, integration, { currentAccountId: currentAccountId }),
+			),
+			providerId: id,
+		};
+	});
+
+	const items: PullRequestShape[] = [];
+	const warnings: ProviderWarning[] = [];
+	const failedProviderIds = new Set<IntegrationIds>();
+	const incompleteProviderIds = new Set<IntegrationIds>();
+	let fetchFailed = false;
+	let truncated = false;
+	for (const drain of results) {
+		if (drain == null) {
+			continue;
+		}
+
+		items.push(...drain.items);
+		for (const w of drain.warnings) {
+			appendDedupedWarning(warnings, w);
+		}
+		if (drain.fetchFailed) {
+			fetchFailed = true;
+		}
+		if (drain.failedProvider) {
+			failedProviderIds.add(drain.providerId);
+		} else if (drain.fetchFailed || drain.truncated) {
+			incompleteProviderIds.add(drain.providerId);
+		}
+		if (drain.truncated) {
+			truncated = true;
+		}
+	}
+
+	return {
+		items: items,
+		warnings: warnings,
+		// `allPages` asserts completeness — it must be false when any provider truncated (a single-page
+		// account-wide read that couldn't confirm it drained everything) OR a drain aborted on a read
+		// failure (its slice is incomplete). Either way the sweep did not read every page.
+		page: {
+			currentPage: 1,
+			itemsPerPage: items.length,
+			allPages: !truncated && !fetchFailed,
+			truncated: truncated || undefined,
+		},
+		// A sweep drains every page itself and exposes no cursor to resume — so `hasMore` must be false even
+		// when the read was incomplete. Terminal incompleteness is expressed through `page.truncated` +
+		// `allPages: false` + warnings; setting `hasMore: true` here would make a consumer that drains while
+		// `hasMore` re-run the identical sweep forever with no cursor to advance.
+		hasMore: false,
+		fetchFailed: fetchFailed || undefined,
+		failedProviderIds: [...failedProviderIds],
+		incompleteProviderIds: [...incompleteProviderIds],
+	};
+}
+
+/**
+ * Closed/merged counterpart of {@link sweepPullRequests}, feeding Kepler's Kanban "done" column. Applies
+ * the native cross-provider state filter (`Closed` + `Merged`) so it works beyond GitHub.
+ */
+export function sweepClosedPullRequests(
+	ctx: ProviderReadContext,
+	options?: ClosedPullRequestSweepOptions,
+): Promise<ProviderSweepResult<PullRequestShape>> {
+	return sweepPullRequests(ctx, { ...options, states: ['closed', 'merged'] });
+}

package/src/plus/integrations/reads/warnings.ts

@@ -0,0 +1,170 @@
+import type { IntegrationIds } from '../constants.js';
+import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import { providersMetadata } from '../providers/models.js';
+import type { ProviderWarning } from '../results.js';
+
+/**
+ * The warnings the provider facade raises on its OWN terms, as opposed to the ones derived from a caught
+ * provider error ({@link toProviderWarning}) or from SDK collection metadata (`collectionMetadata.ts`).
+ *
+ * These are pure message builders, kept together and out of the service so a read method reads as the decision
+ * it makes ("this surface doesn't apply, refuse it") rather than as the wording of the refusal, and so the same
+ * refusal can't be phrased two ways in two reads.
+ */
+
+/**
+ * The single builder for a provider-neutral, non-auth warning: an unsupported capability, a
+ * contradictory/inexpressible request, or a read that couldn't confirm completeness. Every `kind: 'other'`
+ * warning the facade emits goes through here (directly, or via one of the named builders below that pin a
+ * recurring message), so the discriminant is assigned in exactly one place.
+ *
+ * The kinds that carry a programmatic remedy — `auth`, `rate-limit`, `not-found`, `no-connection` — are derived
+ * from the caught error's type instead and never come from here; see `ProviderWarningKind` and
+ * {@link noConnectionWarning}.
+ */
+export function otherWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	message: string,
+): ProviderWarning {
+	return {
+		providerId: id,
+		domain: domain,
+		connectionId: connectionId,
+		message: message,
+		kind: 'other',
+		isAuth: false,
+	};
+}
+
+/**
+ * Builds a `no-connection` warning for a per-connection read that resolved neither a session nor an error: the
+ * requested `connectionId` no longer resolves (deleted, or its authentication is invalid). Consumers use this
+ * to tell a truly empty account apart from a broken connection.
+ */
+export function noConnectionWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId?: string,
+): ProviderWarning {
+	return {
+		providerId: id,
+		domain: domain,
+		connectionId: connectionId,
+		message:
+			connectionId != null
+				? `Connection '${connectionId}' for '${id}' could not be resolved (deleted or invalid authentication).`
+				: `No active connection for '${id}' could be resolved.`,
+		kind: 'no-connection',
+		isAuth: false,
+	};
+}
+
+/** Warning for an issue-tracker provider asked for a surface only a git host serves (repos, PRs, sweeps). */
+export function gitHostOnlySurfaceWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	surface: string,
+): ProviderWarning {
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`${surface} is not supported by '${id}'; use a git-host integration instead.`,
+	);
+}
+
+/** Warning for a git host asked for a surface only an issue tracker serves (resource → project issue reads). */
+export function issueTrackerOnlySurfaceWarning(
+	id: IntegrationIds,
+	connectionId: string | undefined,
+	surface: string,
+): ProviderWarning {
+	return otherWarning(
+		id,
+		undefined,
+		connectionId,
+		`${surface} is not supported by '${id}'; use an issue-tracker integration instead.`,
+	);
+}
+
+/**
+ * Builds a warning for a drain that stopped short of completeness (hit a page backstop, or a single-page read
+ * that couldn't confirm it drained everything). `truncated`/`allPages` already carry this on the result, but
+ * consumers that only inspect `warnings` would otherwise see no signal the read is partial.
+ */
+export function truncationWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	readKind: 'Pull request' | 'Issue' | 'Repository',
+): ProviderWarning {
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`${readKind} read for '${id}' was truncated (a page backstop was reached); results may be incomplete.`,
+	);
+}
+
+/** Warning for an account-wide issue read whose requested filters the provider can't express server-side. */
+export function unsupportedAccountWideIssueFiltersWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	filters: IssueFilter[],
+): ProviderWarning {
+	const supported = providersMetadata[id]?.supportedAccountWideIssueFilters ?? [];
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`The requested account-wide issue filters (${filters.join(', ')}) are not supported by '${id}'${supported.length ? ` (supported: ${supported.join(', ')})` : ''}; skipped to avoid returning a wider result than requested.`,
+	);
+}
+
+/** Warning for an account-wide PR read whose requested relationship union cannot be expressed exactly. */
+export function unsupportedAccountWidePullRequestFiltersWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	filters: PullRequestFilter[],
+): ProviderWarning {
+	const supported = providersMetadata[id]?.supportedAccountWidePullRequestFilters ?? [];
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`The requested account-wide pull request filters (${filters.join(', ')}) are not supported by '${id}'${supported.length ? ` (supported: ${supported.join(', ')})` : ''}; skipped to avoid returning a wider result than requested.`,
+	);
+}
+
+/** Warning for a repo-scoped PR read whose requested filters the provider supports none of. */
+export function unsupportedFiltersWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+): ProviderWarning {
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`The requested pull request filters are not supported by '${id}'; skipped to avoid returning unfiltered results.`,
+	);
+}
+
+/** Warning for a git host that doesn't expose issues on this surface (e.g. Bitbucket, deprecated in favor of Jira). */
+export function issuesUnsupportedWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+): ProviderWarning {
+	return otherWarning(
+		id,
+		domain,
+		connectionId,
+		`Issues are not supported by '${id}'; use a dedicated issue integration (e.g. Jira) instead.`,
+	);
+}

package/src/plus/integrations/results.ts

@@ -0,0 +1,275 @@
+import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
+import type { IntegrationIds } from './constants.js';
+
+export interface ConnectionStateChangeEvent {
+	key: string;
+	reason: 'connected' | 'disconnected';
+}
+
+/**
+ * A per-provider, per-connection warning surfaced alongside (partial) read results. Consumers use
+ * these to drive auth recovery, retry, or truncation messaging without the read itself throwing.
+ *
+ * `kind` is the programmatic discriminant (a rate-limit is retryable, a 404 is not, an auth failure
+ * needs re-connection); `isAuth` is retained as a convenience mirror of `kind === 'auth'`.
+ */
+export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-connection' | 'other';
+
+export interface ProviderWarning {
+	providerId: IntegrationIds;
+	/** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */
+	domain?: string;
+	/** The specific token/connection the read was pinned to, when a `connectionId` was supplied. */
+	connectionId?: string;
+	message: string;
+	kind: ProviderWarningKind;
+	/** Convenience mirror of `kind === 'auth'`. */
+	isAuth: boolean;
+}
+
+export interface ProviderPageInfo {
+	/**
+	 * The 1-based POSITION of the returned page. One convention across every paged read, page-number and
+	 * cursor paging alike, so a `getNextPageParam`-style consumer can key off it uniformly:
+	 * - the page number the provider itself reported, when it reports one (authoritative);
+	 * - else the position the caller addressed: the page encoded in a threaded page cursor, or the `page`
+	 *   supplied alongside an opaque cursor (1 when the caller supplied no `page`);
+	 * - else, for a read that can be advanced by page number, the requested `page` — the provider either
+	 *   honored it or the internal drain reached it (see the paging contract on `IntegrationManager`);
+	 * - else 1: a cursor-only read with no cursor threaded back ignores a requested page number and answers
+	 *   with its first page, so echoing the request would mislabel page 1 as page N.
+	 *
+	 * A page past the provider's terminal cursor still reports the requested `page` with empty `items` — an
+	 * empty page N, never page N-1 relabeled.
+	 *
+	 * Continue a cursor-paged read from `cursor`, NOT from `currentPage + 1`: a cursor-only host can't be
+	 * addressed by number, so this is a position label and not always a resumable request parameter.
+	 */
+	currentPage: number;
+	/**
+	 * The page size IN EFFECT, which is not always the one requested — it is whichever of these the read can
+	 * actually vouch for:
+	 * - the size the provider reported for the page it served (numbered-page hosts), else
+	 * - the `itemsPerPage` that was applied to the request (repo-scoped reads, which forward it), else
+	 * - `items.length`, for a read that takes no page size at all: the account-wide PR/issue reads, `listRepos`
+	 *   (cursor-only), and `listIssueTrackerIssuesPage`, whose `itemsPerPage` counts PROJECTS rather than issues.
+	 *
+	 * So it is a description of the page, not an echo of the request: don't derive a total from
+	 * `currentPage * itemsPerPage`, and don't read `items.length < itemsPerPage` as "last page" — `hasMore` /
+	 * `cursor` are the only continuation signals.
+	 */
+	itemsPerPage: number;
+	/**
+	 * A COMPLETENESS assertion, not a mode flag: `true` only when a sweep drained every page of every target
+	 * without truncating or failing (`!truncated && !fetchFailed`). Set exclusively by `sweepPullRequests` /
+	 * `sweepClosedPullRequests` and absent on every paged read, so `allPages !== true` does NOT by itself mean
+	 * "this was a single page".
+	 *
+	 * This is the signal to gate on before caching a sweep as authoritative: unlike `truncated` it is `false`
+	 * for BOTH kinds of incompleteness, so it can't be misread as a benign cap.
+	 */
+	allPages?: boolean;
+	/**
+	 * True when the read stopped before it could confirm it had everything. Deliberately does NOT distinguish
+	 * WHY, and a consumer must not assume it means a provider ceiling — a sweep sets it from three different
+	 * origins:
+	 * - a provider-side ceiling or per-scope backstop propagated from below (e.g. GitHub Search's 1000-result
+	 *   cap): the missing items are NOT reachable, so this really is "complete to the provider's limit";
+	 * - the sweep's OWN `maxPages` cap (default 100) with a usable cursor still in hand: the missing items ARE
+	 *   reachable and were simply not fetched — raise `maxPages` to get them;
+	 * - the provider reporting another page but handing back no usable cursor: not reachable.
+	 *
+	 * Only the second is recoverable, and a sweep exposes no continuation cursor, so treating a truncated sweep
+	 * as a complete set silently drops reachable data in that case. Prefer `allPages` for the cache decision.
+	 */
+	truncated?: boolean;
+}
+
+export interface ProviderResult<T> {
+	items: T[];
+	warnings: ProviderWarning[];
+	/**
+	 * True when `items` is incomplete — distinguishes a failed or truncated flat read from a genuinely empty
+	 * result. Paged results additionally use `page.truncated` when a completed page could not confirm it
+	 * drained everything.
+	 */
+	fetchFailed?: boolean;
+}
+
+export interface ProviderPagedResult<T> extends ProviderResult<T> {
+	page: ProviderPageInfo;
+	hasMore: boolean;
+	/**
+	 * Opaque cursor for cursor-based paging (GraphQL, per-repo/per-project cursors, etc.). For hosts that
+	 * require the previous page's cursor, consumers should pass this value back to the next `cursor` option.
+	 * A retry-only cursor may remain when `hasMore` is false: `hasMore` means automatic forward progress,
+	 * while explicitly reusing such a cursor retries failed work without creating an infinite paging loop.
+	 */
+	cursor?: string;
+}
+
+export interface ProviderSweepResult<T> extends ProviderResult<T> {
+	page: ProviderPageInfo;
+	hasMore: boolean;
+	/**
+	 * Providers whose top-level read failed before returning any usable page. Partial per-scope failures stay
+	 * represented by `warnings` + `fetchFailed` and are intentionally excluded.
+	 */
+	failedProviderIds: IntegrationIds[];
+	/**
+	 * Providers whose read started successfully but could not produce an authoritative complete slice (for
+	 * example, a later page failed, collection metadata reported a partial scope, or a paging backstop was hit).
+	 * Kept separate from
+	 * `failedProviderIds` so consumers can accept healthy sibling providers while preserving an older snapshot
+	 * for a provider whose returned slice has a gap.
+	 */
+	incompleteProviderIds: IntegrationIds[];
+}
+
+export interface ProviderBroadenResult<T> extends ProviderPagedResult<T> {
+	broadenedProviderIds: IntegrationIds[];
+	/** Providers for which no requested org produced a usable issue result. */
+	failedProviderIds: IntegrationIds[];
+	/** Providers with both a usable org result and at least one failed or truncated org slice. */
+	incompleteProviderIds: IntegrationIds[];
+	fanOutCount: number;
+}
+
+export type RepositoryResolutionStatus =
+	| 'resolved'
+	| 'not-found'
+	| 'unauthorized'
+	| 'unsupported-provider'
+	| 'invalid-remote-url'
+	| 'host-mismatch'
+	| 'undetermined';
+
+export interface RepositoryIdentity {
+	providerId: IntegrationIds;
+	domain: string;
+	/** The provider's canonical owner/namespace (follows renames), falling back to the parsed remote when omitted. */
+	owner: string;
+	/** The provider's canonical repo name (follows renames), falling back to the parsed remote when omitted. */
+	name: string;
+	project?: string;
+	/** The original input remote URL, so the caller can key the resolution back to the remote it asked about. */
+	remoteUrl: string;
+	/**
+	 * True when the provider's canonical owner/name differ from what the input remote URL carried — i.e. the
+	 * repo was renamed/moved host-side and the local remote is stale. Case-insensitive, mirroring gkcli's
+	 * `EqualFold` compare so hosts that echo the input casing (e.g. Bitbucket Server/Azure) aren't flagged.
+	 */
+	renamed: boolean;
+}
+
+export interface RepositoryResolution {
+	status: RepositoryResolutionStatus;
+	identity?: RepositoryIdentity;
+	warning?: ProviderWarning;
+}
+
+export interface ResolveRepositoryResult {
+	resolution: RepositoryResolution;
+}
+
+const maxProviderWarningMessageLength = 500;
+
+function providerWarningMessage(ex: unknown): string {
+	const raw = (ex instanceof Error ? ex.message : String(ex)).trim();
+	const carrier = ex as { status?: unknown; response?: { status?: unknown } } | null | undefined;
+	const status =
+		typeof carrier?.status === 'number'
+			? carrier.status
+			: typeof carrier?.response?.status === 'number'
+				? carrier.response.status
+				: undefined;
+
+	// Gateways commonly answer API requests with a complete HTML error page. That payload is neither actionable
+	// nor suitable for a warning DTO consumed by UIs and logs; preserve the status without leaking the document.
+	if (/<(?:!doctype\s+html|html|head|body)\b/i.test(raw)) {
+		return status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';
+	}
+
+	if (!raw) {
+		return status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';
+	}
+	return raw.length > maxProviderWarningMessageLength
+		? `${raw.slice(0, maxProviderWarningMessageLength - 3)}...`
+		: raw;
+}
+
+/**
+ * Normalized org/workspace/group shape returned by the provider facade.
+ * `name` is the provider identifier to pass to follow-up reads, while `org` is an optional display label.
+ */
+export interface ProviderOrganization {
+	id: string;
+	providerId: IntegrationIds;
+	name: string;
+	org?: string;
+	url: string;
+}
+
+/** Normalized repository shape returned by the provider facade. */
+export interface ProviderRepositoryShape {
+	id: string;
+	namespace: string;
+	name: string;
+	/** Azure DevOps project; `undefined` for hosts without a project layer. */
+	project?: string;
+	/** Web (browser) URL, when the provider exposes it. */
+	url?: string;
+	/** HTTPS clone URL, when available. */
+	cloneUrlHttps?: string;
+	/** SSH clone URL, when available. */
+	cloneUrlSsh?: string;
+	/** Default branch name, when the provider reports it. */
+	defaultBranch?: string;
+}
+
+/**
+ * Classifies a caught provider exception into a neutral {@link ProviderWarning}. Ordering matters:
+ * `instanceof` is checked most-specific-first so a rate-limit isn't mislabeled as a generic error and
+ * a 404 isn't mislabeled as auth.
+ */
+export function toProviderWarning(
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	ex: unknown,
+): ProviderWarning {
+	let kind: ProviderWarning['kind'];
+	if (ex instanceof AuthenticationError) {
+		kind = 'auth';
+	} else if (ex instanceof RequestRateLimitError) {
+		kind = 'rate-limit';
+	} else if (ex instanceof RequestNotFoundError) {
+		kind = 'not-found';
+	} else {
+		kind = 'other';
+	}
+
+	return {
+		providerId: providerId,
+		domain: domain,
+		connectionId: connectionId,
+		message: providerWarningMessage(ex),
+		kind: kind,
+		isAuth: kind === 'auth',
+	};
+}
+
+/** A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes. */
+function providerWarningKey(warning: ProviderWarning): string {
+	return [warning.providerId, warning.connectionId ?? '', warning.domain ?? '', warning.kind, warning.message].join(
+		' ',
+	);
+}
+
+/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+export function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void {
+	const key = providerWarningKey(warning);
+	if (into.some(existing => providerWarningKey(existing) === key)) return;
+
+	into.push(warning);
+}

package/src/plus/integrations/utils/domain.utils.ts

@@ -0,0 +1,26 @@
+/** Extracts the host from a domain expressed as either a URL or a bare host. */
+export function hostFromDomain(domain: string | undefined): string | undefined {
+	const value = domain?.trim();
+	if (!value) return undefined;
+
+	if (/^[a-z][a-z\d+\-.]*:\/\//i.test(value)) {
+		try {
+			return new URL(value).host || undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	try {
+		return new URL(`https://${value}`).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Whether two URL-or-host domain values identify the same normalized host and port. */
+export function areDomainsOnSameHost(first: string | undefined, second: string | undefined): boolean {
+	const firstHost = hostFromDomain(first);
+	const secondHost = hostFromDomain(second);
+	return firstHost != null && secondHost != null && firstHost === secondHost;
+}