@gitkraken/core-gitlens 0.3.1 → 0.4.100

package/src/plus/integrations/lite.ts

@@ -0,0 +1,233 @@
+// A lightweight, token-scoped entry point for stateless single-shot provider reads.
+//
+// Unlike `createIntegrationManager`, this does NOT build an `IntegrationServiceContext`
+// (no storage/account/config/cache/repositories/hooks) and runs no session/OAuth lifecycle.
+// A consumer that already holds a provider access token (obtained by its own means, e.g.
+// the GitKraken account backend's `v1/provider-tokens/{provider}` endpoint) can call the
+// per-provider API client directly and get back the same DTOs the session-managed
+// `GitHostIntegration` returns.
+//
+// Provider notes:
+// - Azure DevOps encodes the repository as the composite string `"{project}/_git/{repoName}"`
+//   in the `repo` argument (matching the descriptor `GitHostIntegration` uses); `owner` is the
+//   organization. Pass `repo` in that shape for Azure.
+// - Bitbucket Cloud `getDefaultBranch`/`getRepositoryMetadata` depend on `mainbranch`/`parent`
+//   fields the API may omit for some repos; they resolve to `undefined` when absent.
+// - Bitbucket Server (`bitbucket-server`) is not supported here — its reads use a different
+//   REST surface that this token-scoped path doesn't wire up.
+
+import type { GitHubApiConfig } from '../git-github/api/config.js';
+import { GitHubApi } from '../git-github/api/github.js';
+import type { DefaultBranch } from '../../git/models/defaultBranch.js';
+import type { Provider } from '../../git/models/remoteProvider.js';
+import type { RepositoryMetadata } from '../../git/models/repositoryMetadata.js';
+import type { TokenWithInfo } from './authentication/models.js';
+import { toTokenInfo } from './authentication/models.js';
+import { GitCloudHostIntegrationId, GitSelfManagedHostIntegrationId } from './constants.js';
+import type { ProviderApiConfig } from './providers/apiConfig.js';
+import { AzureDevOpsApi } from './providers/azure/azure.js';
+import { BitbucketApi } from './providers/bitbucket/bitbucket.js';
+import { GitLabApi } from './providers/gitlab/gitlab.js';
+import { providersMetadata } from './providers/models.js';
+
+/** The git-hosting integrations that expose a token-scoped read path here. */
+export type TokenScopedGitHostId =
+	| GitCloudHostIntegrationId.GitHub
+	| GitCloudHostIntegrationId.GitLab
+	| GitCloudHostIntegrationId.Bitbucket
+	| GitCloudHostIntegrationId.AzureDevOps
+	| GitSelfManagedHostIntegrationId.CloudGitHubEnterprise
+	| GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted
+	| GitSelfManagedHostIntegrationId.AzureDevOpsServer;
+
+export interface TokenScopedGitHostToken {
+	/** The provider access token the consumer already holds. */
+	readonly accessToken: string;
+	/**
+	 * Host domain for self-managed instances (e.g. `git.example.com`). Ignored for cloud ids. For an Azure
+	 * DevOps Server reachable over plain HTTP, include the scheme (e.g. `http://tfs.example.com`); otherwise
+	 * `https` is assumed.
+	 */
+	readonly domain?: string;
+	/** Optional scopes carried by the token, surfaced only in logging metadata. */
+	readonly scopes?: readonly string[];
+	/** Whether the token came from a GK-cloud connection (vs a raw PAT). Defaults to `true`. */
+	readonly cloud?: boolean;
+}
+
+export interface TokenScopedHttpConfig {
+	/** The `fetch` implementation to use for HTTP requests. */
+	fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+	/**
+	 * Wrap an async op so TLS validation is disabled when `ignoreSSLErrors` is `'force'`. Optional —
+	 * defaults to a pass-through, which is correct for the browser and for any consumer not toggling SSL.
+	 */
+	wrapForForcedInsecureSSL?<T>(ignoreSSLErrors: boolean | 'force', fn: () => Promise<T> | PromiseLike<T>): Promise<T>;
+	/** Whether to ignore SSL certificate errors on requests. Defaults to `false`. */
+	ignoreSSLErrors?: boolean | 'force';
+	/**
+	 * Whether the consumer runs in a web worker / browser (vs Node.js). GitHub uses this to drop the
+	 * `user-agent` header, which browsers reject and warn about. Defaults to `false`.
+	 */
+	isWeb?: boolean;
+}
+
+/** The stateless reads a token-scoped integration exposes. */
+export interface TokenScopedGitHostIntegration {
+	getRepositoryMetadata(
+		owner: string,
+		repo: string,
+		cancellation?: AbortSignal,
+	): Promise<RepositoryMetadata | undefined>;
+	getDefaultBranch(owner: string, repo: string, cancellation?: AbortSignal): Promise<DefaultBranch | undefined>;
+}
+
+/**
+ * Build a token-scoped git-host integration for a single provider, backed only by a `fetch` + a token —
+ * no `IntegrationServiceContext`, no session/OAuth lifecycle. The returned DTOs match those from the
+ * session-managed {@link GitHostIntegration}.
+ */
+export function createTokenScopedGitHostIntegration(
+	id: TokenScopedGitHostId,
+	token: TokenScopedGitHostToken,
+	http: TokenScopedHttpConfig,
+): TokenScopedGitHostIntegration {
+	// `token.domain` only applies to self-managed ids; cloud ids always use their canonical domain.
+	const selfManaged =
+		id === GitSelfManagedHostIntegrationId.CloudGitHubEnterprise ||
+		id === GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted ||
+		id === GitSelfManagedHostIntegrationId.AzureDevOpsServer;
+	// Self-managed ids carry no canonical domain (`providersMetadata[id].domain` is empty), so a missing
+	// `token.domain` would silently build a malformed base URL (e.g. `https:///api/v3`). Fail fast instead.
+	if (selfManaged && !token.domain) {
+		throw new Error(`A token-scoped integration for the self-managed host '${id}' requires 'token.domain'.`);
+	}
+
+	const rawDomain = (selfManaged && token.domain) || providersMetadata[id].domain;
+	// The provider/DTO domain drops the scheme (a subpath/collection is preserved for Azure Server and subpath
+	// installs); only Azure DevOps Server's base URL honors an explicit scheme (per its doc). Stripping keeps a
+	// scheme out of the DTO and prevents a malformed base URL (e.g. `https://http://host/api/v3`) if one is
+	// accidentally passed for GHE/GitLab.
+	const host = stripScheme(rawDomain);
+	const provider = createProviderStub(id, host, http.ignoreSSLErrors ?? false);
+	const tokenInfo = buildTokenWithInfo(id, token);
+
+	const wrapForForcedInsecureSSL: NonNullable<TokenScopedHttpConfig['wrapForForcedInsecureSSL']> =
+		// `Promise.resolve().then(fn)` (not `Promise.resolve(fn())`) so a synchronous throw in `fn` surfaces as
+		// a rejected promise, honoring the `Promise<T>` contract.
+		http.wrapForForcedInsecureSSL ?? ((_ignore, fn) => Promise.resolve().then(fn));
+
+	// GitHub has its own VS Code-free config type and a `getDefaultBranch` without a cancellation param.
+	if (id === GitCloudHostIntegrationId.GitHub || id === GitSelfManagedHostIntegrationId.CloudGitHubEnterprise) {
+		const config: GitHubApiConfig = {
+			isWeb: http.isWeb ?? false,
+			fetch: (url, init) => http.fetch(url, init),
+			wrapForForcedInsecureSSL: wrapForForcedInsecureSSL,
+		};
+		const api = new GitHubApi(config);
+		// GitHub is the one family whose base URL can legitimately be absent — see `resolveGitHubApiBaseUrl`.
+		const baseUrl = resolveGitHubApiBaseUrl(id, host);
+		return {
+			getRepositoryMetadata: (owner, repo, cancellation) =>
+				api.getRepositoryMetadata(provider, tokenInfo, owner, repo, { baseUrl: baseUrl }, cancellation),
+			// `GitHubApi.getDefaultBranch` has no cancellation param; accept and intentionally ignore it here so
+			// the signature matches the other providers and the drop is explicit at the call site.
+			getDefaultBranch: (owner, repo, _cancellation) =>
+				api.getDefaultBranch(provider, tokenInfo, owner, repo, { baseUrl: baseUrl }),
+		};
+	}
+
+	// GitLab, Bitbucket, and Azure DevOps share the `ProviderApiConfig` client shape and identical read signatures.
+	const baseUrl = resolveApiBaseUrl(id, rawDomain, host);
+	const config = toProviderApiConfig(http, wrapForForcedInsecureSSL);
+	const api =
+		id === GitCloudHostIntegrationId.GitLab || id === GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted
+			? new GitLabApi(config)
+			: id === GitCloudHostIntegrationId.Bitbucket
+				? new BitbucketApi(config)
+				: new AzureDevOpsApi(config);
+	return {
+		getRepositoryMetadata: (owner, repo, cancellation) =>
+			api.getRepositoryMetadata(provider, tokenInfo, owner, repo, { baseUrl: baseUrl }, cancellation),
+		getDefaultBranch: (owner, repo, cancellation) =>
+			api.getDefaultBranch(provider, tokenInfo, owner, repo, { baseUrl: baseUrl }, cancellation),
+	};
+}
+
+function toProviderApiConfig(
+	http: TokenScopedHttpConfig,
+	wrapForForcedInsecureSSL: NonNullable<TokenScopedHttpConfig['wrapForForcedInsecureSSL']>,
+): ProviderApiConfig {
+	return {
+		fetch: (input, init) => http.fetch(input, init),
+		wrapForForcedInsecureSSL: wrapForForcedInsecureSSL,
+	};
+}
+
+function buildTokenWithInfo(id: TokenScopedGitHostId, token: TokenScopedGitHostToken): TokenWithInfo {
+	const cloud = token.cloud ?? true;
+	return {
+		...toTokenInfo(id, token.accessToken, { cloud: cloud, type: undefined, scopes: token.scopes }),
+		accessToken: token.accessToken,
+	};
+}
+
+/** A minimal {@link Provider} for the API clients: identity + no-op reauth/telemetry, SSL from config. */
+function createProviderStub(id: TokenScopedGitHostId, domain: string, ignoreSSLErrors: boolean | 'force'): Provider {
+	const metadata = providersMetadata[id];
+	return {
+		id: id,
+		name: metadata.name,
+		domain: domain,
+		icon: metadata.iconKey,
+		getIgnoreSSLErrors: () => ignoreSSLErrors,
+		reauthenticate: () => Promise.resolve(),
+		trackRequestException: () => {},
+	};
+}
+
+/** Strips a leading `scheme://` and any trailing slashes; a subpath/collection (e.g. `host/tfs/Col`) is preserved. */
+function stripScheme(domain: string): string {
+	return domain.replace(/^[a-z][\w+.-]*:\/\//i, '').replace(/\/+$/, '');
+}
+
+/**
+ * GitHub's base URL, which `@gitkraken/provider-apis` derives BOTH the REST and the GraphQL endpoint from by
+ * appending GitHub Enterprise's paths (`/api/v3`, `/api/graphql`). Cloud must therefore pass nothing rather than
+ * `https://api.github.com`, which would build `https://api.github.com/api/graphql` and get a 404; omitting it is
+ * what selects the cloud endpoints. Mirrors the cloud `GitHubIntegration.apiBaseUrl` getter.
+ */
+function resolveGitHubApiBaseUrl(
+	id: GitCloudHostIntegrationId.GitHub | GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
+	host: string,
+): string | undefined {
+	return id === GitCloudHostIntegrationId.GitHub ? undefined : `https://${host}/api/v3`;
+}
+
+/**
+ * Mirrors the per-provider `apiBaseUrl` getters on the `GitHostIntegration` subclasses, for every family whose
+ * base URL is always concrete (GitHub's is not — see {@link resolveGitHubApiBaseUrl}). `rawDomain` may carry a
+ * scheme (only Azure DevOps Server honors it); `host` is the bare host used everywhere else.
+ */
+function resolveApiBaseUrl(
+	id: Exclude<
+		TokenScopedGitHostId,
+		GitCloudHostIntegrationId.GitHub | GitSelfManagedHostIntegrationId.CloudGitHubEnterprise
+	>,
+	rawDomain: string,
+	host: string,
+): string {
+	switch (id) {
+		case GitCloudHostIntegrationId.GitLab:
+			return 'https://gitlab.com/api';
+		case GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted:
+			return `https://${host}/api`;
+		case GitCloudHostIntegrationId.Bitbucket:
+			return 'https://api.bitbucket.org/2.0';
+		case GitCloudHostIntegrationId.AzureDevOps:
+			return 'https://dev.azure.com';
+		case GitSelfManagedHostIntegrationId.AzureDevOpsServer:
+			// Mirror the session-managed getter, which honors the connection protocol; default to https.
+			return rawDomain.includes('://') ? rawDomain.replace(/\/+$/, '') : `https://${host}`;
+	}
+}

package/src/plus/integrations/manager.ts

@@ -0,0 +1,359 @@
+import type { IssueShape } from '../../git/models/issue.js';
+import type { PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
+import type { Event } from '../../utils/event.js';
+import type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
+import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
+import type { IntegrationIds } from './constants.js';
+import type { IssueFilter, PullRequestFilter } from './providerFilters.js';
+import type {
+	ConnectionStateChangeEvent,
+	ProviderBroadenResult,
+	ProviderOrganization,
+	ProviderPagedResult,
+	ProviderRepositoryShape,
+	ProviderResult,
+	ProviderSweepResult,
+	ResolveRepositoryResult,
+} from './results.js';
+
+/** Neutral repository input accepted by repo-scoped provider reads. */
+export interface ProviderRepositoryInput {
+	namespace: string;
+	name: string;
+	project?: string;
+	id?: string;
+}
+
+export type ProviderRepositoriesInput = (string | number)[] | ProviderRepositoryInput[];
+
+/**
+ * One provider slice in a pull-request sweep.
+ *
+ * A sweep accepts at most one target per provider because its failure attribution is provider-scoped.
+ * `domain` is a fallback for self-managed hosts whose authentication provider doesn't persist a configured
+ * connection; a configured `connectionId` domain takes precedence when both are supplied. It must come from
+ * the trusted authentication configuration, not repository or remote data.
+ */
+export interface ProviderSweepTarget {
+	providerId: IntegrationIds;
+	connectionId?: string;
+	domain?: string;
+	/**
+	 * Relationship filters for this provider slice. With sweep-level `repos`, members are provider query
+	 * constraints; without `repos`, they form an exact OR union. The whole set is validated against the
+	 * selected path's capabilities.
+	 *
+	 * This per-target form lets a cross-provider sweep preserve provider-specific semantics without leaking
+	 * provider query details into the consumer. It overrides the sweep-level `filters` for this target.
+	 */
+	filters?: PullRequestFilter[];
+}
+
+type ProviderSweepSelection =
+	| {
+			targets: readonly ProviderSweepTarget[];
+			providerIds?: never;
+			connectionId?: never;
+	  }
+	| {
+			targets?: never;
+			providerIds?: IntegrationIds[];
+			/**
+			 * Legacy single-provider selector. It is ignored when `providerIds` contains more than one provider;
+			 * use `targets` to select connections independently in a multi-provider sweep.
+			 */
+			connectionId?: string;
+	  };
+
+/**
+ * One org slice in an issue-broadening fan-out. `domain` is a fallback for self-managed hosts whose
+ * authentication provider doesn't persist a configured connection; a configured `connectionId` domain takes
+ * precedence when both are supplied. It must come from the trusted authentication configuration, not
+ * repository or remote data.
+ */
+export interface ProviderBroadenOrg {
+	providerId: IntegrationIds;
+	name: string;
+	connectionId?: string;
+	domain?: string;
+}
+
+type PullRequestSweepCommonOptions = {
+	repos?: ProviderRepositoriesInput;
+	/** Named `states` to match {@link IntegrationManager.listPullRequestsPage}; a mismatch here read as silently ignored. */
+	states?: PullRequestStateFilter[];
+	/**
+	 * Relationship filters applied to every target. Repo-scoped reads combine them as provider query
+	 * constraints (normally an intersection); account-wide reads form an exact OR union. The set is validated
+	 * against `pullRequests` or `pullRequestsAccountWide`, respectively. A target's own `filters` overrides this.
+	 */
+	filters?: PullRequestFilter[];
+	/**
+	 * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
+	 * This extends the provider-native result; it is not a narrowing filter.
+	 */
+	includeReviewRequested?: boolean;
+	forceSync?: boolean;
+	maxPages?: number;
+};
+
+export type PullRequestSweepOptions = PullRequestSweepCommonOptions & ProviderSweepSelection;
+
+export type ClosedPullRequestSweepOptions = Omit<PullRequestSweepCommonOptions, 'states'> & ProviderSweepSelection;
+
+/**
+ * Organization discovery either fans out without a provider-specific target, or pins every scoped selector
+ * to one provider. A `connectionId`/`domain` without `providerId` is ambiguous and therefore unrepresentable.
+ */
+export type ListOrgsOptions =
+	| {
+			providerId: IntegrationIds;
+			connectionId?: string;
+			domain?: string;
+	  }
+	| {
+			providerId?: never;
+			connectionId?: never;
+			domain?: never;
+	  };
+
+/**
+ * Project discovery follows the same provider-targeting rule as {@link ListOrgsOptions}; `org` may still
+ * narrow either a single-provider read or the unscoped fan-out.
+ */
+export type ListProjectsOptions =
+	| {
+			providerId: IntegrationIds;
+			org?: string;
+			connectionId?: string;
+			domain?: string;
+	  }
+	| {
+			providerId?: never;
+			org?: string;
+			connectionId?: never;
+			domain?: never;
+	  };
+
+/**
+ * Public, provider-neutral integration facade. Provider clients and integration model instances remain private
+ * implementation details so SDK changes don't expand this contract.
+ *
+ * ## Paging contract
+ *
+ * Every paged read (`listRepos`, `listPullRequestsPage`, `listIssuesPage`, `listIssueTrackerIssuesPage`,
+ * `broadenIssues`) takes both `page` and `cursor`, and the two are NOT interchangeable:
+ *
+ * - **Supplying `cursor` guarantees a single upstream round trip per provider scope.** A threaded continuation
+ *   is handed to the provider as-is; the facade never walks the pages before it. This is a guarantee, not an
+ *   optimization: a consumer that threads `cursor` back pays O(1) requests per page.
+ * - **Supplying only `page` (> 1) may cost O(page) upstream requests.** Cursor-backed reads such as GitHub
+ *   searches and broaden fan-outs can't be addressed by number, so the facade drains the pages before the
+ *   requested one internally and returns just page N. Providers whose account-wide reads aggregate into one
+ *   terminal page do not incur that drain. The fallback for cursor-backed reads MUST be kept: it supports the
+ *   first page-number-only read after a refresh, where no cursor was persisted.
+ * - Prefer `cursor` when both are available. Pass `page` alongside it so the result's positional
+ *   `page.currentPage` reflects where the caller is (the convention is documented on `ProviderPageInfo`); the
+ *   cursor, not the page number, is what actually advances the read.
+ * - `hasMore` is only ever true with a `cursor` the caller can act on. A provider that reports another page
+ *   but hands back no usable continuation is reported as terminal-but-incomplete (`hasMore: false` +
+ *   `page.truncated`), never as a page that can't be requested.
+ */
+export interface IntegrationManager {
+	readonly onDidChange: Event<ConfiguredIntegrationsChangeEvent>;
+	readonly onDidChangeConnectionState: Event<ConnectionStateChangeEvent>;
+
+	dispose(): void;
+
+	getConfigured(
+		id?: IntegrationIds,
+		options?: { cloud?: boolean; domain?: string },
+	): ConfiguredIntegrationDescriptor[];
+	/**
+	 * The `filters` a provider accepts on `listPullRequestsPage`/`listIssuesPage` and the sweeps.
+	 *
+	 * The filter contract is all-or-nothing: a set containing even one unsupported filter is refused (empty
+	 * `items` + a warning + `fetchFailed`) rather than narrowed, because falling through to an unfiltered read
+	 * would return every pull request instead of the user's. Intersect against this before the read so a
+	 * cross-provider filter set never turns into a failed page. Static per provider — no connection required.
+	 *
+	 * Empty means no filter of that kind is expressible (issue trackers have no pull requests; Bitbucket exposes
+	 * no issues), which means "pass no filters", not "error".
+	 *
+	 * `pullRequests` covers repo-scoped PR reads; `pullRequestsAccountWide` covers account-wide PR reads.
+	 * `issues` covers the repo-scoped issue read; `issuesAccountWide` covers the account-wide one (no `repos`).
+	 * They differ because they are different provider queries — GitLab can express `Assignee` and `Author`
+	 * account-wide, but not `Mention` — and `listIssuesPage` validates against whichever the read uses.
+	 *
+	 * An ISSUE TRACKER (Jira/Linear/Trello) reports its filters under `issues`, and
+	 * {@link IntegrationManager.listIssueTrackerIssuesPage} validates against that field. Its
+	 * `issuesAccountWide` is empty — those two fields split the git-host reads, and a tracker has neither of
+	 * them (its issues live under resource → project) — so intersecting a tracker's filters against
+	 * `issuesAccountWide` would read "cannot filter" for a provider that filters fine.
+	 *
+	 * This is a capability table, not a recommendation: a consumer matching another tool's behavior may pass fewer
+	 * filters than are listed, or none where the underlying read is already scoped.
+	 */
+	getSupportedFilters(providerId: IntegrationIds): {
+		pullRequests: PullRequestFilter[];
+		/** Optional for structural compatibility; missing means no account-wide narrowing filters are supported. */
+		pullRequestsAccountWide?: PullRequestFilter[];
+		issues: IssueFilter[];
+		issuesAccountWide: IssueFilter[];
+	};
+	/** Forces an authoritative cloud connection refresh. Rejects if the backend connection list cannot be read. */
+	refreshConnections(): Promise<void>;
+	/** Rejects unless `connectionId` is a configured cloud connection for `id`. */
+	setPrimaryConnection(id: IntegrationIds, connectionId: string): Promise<void>;
+	/** Rejects unless `connectionId` is a configured cloud connection for `id`. */
+	deleteConnection(id: IntegrationIds, connectionId: string): Promise<void>;
+
+	listOrgs(options?: ListOrgsOptions): Promise<ProviderResult<ProviderOrganization>>;
+	listProjects(options?: ListProjectsOptions): Promise<ProviderResult<ProviderOrganization>>;
+	listRepos(options: {
+		providerId: IntegrationIds;
+		org?: string;
+		project?: string;
+		/**
+		 * Requested 1-based page. Cursor-only providers are advanced internally when no `cursor` is supplied,
+		 * so a direct page-N request can cost O(page) upstream calls.
+		 */
+		page?: number;
+		/** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
+		cursor?: string;
+		/**
+		 * Requested page size. Advisory: the repos read core is cursor-only and takes no page size, so the
+		 * provider's own size is what applies — `page.itemsPerPage` reports what was actually returned.
+		 */
+		itemsPerPage?: number;
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderPagedResult<ProviderRepositoryShape>>;
+	listPullRequestsPage(options: {
+		providerId: IntegrationIds;
+		repos?: ProviderRepositoriesInput;
+		states?: PullRequestStateFilter[];
+		/**
+		 * Relationship filters. Repo-scoped reads combine members as provider query constraints (normally an
+		 * intersection), so issue separate reads when the desired result is a union. Account-wide members form an
+		 * exact OR union. Each path validates the whole set against its corresponding capability.
+		 */
+		filters?: PullRequestFilter[];
+		/**
+		 * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
+		 * This extends the provider-native result; it is not a narrowing filter.
+		 */
+		includeReviewRequested?: boolean;
+		/**
+		 * Requested 1-based page. Without a `cursor` this may cost O(page) upstream requests on a cursor-only
+		 * read (repo-scoped GitHub/GHE and account-wide providers that return continuations), which the facade
+		 * drains internally.
+		 */
+		page?: number;
+		/** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
+		cursor?: string;
+		/**
+		 * Requested page size, honored on the repo-scoped path. The provider-defined account-wide read (no
+		 * `repos`) takes no page size, so it is ignored there — `page.itemsPerPage` reports what was actually
+		 * returned rather than echoing the request.
+		 */
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	}): Promise<ProviderPagedResult<PullRequestShape>>;
+	listIssuesPage(options: {
+		providerId: IntegrationIds;
+		repos?: ProviderRepositoriesInput;
+		/**
+		 * Narrows the account-wide read (no `repos`) to one org/account, and `project` to one project within it.
+		 * Only a git host with a project tier (Azure DevOps) can scope this server-side; for any other provider
+		 * either option is rejected with a warning + `fetchFailed` rather than silently returning an unscoped
+		 * list. Ignored when `repos` is supplied, since those repos are already the scope.
+		 */
+		org?: string;
+		project?: string;
+		/**
+		 * Narrows to the requested relationship(s), validated against `getSupportedFilters().issues` on the
+		 * repo-scoped path and `.issuesAccountWide` on the account-wide one.
+		 *
+		 * On the account-wide path this REPLACES the provider's own definition of "my issues" — GitHub/GHE
+		 * authored + assigned + mentioned, Azure assigned + authored, and GitLab assigned-to-me — so
+		 * `[Assignee]` gets `assignee:@me` semantics wherever it's expressible. Narrowing must happen here rather
+		 * than on the returned page: the excluded items still counted toward the provider's paging, so filtering
+		 * afterward leaves `items` describing a different result set than `hasMore`/`cursor`.
+		 *
+		 * A set the provider can't express server-side is refused whole (warning + `fetchFailed`), never widened.
+		 */
+		filters?: IssueFilter[];
+		/** Broadens to every assignee. On account-wide reads it contradicts `filters`, so passing both is refused. */
+		includeAllAssignees?: boolean;
+		/**
+		 * Requested 1-based page. Without a `cursor` this may cost O(page) upstream requests on cursor-backed
+		 * reads such as repo-scoped GitHub/GHE; aggregate single-page account-wide reads remain O(1).
+		 */
+		page?: number;
+		/** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
+		cursor?: string;
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderPagedResult<IssueShape>>;
+	/** Issue trackers are cloud-only, so this read takes no `domain`. */
+	listIssueTrackerIssuesPage(options: {
+		providerId: IntegrationIds;
+		org?: string;
+		project?: string;
+		filters?: IssueFilter[];
+		includeAllAssignees?: boolean;
+		forceSync?: boolean;
+		page?: number;
+		/**
+		 * Opaque continuation from a prior result. It can bundle the next untouched project window with failed
+		 * discovery/project retries and already-emitted project identities, so it is not equivalent to `page`.
+		 * Thread it back verbatim. A retry-only cursor can remain when `hasMore` is false; reusing that cursor is
+		 * an explicit manual retry, while `hasMore` represents automatic forward progress only.
+		 */
+		cursor?: string;
+		/**
+		 * Page size in PROJECTS, not issues (default 20): these providers have no cross-project issue cursor, so
+		 * a page is a window of projects, each drained in full. Supplying it (or `page`/`cursor`) opts into
+		 * pagination; omitting all three aggregates every matched project in one page.
+		 */
+		itemsPerPage?: number;
+		connectionId?: string;
+	}): Promise<ProviderPagedResult<IssueShape>>;
+	sweepPullRequests(options?: PullRequestSweepOptions): Promise<ProviderSweepResult<PullRequestShape>>;
+	sweepClosedPullRequests(options?: ClosedPullRequestSweepOptions): Promise<ProviderSweepResult<PullRequestShape>>;
+	broadenIssues(options: {
+		orgs: ProviderBroadenOrg[];
+		/**
+		 * Requested 1-based page. Without a `cursor` the fan-out is re-run once per prior page (O(page) rounds),
+		 * since a per-org cursor bundle is the only way to address a later page.
+		 */
+		page?: number;
+		/** Continuation from a prior page's `cursor`; supplying it runs exactly one fan-out round. */
+		cursor?: string;
+		forceSync?: boolean;
+	}): Promise<ProviderBroadenResult<IssueShape>>;
+	resolveRepository(options: {
+		providerId?: IntegrationIds;
+		remoteUrl: string;
+		host?: string;
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain used to select the integration instance. It must come from trusted
+		 * authentication configuration. Without it, the host parsed from `remoteUrl` is only a resolution
+		 * candidate: the facade proceeds only when that host matches a configured integration, so repository
+		 * data cannot select credentials for an arbitrary host.
+		 */
+		domain?: string;
+	}): Promise<ResolveRepositoryResult>;
+}