@gitkraken/core-gitlens 0.3.1 → 0.4.100

package/dist/plus/integrations/context.d.ts

@@ -0,0 +1,358 @@
+import type { Account } 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 { GitRemote } from '../../git/models/remote.js';
+import type { RepositoryMetadata } from '../../git/models/repositoryMetadata.js';
+import type { ResourceDescriptor } from '../../git/models/resourceDescriptor.js';
+import type { Event } from '../../utils/event.js';
+import type { CacheController } from '../../utils/promiseCache.js';
+import type { IntegrationAuthenticationProvider } from './authentication/integrationAuthenticationProvider.js';
+import type { IntegrationIds } from './constants.js';
+import type { GitHostIntegration } from './models/gitHostIntegration.js';
+import type { IntegrationBase } from './models/integration.js';
+import type { Source } from './telemetry.js';
+/**
+ * Context provided to {@link IntegrationService} at construction time.
+ *
+ * Replaces all extension-host coupling that integrations would otherwise reach
+ * for: storage, subscription, cloud connection, host-side authentication,
+ * configuration, commands, UI surfaces, etc. The package boundary at
+ * `@gitkraken/core-gitlens/plus/integrations` cannot import `vscode` or reach into the extension
+ * host directly — every cross-boundary concern is named here so the host can
+ * adapt its own services to satisfy it.
+ *
+ * Mirrors the {@link import('../../git/context.js').GitServiceContext} pattern.
+ */
+export interface IntegrationServiceContext {
+    readonly storage: IntegrationStorageProvider;
+    readonly account: AccountProvider;
+    readonly config: ConfigProvider;
+    readonly http: HttpProvider;
+    readonly cache: IntegrationCacheProvider;
+    readonly repositories: RepositoriesProvider;
+    readonly hooks?: IntegrationServiceHooks;
+}
+/**
+ * The GitKraken account + the GK-cloud connect/manage flows. Unifies the former
+ * subscription/cloudConnection/authentication/uris ports: the host owns the GK-Dev OAuth round-trips
+ * end-to-end (URL shape, exchange token, redirect, callback, redeem), so the package stays out of the
+ * GK-cloud UI and only orchestrates (state, sync, hooks) around `connect`/`openManagement`.
+ */
+export interface AccountProvider {
+    /**
+     * The signed-in GK account, or `undefined` when signed out. `createIfNeeded` triggers the host's
+     * sign-in/sign-up flow (folds the former `loginOrSignUp`/`isSignedIn`/`hasAccountSession`).
+     */
+    getAccount(options?: {
+        createIfNeeded?: boolean;
+        source?: Source;
+    }): Promise<{
+        id: string;
+        name?: string;
+        email?: string;
+    } | undefined>;
+    /** Fires when account/subscription state changes (login, logout, plan change). */
+    readonly onDidChange: Event<void>;
+    /**
+     * Fires on a host account check-in; `force` requests a force-refresh of cloud integration sessions
+     * (explicit re-validation: login, trial activation, manual validate).
+     */
+    readonly onDidCheckIn: Event<{
+        force?: boolean;
+    }>;
+    /** Fires when a host auth session changes (carries the changed provider id the package matches). */
+    readonly onDidChangeSessions: Event<AuthenticationSessionsChangeEvent>;
+    /**
+     * Whether the account is in a trial-or-paid state. Read by {@link IntegrationBase.access} to decide
+     * whether a connected integration's rich features are usable.
+     */
+    isTrialOrPaid(): Promise<boolean>;
+    /**
+     * Authenticated request against the GK cloud API (the connections/tokens endpoints used by
+     * `CloudIntegrationService`). Routes through the host's shared `ServerConnection` (circuit-breaker).
+     */
+    fetchGkApi(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Run the GK-Dev connect flow for the given integrations: the host builds the connect URL (query,
+     * provider, exchange-token vs redirect), opens it, awaits its own OAuth callback, and signs in +
+     * connects in one round-trip. Returns `true` on success; the package syncs + fires hooks around it.
+     */
+    connect(options: {
+        integrationIds?: IntegrationIds[];
+        source?: Source;
+    }): Promise<boolean>;
+    /**
+     * Open the GK-Dev integrations-management page (signing in first if needed) and resolve when the user
+     * returns to the window — `true` if they returned (so the package re-syncs), `false` otherwise.
+     */
+    openManagement(source?: Source): Promise<boolean>;
+}
+/** A cached value, possibly still resolving. Mirrors the host `CacheProvider`'s result shape. */
+type CacheResult<T> = Promise<T | undefined> | T | undefined;
+/** Produces the value (and optional expiry) to cache on a miss; the controller allows invalidation. */
+type Cacheable<T> = (cacheable: CacheController) => {
+    value: CacheResult<T>;
+    expiresAt?: number;
+};
+/** Cache expiry controls. */
+interface CacheExpiryOptions {
+    expiryOverride?: boolean | number;
+    expireOnError?: boolean;
+}
+/**
+ * Cross-call cache for expensive provider lookups. Wraps the host's cache
+ * service, which deduplicates concurrent loads for the same logical key.
+ *
+ * Method names + shapes mirror the host's `CacheProvider` so the package routes
+ * every cache call through this provider without adapting call sites — and the
+ * host adapter can assign its real `CacheProvider` directly (no cast).
+ */
+export interface IntegrationCacheProvider {
+    getRepositoryMetadata(repo: ResourceDescriptor, integration: GitHostIntegration | undefined, cacheable: Cacheable<RepositoryMetadata>, options?: CacheExpiryOptions): CacheResult<RepositoryMetadata>;
+    getRepositoryDefaultBranch(repo: ResourceDescriptor, integration: GitHostIntegration | undefined, cacheable: Cacheable<DefaultBranch>, options?: CacheExpiryOptions): CacheResult<DefaultBranch>;
+    getPullRequestForSha(sha: string, repo: ResourceDescriptor, integration: GitHostIntegration | undefined, cacheable: Cacheable<PullRequest>, options?: CacheExpiryOptions): CacheResult<PullRequest>;
+    getPullRequestForBranch(branch: string, repo: ResourceDescriptor, integration: GitHostIntegration | undefined, cacheable: Cacheable<PullRequest>, options?: CacheExpiryOptions): CacheResult<PullRequest>;
+    getPullRequest(id: string, resource: ResourceDescriptor, integration: IntegrationBase | undefined, cacheable: Cacheable<PullRequest>, options?: CacheExpiryOptions): CacheResult<PullRequest>;
+    getIssueOrPullRequest(id: string, type: IssueOrPullRequestType | undefined, resource: ResourceDescriptor, integration: IntegrationBase | undefined, cacheable: Cacheable<IssueOrPullRequest>, options?: CacheExpiryOptions): CacheResult<IssueOrPullRequest>;
+    getIssue(id: string, resource: ResourceDescriptor, integration: IntegrationBase | undefined, cacheable: Cacheable<Issue>, options?: CacheExpiryOptions): CacheResult<Issue>;
+    getCurrentAccount(integration: IntegrationBase, cacheable: Cacheable<Account>, options?: CacheExpiryOptions & {
+        connectionId?: string;
+        etag?: string;
+    }): CacheResult<Account>;
+}
+/**
+ * The remotes across all currently-open repositories. The package only ever needs the *remotes* (to map
+ * them to integrations) — never the repositories themselves — so the host flattens to a remote list
+ * rather than leaking a repository shape across the boundary. Used for "across all open repos" queries:
+ * issue aggregation by remote ({@link IntegrationService.getMyIssues}) and bitbucket's reviewing-PRs search.
+ */
+export interface RepositoriesProvider {
+    getOpenRemotes(): Promise<readonly GitRemote[]>;
+}
+/**
+ * HTTP primitives the package uses to call out to provider APIs. Wraps the
+ * host's `@env/fetch` (which differs between Node and browser builds) so the
+ * package itself stays environment-agnostic.
+ */
+export interface HttpProvider {
+    /** Whether the package is running in a webworker/browser environment. */
+    readonly isWeb: boolean;
+    /** Pre-assembled User-Agent string for provider API requests (host builds it from its env facts). */
+    readonly userAgent: string;
+    /** Host-supplied fetch implementation. */
+    fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Wrap a fetch in the host's "ignore SSL errors" toggle. On Node, this
+     * disables TLS verification while the wrapped fetch is in flight; on the
+     * browser, it's a no-op.
+     */
+    wrapForForcedInsecureSSL<T>(ignoreSSLErrors: boolean | 'force', fn: () => Promise<T> | PromiseLike<T>): Promise<T>;
+}
+/**
+ * Persists integration token/session/configured-integration state.
+ * Wraps the host's `Container.storage` (global + workspace + secret stores).
+ *
+ * Two non-secret namespaces:
+ *  - **Global** (`get`/`store`/`delete`/`deleteWithPrefix`) — values shared
+ *    across all workspaces (e.g., the `integrations:configured` descriptor
+ *    map, per-account caches keyed by access token).
+ *  - **Workspace** (`getWorkspace`/`storeWorkspace`/`deleteWorkspace`) —
+ *    values scoped to the active workspace (e.g., `connected:<id>` flags).
+ *
+ * Plus a **Secret** namespace (`getSecret`/`storeSecret`/`deleteSecret`)
+ * for OAuth tokens and other credentials.
+ *
+ * Method names mirror the host's `Storage` API so the package can route
+ * every storage access through this provider without renaming call sites.
+ */
+export interface IntegrationStorageProvider {
+    /** Read a global (cross-workspace) value (non-secret). */
+    get<T = any>(key: string): T | undefined;
+    /** Write a global (cross-workspace) value (non-secret). */
+    store<T = any>(key: string, value: T): Promise<void>;
+    /** Delete a global value. */
+    delete(key: string): Promise<void>;
+    /** Delete every global key with the given prefix. */
+    deleteWithPrefix(prefix: string): Promise<void>;
+    /** Read a workspace-scoped value (non-secret). */
+    getWorkspace<T = any>(key: string): T | undefined;
+    /** Write a workspace-scoped value (non-secret). */
+    storeWorkspace<T = any>(key: string, value: T): Promise<void>;
+    /** Delete a workspace-scoped value (non-secret). */
+    deleteWorkspace(key: string): Promise<void>;
+    /** Read a secret (e.g., access token). */
+    getSecret(key: string): Promise<string | undefined>;
+    /** Store a secret. */
+    storeSecret(key: string, value: string): Promise<void>;
+    /** Delete a secret. */
+    deleteSecret(key: string): Promise<void>;
+}
+export interface AuthenticationSessionsChangeEvent {
+    readonly provider: {
+        readonly id: string;
+    };
+}
+/**
+ * Per-remote-host configuration entry (subset of the host's `RemotesConfig`).
+ * Used by `IntegrationService.ignoreSSLErrors` to look up self-managed remote
+ * settings.
+ */
+export interface IntegrationsRemoteConfig {
+    readonly type: string;
+    /** Exact-match domain (mutually exclusive with `regex`) */
+    readonly domain?: string;
+    /** Regex pattern for flexible host matching (mutually exclusive with `domain`) */
+    readonly regex?: string;
+    /** URL protocol override (e.g., `'https'`) */
+    readonly protocol?: string;
+    readonly ignoreSSLErrors?: boolean | 'force';
+}
+/**
+ * Snapshot of integration-relevant config values + reactive change detection.
+ *
+ * Only the keys integrations actually read are surfaced; everything else is
+ * the host's concern. Host adapter wraps the `system/-webview/configuration`
+ * helper to satisfy this.
+ */
+export interface ConfigProvider {
+    /** `integrations.enabled`. Optional — omit (or omit a `false` return) and integrations are enabled. */
+    isIntegrationsEnabled?(): boolean;
+    /**
+     * `launchpad.*` knobs surfaced to the GitHub provider.
+     */
+    getLaunchpadOptions(): {
+        queryLimit?: number;
+        ignoredRepositories?: readonly string[];
+        includedOrganizations?: readonly string[];
+        ignoredOrganizations?: readonly string[];
+    };
+    /** Per-remote-host configurations from `remotes`. */
+    getRemoteConfigs(): readonly IntegrationsRemoteConfig[];
+    /** Fires when any integration-relevant config changes. */
+    readonly onDidChange: Event<ConfigChangeEvent>;
+}
+/** Typed change descriptor returned by {@link ConfigProvider.onDidChange}. */
+export interface ConfigChangeEvent {
+    /** Whether `remotes` configuration changed. */
+    readonly remotes: boolean;
+    /** Whether `integrations.enabled` changed. */
+    readonly integrationsEnabled: boolean;
+    /** Whether one of the `launchpad.*` keys changed. */
+    readonly launchpad: boolean;
+    /** Whether `http.proxy` or `http.proxyStrictSSL` (VS Code core) changed. */
+    readonly httpProxy: boolean;
+}
+/**
+ * Outbound hooks: the package raises domain events the host wants to observe
+ * and exposes host-owned composition hooks (e.g., `createAuthenticationProvider`).
+ *
+ * Hooks are optional; the package omits the call when unset. They follow the
+ * pattern used by `@gitkraken/core-gitlens/plus/agents` (`AgentProviderCallbacks`) and the
+ * existing `GitServiceHooks` — the package surfaces named events; the host
+ * decides what to do (send telemetry, log, update UI, etc.).
+ *
+ * Replaces the direct `Container.telemetry.sendEvent` calls scattered through
+ * integration source today. Each hook below is named after the domain event,
+ * not its current telemetry event name; the host adapter forwards each one to
+ * the corresponding `telemetry.sendEvent('cloudIntegrations/...')` call to
+ * preserve existing analytics.
+ */
+export interface IntegrationServiceHooks {
+    /**
+     * Ask the host to confirm reauthentication after an integration auth/permission failure. The host
+     * owns the prompt (and its "Reauthenticate" affordance) and resolves to the user's choice; the
+     * package performs the actual reauth when this resolves truthy. Omit to never prompt.
+     */
+    onReauthenticationRequired?(message: string): Promise<boolean | undefined>;
+    /**
+     * Confirm disabling a connected integration. The host renders the dialog (offering a "sign out"
+     * choice when `offerSignOut`); resolves to the user's decision, or `undefined` to cancel. Omit to
+     * make interactive `disconnect()` a no-op (callers should pass `silent`/`currentSessionOnly` then).
+     */
+    onConfirmDisconnect?(e: {
+        integrationName: string;
+        offerSignOut: boolean;
+    }): Promise<{
+        signOut: boolean;
+    } | undefined>;
+    /**
+     * Optional consumer override: construct a custom authentication provider for `id` (e.g. a manual-token
+     * provider via {@link createManualTokenAuthProvider}). Return `undefined` to defer to the package's own
+     * cloud-OAuth provider. GitLens omits this — the package builds its cloud providers internally; an
+     * external consumer can plug in any auth strategy here.
+     */
+    createAuthenticationProvider?(args: {
+        id: IntegrationIds;
+    }): Promise<IntegrationAuthenticationProvider | undefined>;
+    /**
+     * Outbound behavioral events, nested by domain — mirroring `@gitkraken/core-gitlens/git`'s `GitServiceHooks`. The
+     * package raises typed domain events; the host decides what to do (GitLens maps each to its telemetry
+     * schema, but a consumer could log or ignore them — they're behavioral, not telemetry-specific).
+     * Optional throughout — omit to opt out entirely (no stub functions needed).
+     */
+    connection?: {
+        /** A connect flow was initiated. */
+        onStarted?(e: {
+            integrationIds: IntegrationIds[] | undefined;
+        }, source: Source | undefined): void;
+        /** A connect flow finished syncing. */
+        onCompleted?(e: {
+            integrationIds: IntegrationIds[] | undefined;
+            connectedIntegrationIds: IntegrationIds[] | undefined;
+        }, source: Source | undefined): void;
+        /** The user opened the integrations management surface. */
+        onManaged?(source: Source | undefined): void;
+        /** A hosting/remote/issue integration's connection state changed. */
+        onStateChanged?(e: {
+            id: IntegrationIds;
+            key: string;
+            connected: boolean;
+            kind: 'hosting' | 'remote' | 'issue';
+        }): void;
+        /** The set of connected integrations changed (e.g. for connected-count attributes). */
+        onConnectedChanged?(e: {
+            integrationIds: IntegrationIds[];
+        }): void;
+        /** Fetching the set of connected providers failed. */
+        onConnectionsFetchFailed?(e: {
+            code: number | undefined;
+        }): void;
+        /** Fetching/refreshing a single provider's token failed. */
+        onConnectionFetchFailed?(e: {
+            id: IntegrationIds;
+            code: number | undefined;
+            refreshing: boolean;
+        }): void;
+        /** Disconnecting a provider's token failed. */
+        onDisconnectFailed?(e: {
+            id: IntegrationIds;
+            code: number | undefined;
+        }): void;
+    };
+    /** Outbound session events (behavioral; the host maps to telemetry). */
+    session?: {
+        /** A session refresh was skipped (reported once per reason). */
+        onRefreshSkipped?(e: {
+            id: IntegrationIds;
+            reason: 'skip-non-cloud' | 'missing-expiry';
+            cloud: boolean | undefined;
+        }): void;
+    };
+    /** Outbound user-facing notifications (fire-and-forget). The host renders them; a consumer may log/ignore. */
+    ui?: {
+        /** A non-fatal error to surface. */
+        onError?(message: string): void;
+        /** The integration's API returned a 500-level error. */
+        onRequestFailed?(message: string): void;
+        /** The integration's API request timed out. */
+        onRequestTimedOut?(integrationName: string): void;
+        /** An integration was disconnected after too many consecutive failed requests. */
+        onDisconnectedAfterTooManyFailures?(integrationName: string): void;
+        /** Bitbucket's "Pull Requests for Commit" app isn't installed; `revLink` opens the install page. */
+        onBitbucketCommitLinksAppMissing?(revLink: string): void;
+    };
+}
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/plus/integrations/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/plus/integrations/context.ts"],"names":[],"mappings":"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"}

package/dist/plus/integrations/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/plus/integrations/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/plus/integrations/context.ts"],"names":[],"mappings":""}

package/dist/plus/integrations/errors.d.ts

@@ -0,0 +1,79 @@
+export type { AuthTokenInfo } from '../../git/errors.js';
+export { AuthenticationError, AuthenticationErrorReason, RequestClientError, RequestNotFoundError, 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 declare class IntegrationReadUnavailableError extends Error {
+    constructor(provider: string, reason: string);
+}
+/**
+ * Thrown by integration provider HTTP clients when an upstream request fails.
+ */
+export declare class ProviderFetchError extends Error {
+    readonly response: Response;
+    get status(): number;
+    get statusText(): string;
+    /**
+     * 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 fromResponse(provider: string, response: Response): Promise<ProviderFetchError>;
+    constructor(provider: string, response: Response, errors?: {
+        message: string;
+    }[]);
+}
+/**
+ * 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 declare function isRateLimitResponse(ex: {
+    status: number;
+    message?: string;
+}): boolean;
+/**
+ * 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 declare function toRateLimitError(ex: Error & {
+    response?: {
+        headers?: ResponseHeaders;
+    };
+}, token: string | undefined): RequestRateLimitError;
+/**
+ * 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 declare function toError(ex: unknown): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/plus/integrations/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/plus/integrations/errors.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EACN,mBAAmB,EACnB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;GAMG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACzD,YAAY,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAG3C;CACD;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAwB3B,QAAQ,EAAE,QAAQ;IAvBnC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;;;OAQG;IACH,OAAa,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAE3F;IAED,YACC,QAAQ,EAAE,MAAM,EACA,QAAQ,EAAE,QAAQ,EAClC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,EAS9B;CACD;AAgDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAQrF;AAED;;;;GAIG;AACH,KAAK,eAAe,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,EAAE,EAAE,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,eAAe,CAAA;KAAE,CAAA;CAAE,EACxD,KAAK,EAAE,MAAM,GAAG,SAAS,GACvB,qBAAqB,CAoBvB;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,CAE1C"}

package/dist/plus/integrations/errors.js

@@ -0,0 +1,150 @@
+export { AuthenticationError, AuthenticationErrorReason, RequestClientError, RequestNotFoundError, 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, reason) {
+        super(`${provider} read unavailable: ${reason}`);
+        Error.captureStackTrace?.(this, new.target);
+    }
+}
+/**
+ * Thrown by integration provider HTTP clients when an upstream request fails.
+ */
+export class ProviderFetchError extends Error {
+    response;
+    get status() {
+        return this.response.status;
+    }
+    get statusText() {
+        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, response) {
+        return new ProviderFetchError(provider, response, await readErrorBodyMessage(response));
+    }
+    constructor(provider, response, errors) {
+        super(`${provider} request failed: ${!response.ok ? `(${response.status}) ${response.statusText}. ` : ''}${errors?.length ? errors[0].message : ''}`);
+        this.response = response;
+        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) {
+    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;
+    try {
+        const body = JSON.parse(text);
+        if (body != null && typeof body === 'object') {
+            const { message: m, error } = body;
+            if (typeof m === 'string') {
+                message = m;
+            }
+            else if (typeof error === 'string') {
+                message = error;
+            }
+            else if (error != null && typeof error === 'object' && typeof error.message === 'string') {
+                message = error.message;
+            }
+        }
+    }
+    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) {
+    // 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'));
+}
+/**
+ * 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, token) {
+    const headers = ex.response?.headers;
+    const raw = headers == null
+        ? undefined
+        : typeof headers.get === 'function'
+            ? headers.get('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;
+    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) {
+    return ex instanceof Error ? ex : new Error(String(ex));
+}
+//# sourceMappingURL=errors.js.map

package/dist/plus/integrations/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/plus/integrations/errors.ts"],"names":[],"mappings":"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"}