@gitkraken/core-gitlens 0.23.0 → 0.25.0

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

@@ -1 +1 @@
-{"version":3,"file":"results.js","names":[],"sources":["../../../../plus/integrations/src/results.ts"],"sourcesContent":["import { isUnsupportedSortError } from '@gitkraken/provider-apis';\nimport { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '@gitlens/git/errors.js';\nimport type { IssueSorting } from '@gitlens/git/models/issue.js';\nimport type { PullRequestSorting } from '@gitlens/git/models/pullRequest.js';\nimport type { IntegrationIds } from './constants.js';\nimport { isProviderUnreachableError } from './errors.js';\nimport { UnexpectedResponseError } from './providers/providerErrors.js';\n\nexport interface ConnectionStateChangeEvent {\n\tkey: string;\n\treason: 'connected' | 'disconnected';\n}\n\n/**\n * A per-provider, per-connection warning surfaced alongside (partial) read results. Consumers use\n * these to drive auth recovery, retry, or truncation messaging without the read itself throwing.\n *\n * `kind` is the programmatic discriminant (a rate-limit is retryable, a 404 is not, an unsupported capability\n * never succeeds on retry, an auth failure needs re-connection unless {@link ProviderWarning.scope} confines\n * it); `isAuth` is retained as a convenience mirror of `kind === 'auth'`.\n *\n * `'unsupported'`: the provider — or this integration of it — lacks the capability the request asked for: a\n * surface (issues on Bitbucket, pull requests on an issue tracker, a batch read, org/repo discovery,\n * current-account lookup, project-scoped or account-wide issue reads), or a filter, sort, state, search\n * criterion or option combination it cannot express. Retrying the same request never succeeds; a different\n * provider, scope or request may. NOT unsupported (these stay `'other'`): malformed or contradictory caller\n * input the caller fixes in the request itself (a duplicate batch key, invalid target numbers, an empty owner,\n * an unusable scope), incompleteness or omission warnings, and unclassified errors.\n *\n * `'unreadable-items'`: the provider returned items this read could not read (a Jira issue whose fields the SDK cannot\n * parse), so it left them out and read everything else in the warning's {@link ProviderWarning.scope}. It still fails\n * the read (`fetchFailed`), since those items are missing, but retrying returns the same gap. On the reads that publish\n * it (an issue tracker's project reads) it never hides a read that was cut short: a cut always comes with a warning of\n * another kind. {@link ProviderWarning.unreadableItems} names the items left out.\n */\nexport type ProviderWarningKind =\n\t| 'auth'\n\t| 'rate-limit'\n\t| 'not-found'\n\t| 'no-connection'\n\t| 'unsupported'\n\t| 'unreadable-items'\n\t| 'other';\n\n/** The items an `'unreadable-items'` warning left out: see {@link ProviderWarning.unreadableItems}. */\nexport interface ProviderWarningUnreadableItems {\n\t/**\n\t * The provider's identifiers of the items left out (a Jira issue's key), without duplicates, in reported order. Each\n\t * one is an item the provider reported as skipped, so an identifier present is one that was left out, and one absent\n\t * was read when {@link complete}.\n\t *\n\t * Both hold only for the spelling the provider returned, which is also how a published issue's id spells its key: `keys`\n\t * doesn't answer a lookup by another spelling, such as a different case or the key an issue had before it moved. A\n\t * consumer comparing a key from elsewhere (one parsed from a branch name, say) must normalize the case of both sides,\n\t * and can't take an issue under a key it once had as read.\n\t */\n\tkeys: string[];\n\t/**\n\t * Whether {@link keys} names every item left out. `false` when an item left out had no key to report, when the\n\t * provider's report of them was malformed (no list of keys, or more than keys in it), or when it said items were left\n\t * out and named none, so an identifier absent from `keys` may still be one of them.\n\t */\n\tcomplete: boolean;\n}\n\n/**\n * Why a read that SUCCEEDED still withheld results:\n * - `provider-limit`: the provider refuses to serve past a cap it enforces (GitHub search's 1,000-result\n *   ceiling, Trello's `cards_limit`), so the excess is unreachable through that query.\n * - `recovery-budget`: the internal partitioned recovery stopped spending upstream requests before it ran\n *   out of partitions to visit.\n * - `pagination-incomplete`: pages were left unread — a sub-scope of a multi-scope read that was not drained,\n *   a drain that stopped at its own page backstop, or a provider that advertised another page and gave no way\n *   to reach it. These have DIFFERENT remedies, so the kind alone does not say whether more can be fetched;\n *   read {@link ProviderWarningOmission.recovery} for that.\n *\n * Mirrors the vocabulary the SDK reports. Declared here rather than imported so this module stays free of\n * `@gitkraken/provider-apis` types (see the export block in `index.ts`); `collectionMetadata.ts` holds the\n * compile-time link, so an SDK bump that adds a kind fails the build at that boundary.\n */\nexport type ProviderWarningOmissionKind = 'provider-limit' | 'recovery-budget' | 'pagination-incomplete';\n\n/**\n * How a consumer can recover omitted results. `page-budget` reruns with a larger budget; `narrow-scope`\n * requests a smaller server-side scope; `none` promises neither. Switch on the exact value because only\n * `page-budget` is a fetch-more action.\n */\nexport type ProviderWarningOmissionRecovery = 'none' | 'page-budget' | 'narrow-scope';\n\n/**\n * The part of a provider a warning is confined to: one resource (organization, workspace, site), project or\n * repository. All fields optional; see {@link ProviderWarning.scope} for when one is forwarded.\n */\nexport interface ProviderWarningScope {\n\t/**\n\t * The resource as the read addressed it: its id on most reads, its name on the few that address it by name\n\t * (Azure DevOps' repo-scoped reads, Bitbucket's workspace reads). Match it against both\n\t * `ProviderOrganization.id` and `name`, and a project's `orgId` where it has one.\n\t */\n\tresourceId?: string;\n\t/**\n\t * The project as the read addressed it. For a Jira project read, the key, on Jira Cloud and Jira Data Center alike\n\t * (the project's `name` in `listProjects`).\n\t */\n\tprojectId?: string;\n\trepositoryId?: string;\n}\n\n/**\n * The selector of an issue-tracker project read that matched nothing: see {@link ProviderWarning.selector}. `kind`\n * names which one missed, and `value` is that selector exactly as the caller passed it. `linearProject` is one of a\n * Linear read's `linearProjects`, an id the workspace's Projects no longer list.\n */\nexport interface ProviderWarningSelector {\n\tkind: 'org' | 'project' | 'linearProject';\n\tvalue: string;\n}\n\n/**\n * Why a provider request failed, when the failure itself says so:\n * - `unreachable`: a transport failure or server-side error prevented the provider from answering. The connection\n *   still exists; this accompanies `kind: 'other'`, never an authentication warning.\n * - `oauth-app-not-allowed`: the organization does not let third-party OAuth apps in. On Azure DevOps this is the\n *   organization policy \"Third-party application access via OAuth\", off by default for new organizations. An\n *   organization admin enables it, or the user connects with a personal access token instead, which the policy\n *   does not govern.\n * - `access-denied`: the account has no access to that organization or project (not a member, or lacking the\n *   permission). Someone who administers it has to grant access.\n * - `conditional-access`: a Microsoft Entra Conditional Access policy blocked the request (Azure DevOps\n *   `VS403463`). Its admin has to exempt the request, e.g. by location or device.\n * - `unexpected-response`: the provider answered, but not with data in the shape the read expects (a gateway's JSON\n *   error on a 2xx, an empty object, `null`), so the read could not use it. Accompanies `kind: 'other'`, like\n *   `unreachable`; a retry may succeed once the provider, or whatever answered in front of it, answers properly. A\n *   page served instead of data keeps its own message, without this cause.\n *\n * None of these is healed by reconnecting, which is the point of naming them.\n */\nexport type ProviderWarningCauseReason =\n\t| 'oauth-app-not-allowed'\n\t| 'access-denied'\n\t| 'conditional-access'\n\t| 'unreachable'\n\t| 'unexpected-response';\n\n/** See {@link ProviderWarning.cause}. */\nexport interface ProviderWarningCause {\n\treason: ProviderWarningCauseReason;\n\t/** The provider's own error code, when it reports one (Azure DevOps `TF400813`, `VS403463`). */\n\tcode?: string;\n\t/** Where the setting behind the refusal is changed, when this layer can address it. */\n\tremedyUrl?: string;\n}\n\n/** Which repository / project / resource an omission is attributed to. All fields optional; a scope may name none. */\nexport interface ProviderWarningOmissionScope extends ProviderWarningScope {\n\tproviderId?: string;\n}\n\nexport interface ProviderWarningOmission {\n\tkind: ProviderWarningOmissionKind;\n\t/**\n\t * Whether anything would fetch the missing items, and what. Gate a \"load more\" affordance on this rather\n\t * than on `kind` — see {@link ProviderWarningOmissionRecovery}.\n\t */\n\trecovery: ProviderWarningOmissionRecovery;\n\t/**\n\t * The cap the provider enforces, when it reports one. NOT a result count for every kind: on\n\t * `recovery-budget` this is a REQUEST budget and must not be shown to a user as a number of results.\n\t */\n\tlimit?: number;\n\t/** Total matches the provider reported, when it reports one. Only GitHub's search cap does today. */\n\ttotalCount?: number;\n\t/**\n\t * The order the reachable window was selected under, as `field:direction`, when the omission is a result\n\t * ceiling.\n\t *\n\t * Present so a consumer can word its own \"N matched, showing the first M\" without assuming WHICH M: the\n\t * provider serves the top M under this key, so the sentence is only true if it names it. Absent for every\n\t * omission that isn't a ceiling, where no window was selected by an order.\n\t *\n\t * A union of both vocabularies rather than the issue one alone: `PullRequestSorting` happens to be a subset\n\t * today, so narrowing this to {@link IssueSorting} would still compile while describing only half the reads\n\t * that set it — and would break the day the PR search gains a key the issue search has no name for.\n\t */\n\tsort?: IssueSorting | PullRequestSorting;\n\t/** Which repository / project / resource was affected, when one is attributed. */\n\tscope?: ProviderWarningOmissionScope;\n}\n\nexport interface ProviderWarning {\n\tproviderId: IntegrationIds;\n\t/** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */\n\tdomain?: string;\n\t/** The specific token/connection the read was pinned to, when a `connectionId` was supplied. */\n\tconnectionId?: string;\n\tmessage: string;\n\tkind: ProviderWarningKind;\n\t/** Convenience mirror of `kind === 'auth'`, scoped or not; read {@link scope} before prompting to reconnect. */\n\tisAuth: boolean;\n\t/**\n\t * Present when the failure was recorded against one sub-scope of the read (an organization, project or\n\t * repository) rather than against the connection. A scoped `auth` failure is that one scope refusing this\n\t * credential, e.g. an Azure DevOps organization that disallows third-party OAuth apps, one in another Entra\n\t * tenant, or a Conditional Access policy. Reconnecting cannot fix those, so this warning alone is no reason\n\t * to prompt for it.\n\t *\n\t * `kind` and `isAuth` are unaffected: a scoped 401 is still an authentication failure, and this field says\n\t * how far it reaches. It names at least one of its IDs, and is never set on an omission (which carries its\n\t * own {@link ProviderWarningOmission.scope}) or on a warning derived from a caught exception (see\n\t * {@link toProviderWarning}), even when that call targeted a single organization. The exception is a batch\n\t * read's refused target, which names its scope: the Azure DevOps organization and project, the repository on\n\t * other git hosts, or the tracker's resource.\n\t *\n\t * Its ABSENCE means account-wide or unattributed, so existing handling stays correct without it.\n\t *\n\t * A scoped `auth` failure also means the credential itself was accepted. A dead token can come back as nothing\n\t * but scoped refusals wherever a read reaches its scopes without an uncached request to the connection first:\n\t * discovery served from a per-token cache (Azure DevOps, Bitbucket, Jira Cloud) or an SDK fan-out across the\n\t * requested repositories (Bitbucket Data Center). So when a read's only auth failures are scoped, those providers\n\t * confirm the credential with one uncached check first, and a refused credential fails the whole read with an\n\t * unscoped `auth` warning. A batch read checks it only when every target was refused, since a target that\n\t * answered already proved it. A refusal the provider attributes to the credential itself, like Bitbucket's or Jira\n\t * Cloud's for a token missing the OAuth scopes a read needs, which a reconnect fixes, is published unscoped too,\n\t * once for the connection, while the scopes that answered keep their results.\n\t *\n\t * So the promise holds for a read that carries no unscoped `auth` warning of its own; one that does already asks\n\t * for a reconnect, and its other scoped refusals are not checked. Two exceptions stay scoped even then. A check\n\t * that could not complete or was denied (a network error, a throttle, a `403`, Bitbucket Data Center refusing a\n\t * credential it authenticated, or a Bitbucket Data Center project access token, whose user the check cannot\n\t * find) proves nothing, so the warnings are published unconfirmed, with no {@link cause}, and the next read\n\t * checks again. And a credential confirmed within the last minute is not probed again, so a revocation can take\n\t * up to a minute to surface.\n\t */\n\tscope?: ProviderWarningScope;\n\t/**\n\t * Why the provider request failed, when the failure itself says so: see {@link ProviderWarningCauseReason}. Switch on\n\t * `reason` to recommend a fix instead of a reconnect; `message` then carries the same explanation as prose.\n\t *\n\t * `unreachable` accompanies a transport or server failure with `kind: 'other'`, and `unexpected-response` a response\n\t * the read could not use, also with `kind: 'other'`. Credential refusal causes are set only on a scoped `auth`\n\t * warning whose credential was confirmed first (see {@link scope}), because the\n\t * refusals they name are indistinguishable from a dead credential until then: Azure DevOps answers a\n\t * third-party OAuth app its organization disallows exactly as it answers an expired token. Only Azure DevOps\n\t * reports one today. Its absence proves nothing about the cause.\n\t */\n\tcause?: ProviderWarningCause;\n\t/**\n\t * Present when this warning describes results the read could not return even though the request itself\n\t * SUCCEEDED — a provider-enforced cap, an exhausted recovery budget, a page budget, or a sub-scope the read\n\t * did not drain.\n\t *\n\t * Its presence is the signal: an omission is not a failure. Message it as incompleteness rather than as a\n\t * failed read, and do NOT derive that from `message`, which is English prose and subject to rewording.\n\t * `kind` stays `'other'` for these, so the failure discriminant keeps meaning exactly what it meant before\n\t * this field existed.\n\t *\n\t * Whether anything would fetch the rest is a SEPARATE question — read {@link ProviderWarningOmission.recovery},\n\t * not `kind`, and never assume a retry of the same request returns more.\n\t *\n\t * `limit` / `totalCount` / `scope` are forwarded only when they are reported; most omissions carry none of\n\t * the three, so render correctly without them — and see {@link ProviderWarningOmission.limit} before\n\t * showing that figure as a result count.\n\t *\n\t * Its ABSENCE proves nothing. It is never set on a warning derived from a caught exception (see\n\t * {@link toProviderWarning}) or from a structured scope failure — those are failures, and the field would\n\t * be a lie there. But it is also absent whenever incompleteness was reported without naming what was left\n\t * out, so treat a bare `kind: 'other'` warning as unclassified rather than as a proven failure.\n\t */\n\tomission?: ProviderWarningOmission;\n\t/**\n\t * Present exactly when {@link kind} is `'unreadable-items'`: which items the read left out because it could not read\n\t * them. A consumer deciding whether an identifier is absent from the provider, rather than merely unread, must find\n\t * it in no warning's `keys` and see `complete` on every one.\n\t */\n\tunreadableItems?: ProviderWarningUnreadableItems;\n\t/**\n\t * Present when an issue-tracker project read's `org` or `project` selector matched nothing the connection\n\t * discovered: the selection was removed, renamed, or is no longer visible to this connection. `kind` is\n\t * `'not-found'`, the page is empty and not `fetchFailed`, and it carries no cursor, since a retry finds the same.\n\t * A `linearProject` miss is diagnostic: the requested Project ids still filter the read, preserving issues in\n\t * other selected Projects. It therefore does not force an empty page or remove its continuation.\n\t *\n\t * Set only when discovery was complete. A read whose discovery failed or was truncated cannot tell a missing\n\t * selection from one it did not reach, so it keeps reporting that failure instead, without this field. A miss is\n\t * confirmed against the connection's lists as the provider holds them now, read without the cache, since a cached\n\t * one predates what was created since. A cached project list can still name a project deleted since: the tracker\n\t * refuses it (Jira's \"does not exist for the field 'project'\"), it reads as empty, and the refusal drops that list,\n\t * so the next read reports the miss. Jira Data Center's refusal counts only when it names the user it\n\t * authenticated: it answers a rejected token the same way, as the anonymous user. The miss waits on an account\n\t * lookup on a resource those lists name, which confirms the\n\t * connection's credential, and a failed lookup is reported as the read's failure instead; an account that lists no\n\t * resource at all has none to look up, and is judged on its lists alone.\n\t *\n\t * It is the discriminant: a `not-found` without it is a request that failed with a 404, 410 or 422.\n\t */\n\tselector?: ProviderWarningSelector;\n\t/**\n\t * The keys of the batch targets this warning concerns: the target a per-target failure was refused or failed\n\t * for, or every target of an integration call that failed as a whole. So a caller that sends several callers'\n\t * targets in one call can hand a failure only to the targets it belongs to.\n\t *\n\t * Its ABSENCE means the whole call. It is absent on every read that is not a batch read, and on a batch read's\n\t * refusal of the whole call before any target is read (a duplicate key, an invalid target, an unknown etag\n\t * include, no resolvable connection, the wrong surface), which concerns every target alike.\n\t *\n\t * It is not part of a warning's identity: two warnings that differ only here are one warning, for the union of\n\t * their targets (see {@link appendDedupedWarning}).\n\t */\n\ttargetKeys?: string[];\n}\n\nexport interface ProviderPageInfo {\n\t/**\n\t * The 1-based POSITION of the returned page. One convention across every paged read, page-number and\n\t * cursor paging alike, so a `getNextPageParam`-style consumer can key off it uniformly:\n\t * - the page number the provider itself reported, when it reports one (authoritative);\n\t * - else the position the caller addressed: the page encoded in a threaded page cursor, or the `page`\n\t *   supplied alongside an opaque cursor (1 when the caller supplied no `page`);\n\t * - else, for a read that can be advanced by page number, the requested `page` — the provider either\n\t *   honored it or the internal drain reached it (see the paging contract on `IntegrationManager`);\n\t * - else 1: a cursor-only read with no cursor threaded back ignores a requested page number and answers\n\t *   with its first page, so echoing the request would mislabel page 1 as page N.\n\t *\n\t * A page past the provider's terminal cursor still reports the requested `page` with empty `items` — an\n\t * empty page N, never page N-1 relabeled.\n\t *\n\t * Continue a cursor-paged read from `cursor`, NOT from `currentPage + 1`: a cursor-only host can't be\n\t * addressed by number, so this is a position label and not always a resumable request parameter.\n\t */\n\tcurrentPage: number;\n\t/**\n\t * The page size IN EFFECT, which is not always the one requested — it is whichever of these the read can\n\t * actually vouch for:\n\t * - the size the provider reported for the page it served (numbered-page hosts), else\n\t * - the `itemsPerPage` that was applied to the request (repo-scoped reads, which forward it), else\n\t * - `items.length`, for a read that takes no page size at all: the account-wide PR/issue reads, `listRepos`\n\t *   (cursor-only), and `listIssueTrackerIssuesPage`, whose `itemsPerPage` counts PROJECTS rather than issues.\n\t *\n\t * So it is a description of the page, not an echo of the request: don't derive a total from\n\t * `currentPage * itemsPerPage`, and don't read `items.length < itemsPerPage` as \"last page\" — `hasMore` /\n\t * `cursor` are the only continuation signals.\n\t */\n\titemsPerPage: number;\n\t/**\n\t * A COMPLETENESS assertion, not a mode flag: `true` only when a sweep drained every page of every target\n\t * without truncating or failing (`!truncated && !fetchFailed`). Set exclusively by `sweepPullRequests` /\n\t * `sweepClosedPullRequests` and absent on every paged read, so `allPages !== true` does NOT by itself mean\n\t * \"this was a single page\".\n\t *\n\t * This is the signal to gate on before caching a sweep as authoritative: unlike `truncated` it is `false`\n\t * for BOTH kinds of incompleteness, so it can't be misread as a benign cap.\n\t */\n\tallPages?: boolean;\n\t/**\n\t * True when the read stopped before it could confirm it had everything. Deliberately does NOT distinguish\n\t * WHY, and a consumer must not assume it means a provider ceiling — a sweep sets it from three different\n\t * origins:\n\t * - a provider-side ceiling or per-scope backstop propagated from below (e.g. GitHub Search's 1000-result\n\t *   cap): the missing items are NOT reachable, so this really is \"complete to the provider's limit\";\n\t * - the sweep's OWN `maxPages` cap (default 100) with a usable cursor still in hand: the missing items ARE\n\t *   reachable and were simply not fetched — raise `maxPages` to get them;\n\t * - the provider reporting another page but handing back no usable cursor: not reachable.\n\t *\n\t * Only the second is recoverable, and a sweep exposes no continuation cursor, so treating a truncated sweep\n\t * as a complete set silently drops reachable data in that case. Prefer `allPages` for the cache decision.\n\t */\n\ttruncated?: boolean;\n}\n\nexport interface ProviderResult<T> {\n\titems: T[];\n\twarnings: ProviderWarning[];\n\t/**\n\t * True when `items` is incomplete — distinguishes a failed or truncated flat read from a genuinely empty\n\t * result. Paged results additionally use `page.truncated` when a completed page could not confirm it\n\t * drained everything.\n\t */\n\tfetchFailed?: boolean;\n}\n\nexport interface ProviderPagedResult<T> extends ProviderResult<T> {\n\t/**\n\t * True when a request failed. Unlike `fetchFailed`, a collection read successfully that only left some of its items\n\t * unreadable doesn't set it; those items are named by their own warnings.\n\t */\n\trequestFailed?: boolean;\n\t/** True when the provider advertised continuation without a usable cursor or page position, or repeated one. */\n\tunexpectedGap?: boolean;\n\tpage: ProviderPageInfo;\n\thasMore: boolean;\n\t/**\n\t * Opaque cursor for cursor-based paging (GraphQL, per-repo/per-project cursors, etc.). For hosts that\n\t * require the previous page's cursor, consumers should pass this value back to the next `cursor` option.\n\t * A retry-only cursor may remain when `hasMore` is false: `hasMore` means automatic forward progress,\n\t * while explicitly reusing such a cursor retries failed work without creating an infinite paging loop.\n\t */\n\tcursor?: string;\n}\n\nexport interface ProviderSweepResult<T> extends ProviderResult<T> {\n\tpage: ProviderPageInfo;\n\thasMore: boolean;\n\t/**\n\t * Providers whose top-level read failed before returning any usable page. Partial per-scope failures stay\n\t * represented by `warnings` + `fetchFailed` and are intentionally excluded.\n\t */\n\tfailedProviderIds: IntegrationIds[];\n\t/**\n\t * Providers whose read started successfully but could not produce an authoritative complete slice (for\n\t * example, a later page failed, collection metadata reported a partial scope, or a paging backstop was hit).\n\t * Kept separate from\n\t * `failedProviderIds` so consumers can accept healthy sibling providers while preserving an older snapshot\n\t * for a provider whose returned slice has a gap.\n\t */\n\tincompleteProviderIds: IntegrationIds[];\n}\n\nexport interface ProviderBroadenResult<T> extends ProviderPagedResult<T> {\n\tbroadenedProviderIds: IntegrationIds[];\n\t/** Providers for which no requested org produced a usable issue result. */\n\tfailedProviderIds: IntegrationIds[];\n\t/** Providers with both a usable org result and at least one failed or truncated org slice. */\n\tincompleteProviderIds: IntegrationIds[];\n\tfanOutCount: number;\n}\n\nexport type RepositoryResolutionStatus =\n\t| 'resolved'\n\t| 'not-found'\n\t| 'unauthorized'\n\t| 'unsupported-provider'\n\t| 'invalid-remote-url'\n\t| 'host-mismatch'\n\t| 'undetermined';\n\nexport interface RepositoryIdentity {\n\tproviderId: IntegrationIds;\n\tdomain: string;\n\t/** The provider's canonical owner/namespace (follows renames), falling back to the parsed remote when omitted. */\n\towner: string;\n\t/** The provider's canonical repo name (follows renames), falling back to the parsed remote when omitted. */\n\tname: string;\n\tproject?: string;\n\t/** The original input remote URL, so the caller can key the resolution back to the remote it asked about. */\n\tremoteUrl: string;\n\t/**\n\t * True when the provider's canonical owner/name differ from what the input remote URL carried — i.e. the\n\t * repo was renamed/moved host-side and the local remote is stale. Case-insensitive, mirroring gkcli's\n\t * `EqualFold` compare so hosts that echo the input casing (e.g. Bitbucket Server/Azure) aren't flagged.\n\t */\n\trenamed: boolean;\n}\n\nexport interface RepositoryResolution {\n\tstatus: RepositoryResolutionStatus;\n\tidentity?: RepositoryIdentity;\n\twarning?: ProviderWarning;\n}\n\nexport interface ResolveRepositoryResult {\n\tresolution: RepositoryResolution;\n}\n\nconst maxProviderWarningMessageLength = 500;\n\n/** A caught error's message as a warning can carry it: an HTML page becomes its status, and prose is capped. */\nexport function providerWarningMessage(ex: unknown): string {\n\tconst raw = (ex instanceof Error ? ex.message : String(ex)).trim();\n\tconst carrier = ex as { status?: unknown; response?: { status?: unknown } } | null | undefined;\n\tconst status =\n\t\ttypeof carrier?.status === 'number'\n\t\t\t? carrier.status\n\t\t\t: typeof carrier?.response?.status === 'number'\n\t\t\t\t? carrier.response.status\n\t\t\t\t: undefined;\n\n\t// Gateways commonly answer API requests with a complete HTML error page. That payload is neither actionable\n\t// nor suitable for a warning DTO consumed by UIs and logs; preserve the status without leaking the document.\n\tif (/<(?:!doctype\\s+html|html|head|body)\\b/i.test(raw)) {\n\t\treturn status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';\n\t}\n\n\tif (!raw) {\n\t\treturn status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';\n\t}\n\treturn raw.length > maxProviderWarningMessageLength\n\t\t? `${raw.slice(0, maxProviderWarningMessageLength - 3)}...`\n\t\t: raw;\n}\n\n/**\n * Normalized org/workspace/group shape returned by the provider facade.\n * `name` is the provider identifier to pass to follow-up reads (a Jira project's key), while `org` is an optional\n * display label of the parent. Where that label can't address the parent, `orgId` is the parent's stable id to pass\n * as `org` instead (a Jira site's id, or a Data Center instance's domain).\n *\n * Jira site rows (`listOrgs`) are the exception: their `name` is the site's label, and a Jira read selects a site only\n * by its `id` (or a project row's `orgId`).\n */\nexport interface ProviderOrganization {\n\tid: string;\n\tproviderId: IntegrationIds;\n\tname: string;\n\torg?: string;\n\torgId?: string;\n\turl: string;\n}\n\n/**\n * A Linear Project (Linear's own `Project` entity, which can span several teams), as `listLinearProjects` lists it.\n * Distinct from the teams `listProjects` publishes for Linear: pass its `id` to `listIssueTrackerIssuesPage`'s\n * `linearProjects` to narrow an issue read to it.\n */\nexport interface ProviderLinearProjectShape {\n\tid: string;\n\tproviderId: IntegrationIds;\n\tname: string;\n\t/** Linear's project state, as Linear names it (e.g. `planned`, `started`, `paused`, `completed`, `canceled`). */\n\tstate: string;\n\turl: string;\n}\n\n/** Normalized repository shape returned by the provider facade. */\nexport interface ProviderRepositoryShape {\n\tid: string;\n\tnamespace: string;\n\tname: string;\n\t/** Azure DevOps project; `undefined` for hosts without a project layer. */\n\tproject?: string;\n\t/** Web (browser) URL, when the provider exposes it. */\n\turl?: string;\n\t/** HTTPS clone URL, when available. */\n\tcloneUrlHttps?: string;\n\t/** SSH clone URL, when available. */\n\tcloneUrlSsh?: string;\n\t/** Default branch name, when the provider reports it. */\n\tdefaultBranch?: string;\n}\n\n/**\n * Classifies a caught provider exception into a neutral {@link ProviderWarning}. Ordering matters:\n * `instanceof` is checked most-specific-first so a rate-limit isn't mislabeled as a generic error and\n * a 404 isn't mislabeled as auth.\n */\nexport function toProviderWarning(\n\tproviderId: IntegrationIds,\n\tdomain: string | undefined,\n\tconnectionId: string | undefined,\n\tex: unknown,\n): ProviderWarning {\n\tlet kind: ProviderWarning['kind'];\n\tif (ex instanceof AuthenticationError) {\n\t\tkind = 'auth';\n\t} else if (ex instanceof RequestRateLimitError) {\n\t\tkind = 'rate-limit';\n\t} else if (ex instanceof RequestNotFoundError) {\n\t\tkind = 'not-found';\n\t} else if (isUnsupportedSortError(ex)) {\n\t\tkind = 'unsupported';\n\t} else {\n\t\tkind = 'other';\n\t}\n\n\tconst cause = kind === 'other' ? getRequestFailureCause(ex) : undefined;\n\treturn {\n\t\tproviderId: providerId,\n\t\tdomain: domain,\n\t\tconnectionId: connectionId,\n\t\tmessage: providerWarningMessage(ex),\n\t\tkind: kind,\n\t\tisAuth: kind === 'auth',\n\t\t...(cause != null ? { cause: cause } : {}),\n\t};\n}\n\n/**\n * The cause a failed request's error names by itself, one that isn't the credential's (`unexpected-response` or\n * `unreachable`), for a failure classified as no more specific than that.\n */\nexport function getRequestFailureCause(ex: unknown): ProviderWarningCause | undefined {\n\tif (UnexpectedResponseError.is(ex)) return { reason: 'unexpected-response' };\n\tif (isProviderUnreachableError(ex)) return { reason: 'unreachable' };\n\treturn undefined;\n}\n\n/**\n * A scope's identity, as the stable string that keys it.\n *\n * The single definition of what \"the same scope\" means, shared by the failure and omission dedup keys in\n * `providerPaging.ts` and by {@link providerWarningKey} below, so a scope gaining a field is one edit rather\n * than three. `providerId` is included: the same repository ID under two providers is two scopes.\n *\n * The parameter is structural rather than the SDK's `CollectionScope` so this module keeps naming no\n * `@gitkraken/provider-apis` types (see the export block in `index.ts`) while still serving its SDK-facing\n * callers, which pass that type in unchanged.\n */\nexport function collectionScopeKey(scope: ProviderWarningOmissionScope | undefined): string {\n\treturn [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(\n\t\t' ',\n\t);\n}\n\n/**\n * The omission's contribution to a warning's identity — empty when there is none, so a warning without an\n * omission keeps deduping exactly as it did before the field existed.\n *\n * Two omissions of different kinds do produce different `message` values today, so message alone would still\n * separate them. That is incidental: the premise of `omission` is that consumers must not depend on prose\n * carrying the distinguishing fact, and this key must not either.\n */\nfunction providerWarningOmissionKey(omission: ProviderWarningOmission | undefined): string {\n\tif (omission == null) return '';\n\n\treturn [\n\t\tomission.kind,\n\t\tomission.recovery,\n\t\tomission.limit ?? '',\n\t\tomission.totalCount ?? '',\n\t\tcollectionScopeKey(omission.scope),\n\t].join(' ');\n}\n\n/**\n * Strips the omission from every warning in `warnings` when the read as a whole failed.\n *\n * An omission asserts the request SUCCEEDED, and a drain only learns it failed AFTER it may have emitted one:\n * an early page can report its own truncation and then a later page can die. Deciding per warning, at the\n * moment each is built, cannot see that future — so the aggregate is reconciled once, here, where\n * `fetchFailed` is final. Call it at the point a read returns its `fetchFailed`.\n *\n * Re-dedupes as it goes: the omission is part of a warning's identity, so two warnings that differed only\n * there become identical once it is gone, and the array's contract is that no two entries are equal.\n *\n * Mutates in place: the warning array is the one being returned, and callers accumulate into it across pages.\n */\nexport function reconcileOmissionsWithFailure(warnings: ProviderWarning[], fetchFailed: boolean): void {\n\tif (!fetchFailed || !warnings.some(w => w.omission != null)) return;\n\n\tconst reconciled: ProviderWarning[] = [];\n\tfor (const warning of warnings) {\n\t\tif (warning.omission == null) {\n\t\t\tappendDedupedWarning(reconciled, warning);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst { omission: _omission, ...rest } = warning;\n\t\tappendDedupedWarning(reconciled, rest);\n\t}\n\n\twarnings.splice(0, warnings.length, ...reconciled);\n}\n\n/**\n * A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes.\n *\n * The scope and the cause are keyed for the reason the omission is (see {@link providerWarningOmissionKey}): today's\n * failure messages happen to spell them out, but two failures that differ in either must stay two warnings even if\n * they don't.\n *\n * `message` stays LAST. It is the only free-form segment — provider prose, spaces and all — so anything\n * appended after it could be impersonated by a message that happens to end in the same text.\n */\nfunction providerWarningKey(warning: ProviderWarning): string {\n\treturn [\n\t\twarning.providerId,\n\t\twarning.connectionId ?? '',\n\t\twarning.domain ?? '',\n\t\twarning.kind,\n\t\tcollectionScopeKey(warning.scope),\n\t\twarning.cause?.reason ?? '',\n\t\tproviderWarningOmissionKey(warning.omission),\n\t\twarning.selector != null ? JSON.stringify([warning.selector.kind, warning.selector.value]) : '',\n\t\twarning.message,\n\t].join(' ');\n}\n\n/**\n * Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message, plus the\n * structured scope, cause, omission and selector when present) is absent. An equal warning already there merges its\n * {@link ProviderWarning.targetKeys} with the new one's instead: the union of both, or none when either concerns\n * the whole call. Its {@link ProviderWarning.unreadableItems} merge too (see {@link mergeUnreadableItems}): two reads\n * can report the same text for different items. The existing warning is replaced, never mutated, since it may be\n * shared.\n */\nexport function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void {\n\tconst key = providerWarningKey(warning);\n\tconst index = into.findIndex(existing => providerWarningKey(existing) === key);\n\tif (index === -1) {\n\t\tinto.push(warning);\n\t\treturn;\n\t}\n\n\tconst existing = into[index];\n\tconst targetKeys = mergeTargetKeys(existing.targetKeys, warning.targetKeys);\n\tconst unreadableItems =\n\t\texisting.unreadableItems != null && warning.unreadableItems != null\n\t\t\t? mergeUnreadableItems(existing.unreadableItems, warning.unreadableItems)\n\t\t\t: (existing.unreadableItems ?? warning.unreadableItems);\n\tif (targetKeys === existing.targetKeys && unreadableItems === existing.unreadableItems) return;\n\n\tconst { targetKeys: _, ...rest } = existing;\n\tinto[index] = {\n\t\t...rest,\n\t\t...(targetKeys != null ? { targetKeys: targetKeys } : {}),\n\t\t...(unreadableItems != null ? { unreadableItems: unreadableItems } : {}),\n\t};\n}\n\n/** The union of two warnings' target keys, or none when either concerns the whole call. `existing` when unchanged. */\nfunction mergeTargetKeys(existing: string[] | undefined, next: string[] | undefined): string[] | undefined {\n\t// Either concerns the whole call.\n\tif (existing == null || next == null) return undefined;\n\n\tconst added = next.filter(k => !existing.includes(k));\n\tif (!added.length) return existing;\n\n\treturn [...existing, ...new Set(added)];\n}\n\n/**\n * The items two reports of unreadable items left out together: the union of their keys, complete only when both are.\n * `existing` when `next` adds nothing to it.\n */\nexport function mergeUnreadableItems(\n\texisting: ProviderWarningUnreadableItems,\n\tnext: ProviderWarningUnreadableItems,\n): ProviderWarningUnreadableItems {\n\tconst known = new Set(existing.keys);\n\tconst added = next.keys.filter(k => !known.has(k));\n\tconst complete = existing.complete && next.complete;\n\tif (!added.length && complete === existing.complete) return existing;\n\n\treturn { keys: [...existing.keys, ...new Set(added)], complete: complete };\n}\n"],"mappings":"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"}
+{"version":3,"file":"results.js","names":[],"sources":["../../../../plus/integrations/src/results.ts"],"sourcesContent":["import { isUnsupportedSortError } from '@gitkraken/provider-apis';\nimport { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '@gitlens/git/errors.js';\nimport type { IssueSorting } from '@gitlens/git/models/issue.js';\nimport type { PullRequestSorting } from '@gitlens/git/models/pullRequest.js';\nimport type { IntegrationIds } from './constants.js';\nimport { isProviderUnreachableError } from './errors.js';\nimport { UnexpectedResponseError } from './providers/providerErrors.js';\n\nexport interface ConnectionStateChangeEvent {\n\tkey: string;\n\treason: 'connected' | 'disconnected';\n}\n\n/**\n * A per-provider, per-connection warning surfaced alongside (partial) read results. Consumers use\n * these to drive auth recovery, retry, or truncation messaging without the read itself throwing.\n *\n * `kind` is the programmatic discriminant (a rate-limit is retryable, a 404 is not, an unsupported capability\n * never succeeds on retry, an auth failure needs re-connection unless {@link ProviderWarning.scope} confines\n * it); `isAuth` is retained as a convenience mirror of `kind === 'auth'`.\n *\n * `'unsupported'`: the provider — or this integration of it — lacks the capability the request asked for: a\n * surface (issues on Bitbucket, pull requests on an issue tracker, a batch read, org/repo discovery,\n * current-account lookup, project-scoped or account-wide issue reads), or a filter, sort, state, search\n * criterion or option combination it cannot express. Retrying the same request never succeeds; a different\n * provider, scope or request may. NOT unsupported (these stay `'other'`): malformed or contradictory caller\n * input the caller fixes in the request itself (a duplicate batch key, invalid target numbers, an empty owner,\n * an unusable scope), incompleteness or omission warnings, and unclassified errors.\n *\n * `'unreadable-items'`: the provider returned items this read could not read (a Jira issue whose fields the SDK cannot\n * parse), so it left them out and read everything else in the warning's {@link ProviderWarning.scope}. It still fails\n * the read (`fetchFailed`), since those items are missing, but retrying returns the same gap. On the reads that publish\n * it (an issue tracker's project reads) it never hides a read that was cut short: a cut always comes with a warning of\n * another kind. {@link ProviderWarning.unreadableItems} names the items left out.\n */\nexport type ProviderWarningKind =\n\t| 'auth'\n\t| 'rate-limit'\n\t| 'not-found'\n\t| 'no-connection'\n\t| 'unsupported'\n\t| 'unreadable-items'\n\t| 'other';\n\n/** The items an `'unreadable-items'` warning left out: see {@link ProviderWarning.unreadableItems}. */\nexport interface ProviderWarningUnreadableItems {\n\t/**\n\t * The provider's identifiers of the items left out (a Jira issue's key), without duplicates, in reported order. Each\n\t * one is an item the provider reported as skipped, so an identifier present is one that was left out, and one absent\n\t * was read when {@link complete}.\n\t *\n\t * Both hold only for the spelling the provider returned, which is also how a published issue's id spells its key: `keys`\n\t * doesn't answer a lookup by another spelling, such as a different case or the key an issue had before it moved. A\n\t * consumer comparing a key from elsewhere (one parsed from a branch name, say) must normalize the case of both sides,\n\t * and can't take an issue under a key it once had as read.\n\t */\n\tkeys: string[];\n\t/**\n\t * Whether {@link keys} names every item left out. `false` when an item left out had no key to report, when the\n\t * provider's report of them was malformed (no list of keys, or more than keys in it), or when it said items were left\n\t * out and named none, so an identifier absent from `keys` may still be one of them.\n\t */\n\tcomplete: boolean;\n}\n\n/**\n * Why a read that SUCCEEDED still withheld results:\n * - `provider-limit`: the provider refuses to serve past a cap it enforces (GitHub search's 1,000-result\n *   ceiling, Trello's `cards_limit`), so the excess is unreachable through that query.\n * - `recovery-budget`: the internal partitioned recovery stopped spending upstream requests before it ran\n *   out of partitions to visit.\n * - `pagination-incomplete`: pages were left unread — a sub-scope of a multi-scope read that was not drained,\n *   a drain that stopped at its own page backstop, or a provider that advertised another page and gave no way\n *   to reach it. These have DIFFERENT remedies, so the kind alone does not say whether more can be fetched;\n *   read {@link ProviderWarningOmission.recovery} for that.\n *\n * Mirrors the vocabulary the SDK reports. Declared here rather than imported so this module stays free of\n * `@gitkraken/provider-apis` types (see the export block in `index.ts`); `collectionMetadata.ts` holds the\n * compile-time link, so an SDK bump that adds a kind fails the build at that boundary.\n */\nexport type ProviderWarningOmissionKind = 'provider-limit' | 'recovery-budget' | 'pagination-incomplete';\n\n/**\n * How a consumer can recover omitted results. `page-budget` reruns with a larger budget; `narrow-scope`\n * requests a smaller server-side scope; `none` promises neither. Switch on the exact value because only\n * `page-budget` is a fetch-more action.\n */\nexport type ProviderWarningOmissionRecovery = 'none' | 'page-budget' | 'narrow-scope';\n\n/**\n * The part of a provider a warning is confined to: one resource (organization, workspace, site), project or\n * repository. All fields optional; see {@link ProviderWarning.scope} for when one is forwarded.\n */\nexport interface ProviderWarningScope {\n\t/**\n\t * The resource as the read addressed it: its id on most reads, its name on the few that address it by name\n\t * (Azure DevOps' repo-scoped reads, Bitbucket's workspace reads). Match it against both\n\t * `ProviderOrganization.id` and `name`, and a project's `orgId` where it has one.\n\t */\n\tresourceId?: string;\n\t/**\n\t * The project as the read addressed it. For a Jira project read, the key, on Jira Cloud and Jira Data Center alike\n\t * (the project's `name` in `listProjects`).\n\t */\n\tprojectId?: string;\n\trepositoryId?: string;\n}\n\n/**\n * The selector of an issue-tracker project read that matched nothing: see {@link ProviderWarning.selector}. `kind`\n * names which one missed, and `value` is that selector exactly as the caller passed it. `linearProject` is one of a\n * Linear read's `linearProjects`, an id the workspace's Projects no longer list.\n */\nexport interface ProviderWarningSelector {\n\tkind: 'org' | 'project' | 'linearProject';\n\tvalue: string;\n}\n\n/**\n * Why a provider request failed, when the failure itself says so:\n * - `unreachable`: a transport failure or server-side error prevented the provider from answering. The connection\n *   still exists; this accompanies `kind: 'other'`, never an authentication warning.\n * - `oauth-app-not-allowed`: the organization does not let third-party OAuth apps in. On Azure DevOps this is the\n *   organization policy \"Third-party application access via OAuth\", off by default for new organizations. An\n *   organization admin enables it, or the user connects with a personal access token instead, which the policy\n *   does not govern.\n * - `access-denied`: the account has no access to that organization or project (not a member, or lacking the\n *   permission). Someone who administers it has to grant access.\n * - `conditional-access`: a Microsoft Entra Conditional Access policy blocked the request (Azure DevOps\n *   `VS403463`). Its admin has to exempt the request, e.g. by location or device.\n * - `unexpected-response`: the provider answered, but not with data in the shape the read expects (a gateway's JSON\n *   error on a 2xx, an empty object, `null`), so the read could not use it. Accompanies `kind: 'other'`, like\n *   `unreachable`; a retry may succeed once the provider, or whatever answered in front of it, answers properly. A\n *   page served instead of data keeps its own message, without this cause.\n *\n * None of these is healed by reconnecting, which is the point of naming them.\n */\nexport type ProviderWarningCauseReason =\n\t| 'oauth-app-not-allowed'\n\t| 'access-denied'\n\t| 'conditional-access'\n\t| 'unreachable'\n\t| 'unexpected-response';\n\n/** See {@link ProviderWarning.cause}. */\nexport interface ProviderWarningCause {\n\treason: ProviderWarningCauseReason;\n\t/** The provider's own error code, when it reports one (Azure DevOps `TF400813`, `VS403463`). */\n\tcode?: string;\n\t/** Where the setting behind the refusal is changed, when this layer can address it. */\n\tremedyUrl?: string;\n}\n\n/** Which repository / project / resource an omission is attributed to. All fields optional; a scope may name none. */\nexport interface ProviderWarningOmissionScope extends ProviderWarningScope {\n\tproviderId?: string;\n}\n\nexport interface ProviderWarningOmission {\n\tkind: ProviderWarningOmissionKind;\n\t/**\n\t * Whether anything would fetch the missing items, and what. Gate a \"load more\" affordance on this rather\n\t * than on `kind` — see {@link ProviderWarningOmissionRecovery}.\n\t */\n\trecovery: ProviderWarningOmissionRecovery;\n\t/**\n\t * The cap the provider enforces, when it reports one. NOT a result count for every kind: on\n\t * `recovery-budget` this is a REQUEST budget and must not be shown to a user as a number of results.\n\t */\n\tlimit?: number;\n\t/** Total matches the provider reported, when it reports one. Only GitHub's search cap does today. */\n\ttotalCount?: number;\n\t/**\n\t * The order the reachable window was selected under, as `field:direction`, when the omission is a result\n\t * ceiling.\n\t *\n\t * Present so a consumer can word its own \"N matched, showing the first M\" without assuming WHICH M: the\n\t * provider serves the top M under this key, so the sentence is only true if it names it. Absent for every\n\t * omission that isn't a ceiling, where no window was selected by an order.\n\t *\n\t * A union of both vocabularies rather than the issue one alone: `PullRequestSorting` happens to be a subset\n\t * today, so narrowing this to {@link IssueSorting} would still compile while describing only half the reads\n\t * that set it — and would break the day the PR search gains a key the issue search has no name for.\n\t */\n\tsort?: IssueSorting | PullRequestSorting;\n\t/** Which repository / project / resource was affected, when one is attributed. */\n\tscope?: ProviderWarningOmissionScope;\n}\n\nexport interface ProviderWarning {\n\tproviderId: IntegrationIds;\n\t/** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */\n\tdomain?: string;\n\t/** The specific token/connection the read was pinned to, when a `connectionId` was supplied. */\n\tconnectionId?: string;\n\tmessage: string;\n\tkind: ProviderWarningKind;\n\t/** Convenience mirror of `kind === 'auth'`, scoped or not; read {@link scope} before prompting to reconnect. */\n\tisAuth: boolean;\n\t/**\n\t * Present when the failure was recorded against one sub-scope of the read (an organization, project or\n\t * repository) rather than against the connection. A scoped `auth` failure is that one scope refusing this\n\t * credential, e.g. an Azure DevOps organization that disallows third-party OAuth apps, one in another Entra\n\t * tenant, or a Conditional Access policy. Reconnecting cannot fix those, so this warning alone is no reason\n\t * to prompt for it.\n\t *\n\t * `kind` and `isAuth` are unaffected: a scoped 401 is still an authentication failure, and this field says\n\t * how far it reaches. It names at least one of its IDs, and is never set on an omission (which carries its\n\t * own {@link ProviderWarningOmission.scope}) or on a warning derived from a caught exception (see\n\t * {@link toProviderWarning}), even when that call targeted a single organization. The exception is a batch\n\t * read's refused target, which names its scope: the Azure DevOps organization and project, the repository on\n\t * other git hosts, or the tracker's resource.\n\t *\n\t * Its ABSENCE means account-wide or unattributed, so existing handling stays correct without it.\n\t *\n\t * A scoped `auth` failure also means the credential itself was accepted. A dead token can come back as nothing\n\t * but scoped refusals wherever a read reaches its scopes without an uncached request to the connection first:\n\t * discovery served from a per-token cache (Azure DevOps, Bitbucket, Jira Cloud) or an SDK fan-out across the\n\t * requested repositories (Bitbucket Data Center). So when a read's only auth failures are scoped, those providers\n\t * confirm the credential with one uncached check first, and a refused credential fails the whole read with an\n\t * unscoped `auth` warning. A batch read checks it only when every target was refused, since a target that\n\t * answered already proved it. A refusal the provider attributes to the credential itself, like Bitbucket's or Jira\n\t * Cloud's for a token missing the OAuth scopes a read needs, which a reconnect fixes, is published unscoped too,\n\t * once for the connection, while the scopes that answered keep their results.\n\t *\n\t * So the promise holds for a read that carries no unscoped `auth` warning of its own; one that does already asks\n\t * for a reconnect, and its other scoped refusals are not checked. Two exceptions stay scoped even then. A check\n\t * that could not complete or was denied (a network error, a throttle, a `403`, Bitbucket Data Center refusing a\n\t * credential it authenticated, or a Bitbucket Data Center project access token, whose user the check cannot\n\t * find) proves nothing, so the warnings are published unconfirmed, with no {@link cause}, and the next read\n\t * checks again. And a credential confirmed within the last minute is not probed again, so a revocation can take\n\t * up to a minute to surface.\n\t */\n\tscope?: ProviderWarningScope;\n\t/**\n\t * Why the provider request failed, when the failure itself says so: see {@link ProviderWarningCauseReason}. Switch on\n\t * `reason` to recommend a fix instead of a reconnect; `message` then carries the same explanation as prose.\n\t *\n\t * `unreachable` accompanies a transport or server failure with `kind: 'other'`, and `unexpected-response` a response\n\t * the read could not use, also with `kind: 'other'`. Credential refusal causes are set only on a scoped `auth`\n\t * warning whose credential was confirmed first (see {@link scope}), because the\n\t * refusals they name are indistinguishable from a dead credential until then: Azure DevOps answers a\n\t * third-party OAuth app its organization disallows exactly as it answers an expired token. Only Azure DevOps\n\t * reports one today. Its absence proves nothing about the cause.\n\t */\n\tcause?: ProviderWarningCause;\n\t/**\n\t * Present when this warning describes results the read could not return even though the request itself\n\t * SUCCEEDED — a provider-enforced cap, an exhausted recovery budget, a page budget, or a sub-scope the read\n\t * did not drain.\n\t *\n\t * Its presence is the signal: an omission is not a failure. Message it as incompleteness rather than as a\n\t * failed read, and do NOT derive that from `message`, which is English prose and subject to rewording.\n\t * `kind` stays `'other'` for these, so the failure discriminant keeps meaning exactly what it meant before\n\t * this field existed.\n\t *\n\t * Whether anything would fetch the rest is a SEPARATE question — read {@link ProviderWarningOmission.recovery},\n\t * not `kind`, and never assume a retry of the same request returns more.\n\t *\n\t * `limit` / `totalCount` / `scope` are forwarded only when they are reported; most omissions carry none of\n\t * the three, so render correctly without them — and see {@link ProviderWarningOmission.limit} before\n\t * showing that figure as a result count.\n\t *\n\t * Its ABSENCE proves nothing. It is never set on a warning derived from a caught exception (see\n\t * {@link toProviderWarning}) or from a structured scope failure — those are failures, and the field would\n\t * be a lie there. But it is also absent whenever incompleteness was reported without naming what was left\n\t * out, so treat a bare `kind: 'other'` warning as unclassified rather than as a proven failure.\n\t */\n\tomission?: ProviderWarningOmission;\n\t/**\n\t * Present exactly when {@link kind} is `'unreadable-items'`: which items the read left out because it could not read\n\t * them. A consumer deciding whether an identifier is absent from the provider, rather than merely unread, must find\n\t * it in no warning's `keys` and see `complete` on every one.\n\t */\n\tunreadableItems?: ProviderWarningUnreadableItems;\n\t/**\n\t * Present when an issue-tracker project read's `org` or `project` selector matched nothing the connection\n\t * discovered: the selection was removed, renamed, or is no longer visible to this connection. `kind` is\n\t * `'not-found'`, the page is empty and not `fetchFailed`, and it carries no cursor, since a retry finds the same.\n\t * A `linearProject` miss is diagnostic: the requested Project ids still filter the read, preserving issues in\n\t * other selected Projects. It therefore does not force an empty page or remove its continuation.\n\t *\n\t * Set only when discovery was complete. A read whose discovery failed or was truncated cannot tell a missing\n\t * selection from one it did not reach, so it keeps reporting that failure instead, without this field. A miss is\n\t * confirmed against the connection's lists as the provider holds them now, read without the cache, since a cached\n\t * one predates what was created since. A cached project list can still name a project deleted since: the tracker\n\t * refuses it (Jira's \"does not exist for the field 'project'\"), it reads as empty, and the refusal drops that list,\n\t * so the next read reports the miss. Jira Data Center's refusal counts only when it names the user it\n\t * authenticated: it answers a rejected token the same way, as the anonymous user. The miss waits on an account\n\t * lookup on a resource those lists name, which confirms the\n\t * connection's credential, and a failed lookup is reported as the read's failure instead; an account that lists no\n\t * resource at all has none to look up, and is judged on its lists alone.\n\t *\n\t * It is the discriminant: a `not-found` without it is a request that failed with a 404, 410 or 422.\n\t */\n\tselector?: ProviderWarningSelector;\n\t/**\n\t * The keys of the batch targets this warning concerns: the target a per-target failure was refused or failed\n\t * for, or every target of an integration call that failed as a whole. So a caller that sends several callers'\n\t * targets in one call can hand a failure only to the targets it belongs to.\n\t *\n\t * Its ABSENCE means the whole call. It is absent on every read that is not a batch read, and on a batch read's\n\t * refusal of the whole call before any target is read (a duplicate key, an invalid target, an unknown etag\n\t * include, no resolvable connection, the wrong surface), which concerns every target alike.\n\t *\n\t * It is not part of a warning's identity: two warnings that differ only here are one warning, for the union of\n\t * their targets (see {@link appendDedupedWarning}).\n\t */\n\ttargetKeys?: string[];\n}\n\nexport interface ProviderPageInfo {\n\t/**\n\t * The 1-based POSITION of the returned page. One convention across every paged read, page-number and\n\t * cursor paging alike, so a `getNextPageParam`-style consumer can key off it uniformly:\n\t * - the page number the provider itself reported, when it reports one (authoritative);\n\t * - else the position the caller addressed: the page encoded in a threaded page cursor, or the `page`\n\t *   supplied alongside an opaque cursor (1 when the caller supplied no `page`);\n\t * - else, for a read that can be advanced by page number, the requested `page` — the provider either\n\t *   honored it or the internal drain reached it (see the paging contract on `IntegrationManager`);\n\t * - else 1: a cursor-only read with no cursor threaded back ignores a requested page number and answers\n\t *   with its first page, so echoing the request would mislabel page 1 as page N.\n\t *\n\t * A page past the provider's terminal cursor still reports the requested `page` with empty `items` — an\n\t * empty page N, never page N-1 relabeled.\n\t *\n\t * Continue a cursor-paged read from `cursor`, NOT from `currentPage + 1`: a cursor-only host can't be\n\t * addressed by number, so this is a position label and not always a resumable request parameter.\n\t */\n\tcurrentPage: number;\n\t/**\n\t * The page size IN EFFECT, which is not always the one requested — it is whichever of these the read can\n\t * actually vouch for:\n\t * - the size the provider reported for the page it served (numbered-page hosts), else\n\t * - the `itemsPerPage` that was applied to the request (repo-scoped reads, which forward it), else\n\t * - `items.length`, for a read that takes no page size at all: the account-wide PR/issue reads, `listRepos`\n\t *   (cursor-only), and `listIssueTrackerIssuesPage`, whose `itemsPerPage` counts PROJECTS rather than issues.\n\t *\n\t * So it is a description of the page, not an echo of the request: don't derive a total from\n\t * `currentPage * itemsPerPage`, and don't read `items.length < itemsPerPage` as \"last page\" — `hasMore` /\n\t * `cursor` are the only continuation signals.\n\t */\n\titemsPerPage: number;\n\t/**\n\t * A COMPLETENESS assertion, not a mode flag: `true` only when a sweep drained every page of every target\n\t * without truncating or failing (`!truncated && !fetchFailed`). Set exclusively by `sweepPullRequests` /\n\t * `sweepClosedPullRequests` and absent on every paged read, so `allPages !== true` does NOT by itself mean\n\t * \"this was a single page\".\n\t *\n\t * This is the signal to gate on before caching a sweep as authoritative: unlike `truncated` it is `false`\n\t * for BOTH kinds of incompleteness, so it can't be misread as a benign cap.\n\t */\n\tallPages?: boolean;\n\t/**\n\t * True when the read stopped before it could confirm it had everything. Deliberately does NOT distinguish\n\t * WHY, and a consumer must not assume it means a provider ceiling — a sweep sets it from three different\n\t * origins:\n\t * - a provider-side ceiling or per-scope backstop propagated from below (e.g. GitHub Search's 1000-result\n\t *   cap): the missing items are NOT reachable, so this really is \"complete to the provider's limit\";\n\t * - the sweep's OWN `maxPages` cap (default 100) with a usable cursor still in hand: the missing items ARE\n\t *   reachable and were simply not fetched — raise `maxPages` to get them;\n\t * - the provider reporting another page but handing back no usable cursor: not reachable.\n\t *\n\t * Only the second is recoverable, and a sweep exposes no continuation cursor, so treating a truncated sweep\n\t * as a complete set silently drops reachable data in that case. Prefer `allPages` for the cache decision.\n\t */\n\ttruncated?: boolean;\n}\n\nexport interface ProviderResult<T> {\n\titems: T[];\n\twarnings: ProviderWarning[];\n\t/**\n\t * True when `items` is incomplete — distinguishes a failed or truncated flat read from a genuinely empty\n\t * result. Paged results additionally use `page.truncated` when a completed page could not confirm it\n\t * drained everything.\n\t */\n\tfetchFailed?: boolean;\n}\n\nexport interface ProviderPagedResult<T> extends ProviderResult<T> {\n\t/**\n\t * True when a request failed. Unlike `fetchFailed`, a collection read successfully that only left some of its items\n\t * unreadable doesn't set it; those items are named by their own warnings.\n\t */\n\trequestFailed?: boolean;\n\t/** True when the provider advertised continuation without a usable cursor or page position, or repeated one. */\n\tunexpectedGap?: boolean;\n\tpage: ProviderPageInfo;\n\thasMore: boolean;\n\t/**\n\t * Opaque cursor for cursor-based paging (GraphQL, per-repo/per-project cursors, etc.). For hosts that\n\t * require the previous page's cursor, consumers should pass this value back to the next `cursor` option.\n\t * A retry-only cursor may remain when `hasMore` is false: `hasMore` means automatic forward progress,\n\t * while explicitly reusing such a cursor retries failed work without creating an infinite paging loop.\n\t */\n\tcursor?: string;\n}\n\n/**\n * One sweep target, named the way {@link ProviderSweepTargetEvent} names it, so a consumer can join the two.\n * `domain` is the resolved self-managed host (always `undefined` for a cloud provider).\n */\nexport interface ProviderSweepTargetRef {\n\tproviderId: IntegrationIds;\n\tconnectionId: string | undefined;\n\tdomain: string | undefined;\n}\n\n/**\n * A sweep may carry several targets of one provider (one per connection), so the provider arrays below can't say\n * which connection failed: `failedTargets` and `incompleteTargets` are the authoritative attribution, and\n * `failedProviderIds`/`incompleteProviderIds` summarize them. With one target per provider the two agree exactly.\n */\nexport interface ProviderSweepResult<T> extends ProviderResult<T> {\n\tpage: ProviderPageInfo;\n\thasMore: boolean;\n\t/**\n\t * Providers whose top-level read failed before returning any usable page, for EVERY attributed target of the\n\t * provider. A provider with a failed target and a surviving sibling is in `incompleteProviderIds` instead.\n\t * Partial per-scope failures stay represented by `warnings` + `fetchFailed` and are intentionally excluded.\n\t */\n\tfailedProviderIds: IntegrationIds[];\n\t/**\n\t * Providers whose read started successfully but could not produce an authoritative complete slice (for\n\t * example, a later page failed, collection metadata reported a partial scope, or a paging backstop was hit),\n\t * or that have a failed target beside one that returned something.\n\t * Kept separate from\n\t * `failedProviderIds` so consumers can accept healthy sibling providers while preserving an older snapshot\n\t * for a provider whose returned slice has a gap.\n\t */\n\tincompleteProviderIds: IntegrationIds[];\n\t/** Targets whose top-level read failed before returning any usable page. A skipped target is in neither list. */\n\tfailedTargets: ProviderSweepTargetRef[];\n\t/** Targets that returned a slice with a gap: a later page failed, or pages remain unread. Never also in `failedTargets`. */\n\tincompleteTargets: ProviderSweepTargetRef[];\n}\n\nexport interface ProviderBroadenResult<T> extends ProviderPagedResult<T> {\n\tbroadenedProviderIds: IntegrationIds[];\n\t/** Providers for which no requested org produced a usable issue result. */\n\tfailedProviderIds: IntegrationIds[];\n\t/** Providers with both a usable org result and at least one failed or truncated org slice. */\n\tincompleteProviderIds: IntegrationIds[];\n\tfanOutCount: number;\n}\n\nexport type RepositoryResolutionStatus =\n\t| 'resolved'\n\t| 'not-found'\n\t| 'unauthorized'\n\t| 'unsupported-provider'\n\t| 'invalid-remote-url'\n\t| 'host-mismatch'\n\t| 'undetermined';\n\nexport interface RepositoryIdentity {\n\tproviderId: IntegrationIds;\n\tdomain: string;\n\t/** The provider's canonical owner/namespace (follows renames), falling back to the parsed remote when omitted. */\n\towner: string;\n\t/** The provider's canonical repo name (follows renames), falling back to the parsed remote when omitted. */\n\tname: string;\n\tproject?: string;\n\t/** The original input remote URL, so the caller can key the resolution back to the remote it asked about. */\n\tremoteUrl: string;\n\t/**\n\t * True when the provider's canonical owner/name differ from what the input remote URL carried — i.e. the\n\t * repo was renamed/moved host-side and the local remote is stale. Case-insensitive, mirroring gkcli's\n\t * `EqualFold` compare so hosts that echo the input casing (e.g. Bitbucket Server/Azure) aren't flagged.\n\t */\n\trenamed: boolean;\n}\n\nexport interface RepositoryResolution {\n\tstatus: RepositoryResolutionStatus;\n\tidentity?: RepositoryIdentity;\n\twarning?: ProviderWarning;\n}\n\nexport interface ResolveRepositoryResult {\n\tresolution: RepositoryResolution;\n}\n\nconst maxProviderWarningMessageLength = 500;\n\n/** A caught error's message as a warning can carry it: an HTML page becomes its status, and prose is capped. */\nexport function providerWarningMessage(ex: unknown): string {\n\tconst raw = (ex instanceof Error ? ex.message : String(ex)).trim();\n\tconst carrier = ex as { status?: unknown; response?: { status?: unknown } } | null | undefined;\n\tconst status =\n\t\ttypeof carrier?.status === 'number'\n\t\t\t? carrier.status\n\t\t\t: typeof carrier?.response?.status === 'number'\n\t\t\t\t? carrier.response.status\n\t\t\t\t: undefined;\n\n\t// Gateways commonly answer API requests with a complete HTML error page. That payload is neither actionable\n\t// nor suitable for a warning DTO consumed by UIs and logs; preserve the status without leaking the document.\n\tif (/<(?:!doctype\\s+html|html|head|body)\\b/i.test(raw)) {\n\t\treturn status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';\n\t}\n\n\tif (!raw) {\n\t\treturn status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';\n\t}\n\treturn raw.length > maxProviderWarningMessageLength\n\t\t? `${raw.slice(0, maxProviderWarningMessageLength - 3)}...`\n\t\t: raw;\n}\n\n/**\n * Normalized org/workspace/group shape returned by the provider facade.\n * `name` is the provider identifier to pass to follow-up reads (a Jira project's key), while `org` is an optional\n * display label of the parent. Where that label can't address the parent, `orgId` is the parent's stable id to pass\n * as `org` instead (a Jira site's id, or a Data Center instance's domain).\n *\n * Jira site rows (`listOrgs`) are the exception: their `name` is the site's label, and a Jira read selects a site only\n * by its `id` (or a project row's `orgId`).\n */\nexport interface ProviderOrganization {\n\tid: string;\n\tproviderId: IntegrationIds;\n\tname: string;\n\torg?: string;\n\torgId?: string;\n\turl: string;\n}\n\n/**\n * A Linear Project (Linear's own `Project` entity, which can span several teams), as `listLinearProjects` lists it.\n * Distinct from the teams `listProjects` publishes for Linear: pass its `id` to `listIssueTrackerIssuesPage`'s\n * `linearProjects` to narrow an issue read to it.\n */\nexport interface ProviderLinearProjectShape {\n\tid: string;\n\tproviderId: IntegrationIds;\n\tname: string;\n\t/** Linear's project state, as Linear names it (e.g. `planned`, `started`, `paused`, `completed`, `canceled`). */\n\tstate: string;\n\turl: string;\n}\n\n/** Normalized repository shape returned by the provider facade. */\nexport interface ProviderRepositoryShape {\n\tid: string;\n\tnamespace: string;\n\tname: string;\n\t/** Azure DevOps project; `undefined` for hosts without a project layer. */\n\tproject?: string;\n\t/** Web (browser) URL, when the provider exposes it. */\n\turl?: string;\n\t/** HTTPS clone URL, when available. */\n\tcloneUrlHttps?: string;\n\t/** SSH clone URL, when available. */\n\tcloneUrlSsh?: string;\n\t/** Default branch name, when the provider reports it. */\n\tdefaultBranch?: string;\n}\n\n/**\n * Classifies a caught provider exception into a neutral {@link ProviderWarning}. Ordering matters:\n * `instanceof` is checked most-specific-first so a rate-limit isn't mislabeled as a generic error and\n * a 404 isn't mislabeled as auth.\n */\nexport function toProviderWarning(\n\tproviderId: IntegrationIds,\n\tdomain: string | undefined,\n\tconnectionId: string | undefined,\n\tex: unknown,\n): ProviderWarning {\n\tlet kind: ProviderWarning['kind'];\n\tif (ex instanceof AuthenticationError) {\n\t\tkind = 'auth';\n\t} else if (ex instanceof RequestRateLimitError) {\n\t\tkind = 'rate-limit';\n\t} else if (ex instanceof RequestNotFoundError) {\n\t\tkind = 'not-found';\n\t} else if (isUnsupportedSortError(ex)) {\n\t\tkind = 'unsupported';\n\t} else {\n\t\tkind = 'other';\n\t}\n\n\tconst cause = kind === 'other' ? getRequestFailureCause(ex) : undefined;\n\treturn {\n\t\tproviderId: providerId,\n\t\tdomain: domain,\n\t\tconnectionId: connectionId,\n\t\tmessage: providerWarningMessage(ex),\n\t\tkind: kind,\n\t\tisAuth: kind === 'auth',\n\t\t...(cause != null ? { cause: cause } : {}),\n\t};\n}\n\n/**\n * The cause a failed request's error names by itself, one that isn't the credential's (`unexpected-response` or\n * `unreachable`), for a failure classified as no more specific than that.\n */\nexport function getRequestFailureCause(ex: unknown): ProviderWarningCause | undefined {\n\tif (UnexpectedResponseError.is(ex)) return { reason: 'unexpected-response' };\n\tif (isProviderUnreachableError(ex)) return { reason: 'unreachable' };\n\treturn undefined;\n}\n\n/**\n * A scope's identity, as the stable string that keys it.\n *\n * The single definition of what \"the same scope\" means, shared by the failure and omission dedup keys in\n * `providerPaging.ts` and by {@link providerWarningKey} below, so a scope gaining a field is one edit rather\n * than three. `providerId` is included: the same repository ID under two providers is two scopes.\n *\n * The parameter is structural rather than the SDK's `CollectionScope` so this module keeps naming no\n * `@gitkraken/provider-apis` types (see the export block in `index.ts`) while still serving its SDK-facing\n * callers, which pass that type in unchanged.\n */\nexport function collectionScopeKey(scope: ProviderWarningOmissionScope | undefined): string {\n\treturn [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(\n\t\t' ',\n\t);\n}\n\n/**\n * The omission's contribution to a warning's identity — empty when there is none, so a warning without an\n * omission keeps deduping exactly as it did before the field existed.\n *\n * Two omissions of different kinds do produce different `message` values today, so message alone would still\n * separate them. That is incidental: the premise of `omission` is that consumers must not depend on prose\n * carrying the distinguishing fact, and this key must not either.\n */\nfunction providerWarningOmissionKey(omission: ProviderWarningOmission | undefined): string {\n\tif (omission == null) return '';\n\n\treturn [\n\t\tomission.kind,\n\t\tomission.recovery,\n\t\tomission.limit ?? '',\n\t\tomission.totalCount ?? '',\n\t\tcollectionScopeKey(omission.scope),\n\t].join(' ');\n}\n\n/**\n * Strips the omission from every warning in `warnings` when the read as a whole failed.\n *\n * An omission asserts the request SUCCEEDED, and a drain only learns it failed AFTER it may have emitted one:\n * an early page can report its own truncation and then a later page can die. Deciding per warning, at the\n * moment each is built, cannot see that future — so the aggregate is reconciled once, here, where\n * `fetchFailed` is final. Call it at the point a read returns its `fetchFailed`.\n *\n * Re-dedupes as it goes: the omission is part of a warning's identity, so two warnings that differed only\n * there become identical once it is gone, and the array's contract is that no two entries are equal.\n *\n * Mutates in place: the warning array is the one being returned, and callers accumulate into it across pages.\n */\nexport function reconcileOmissionsWithFailure(warnings: ProviderWarning[], fetchFailed: boolean): void {\n\tif (!fetchFailed || !warnings.some(w => w.omission != null)) return;\n\n\tconst reconciled: ProviderWarning[] = [];\n\tfor (const warning of warnings) {\n\t\tif (warning.omission == null) {\n\t\t\tappendDedupedWarning(reconciled, warning);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst { omission: _omission, ...rest } = warning;\n\t\tappendDedupedWarning(reconciled, rest);\n\t}\n\n\twarnings.splice(0, warnings.length, ...reconciled);\n}\n\n/**\n * A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes.\n *\n * The scope and the cause are keyed for the reason the omission is (see {@link providerWarningOmissionKey}): today's\n * failure messages happen to spell them out, but two failures that differ in either must stay two warnings even if\n * they don't.\n *\n * `message` stays LAST. It is the only free-form segment — provider prose, spaces and all — so anything\n * appended after it could be impersonated by a message that happens to end in the same text.\n */\nfunction providerWarningKey(warning: ProviderWarning): string {\n\treturn [\n\t\twarning.providerId,\n\t\twarning.connectionId ?? '',\n\t\twarning.domain ?? '',\n\t\twarning.kind,\n\t\tcollectionScopeKey(warning.scope),\n\t\twarning.cause?.reason ?? '',\n\t\tproviderWarningOmissionKey(warning.omission),\n\t\twarning.selector != null ? JSON.stringify([warning.selector.kind, warning.selector.value]) : '',\n\t\twarning.message,\n\t].join(' ');\n}\n\n/**\n * Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message, plus the\n * structured scope, cause, omission and selector when present) is absent. An equal warning already there merges its\n * {@link ProviderWarning.targetKeys} with the new one's instead: the union of both, or none when either concerns\n * the whole call. Its {@link ProviderWarning.unreadableItems} merge too (see {@link mergeUnreadableItems}): two reads\n * can report the same text for different items. The existing warning is replaced, never mutated, since it may be\n * shared.\n */\nexport function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void {\n\tconst key = providerWarningKey(warning);\n\tconst index = into.findIndex(existing => providerWarningKey(existing) === key);\n\tif (index === -1) {\n\t\tinto.push(warning);\n\t\treturn;\n\t}\n\n\tconst existing = into[index];\n\tconst targetKeys = mergeTargetKeys(existing.targetKeys, warning.targetKeys);\n\tconst unreadableItems =\n\t\texisting.unreadableItems != null && warning.unreadableItems != null\n\t\t\t? mergeUnreadableItems(existing.unreadableItems, warning.unreadableItems)\n\t\t\t: (existing.unreadableItems ?? warning.unreadableItems);\n\tif (targetKeys === existing.targetKeys && unreadableItems === existing.unreadableItems) return;\n\n\tconst { targetKeys: _, ...rest } = existing;\n\tinto[index] = {\n\t\t...rest,\n\t\t...(targetKeys != null ? { targetKeys: targetKeys } : {}),\n\t\t...(unreadableItems != null ? { unreadableItems: unreadableItems } : {}),\n\t};\n}\n\n/** The union of two warnings' target keys, or none when either concerns the whole call. `existing` when unchanged. */\nfunction mergeTargetKeys(existing: string[] | undefined, next: string[] | undefined): string[] | undefined {\n\t// Either concerns the whole call.\n\tif (existing == null || next == null) return undefined;\n\n\tconst added = next.filter(k => !existing.includes(k));\n\tif (!added.length) return existing;\n\n\treturn [...existing, ...new Set(added)];\n}\n\n/**\n * The items two reports of unreadable items left out together: the union of their keys, complete only when both are.\n * `existing` when `next` adds nothing to it.\n */\nexport function mergeUnreadableItems(\n\texisting: ProviderWarningUnreadableItems,\n\tnext: ProviderWarningUnreadableItems,\n): ProviderWarningUnreadableItems {\n\tconst known = new Set(existing.keys);\n\tconst added = next.keys.filter(k => !known.has(k));\n\tconst complete = existing.complete && next.complete;\n\tif (!added.length && complete === existing.complete) return existing;\n\n\treturn { keys: [...existing.keys, ...new Set(added)], complete: complete };\n}\n"],"mappings":"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"}

package/dist/plus/notifications/api.d.ts

@@ -0,0 +1,20 @@
+import { NotificationsContext } from "./context.js";
+import { NotificationSettings, NotificationsPage } from "./models.js";
+//#region ../plus/notifications/src/api.d.ts
+export declare const notificationsPageSize = 50;
+/** A thin client over the `notifications-service-v2` v1 API. */
+export declare class NotificationsApi {
+  private readonly context;
+  constructor(context: NotificationsContext);
+  /** Loads one page (1-based), newest first. Invalid notifications are dropped (and logged). */
+  list(page: number, pageSize?: number): Promise<NotificationsPage>;
+  markRead(ids: readonly string[]): Promise<void>;
+  markUnread(ids: readonly string[]): Promise<void>;
+  delete(ids: readonly string[]): Promise<void>;
+  getSettings(): Promise<NotificationSettings>;
+  updateSettings(settings: NotificationSettings): Promise<void>;
+  /** Sends the request and returns the unwrapped `data` envelope (or `undefined` for an empty body). */
+  private request;
+}
+//#endregion
+//# sourceMappingURL=api.d.ts.map

package/dist/plus/notifications/api.js

@@ -0,0 +1,89 @@
+import { NotificationsApiError } from "./errors.js";
+import { isRecord, parseNotification } from "./parse.js";
+//#region ../plus/notifications/src/api.ts
+const notificationsPageSize = 50;
+/** A thin client over the `notifications-service-v2` v1 API. */
+var NotificationsApi = class {
+	context;
+	constructor(context) {
+		this.context = context;
+	}
+	/** Loads one page (1-based), newest first. Invalid notifications are dropped (and logged). */
+	async list(page, pageSize = 50) {
+		const query = new URLSearchParams({
+			productType: this.context.productType,
+			page: String(page),
+			pageSize: String(pageSize)
+		});
+		const data = await this.request("list", "v1/notifications", { method: "GET" }, query);
+		const results = isRecord(data) && Array.isArray(data.results) ? data.results : [];
+		const items = [];
+		for (const raw of results) {
+			const notification = parseNotification(raw, this.context.log);
+			if (notification != null) items.push(notification);
+		}
+		return {
+			items,
+			hasMore: isRecord(data) && data.hasMore === true,
+			page: isRecord(data) && typeof data.page === "number" ? data.page : page
+		};
+	}
+	async markRead(ids) {
+		await this.request("markRead", "v1/notifications/read", {
+			method: "POST",
+			body: JSON.stringify({ notificationIds: ids })
+		});
+	}
+	async markUnread(ids) {
+		await this.request("markUnread", "v1/notifications/unread", {
+			method: "POST",
+			body: JSON.stringify({ notificationIds: ids })
+		});
+	}
+	async delete(ids) {
+		await this.request("delete", "v1/notifications", {
+			method: "DELETE",
+			body: JSON.stringify({ notificationIds: ids })
+		});
+	}
+	async getSettings() {
+		const data = await this.request("getSettings", "v1/notifications/user-settings", { method: "GET" });
+		const settings = isRecord(data) ? data : {};
+		return {
+			marketingEnabled: settings.marketingEnabled !== false,
+			helpEnabled: settings.helpEnabled !== false,
+			securityEnabled: settings.securityEnabled !== false
+		};
+	}
+	async updateSettings(settings) {
+		await this.request("updateSettings", "v1/notifications/user-settings", {
+			method: "POST",
+			body: JSON.stringify({
+				marketingEnabled: settings.marketingEnabled,
+				helpEnabled: settings.helpEnabled,
+				securityEnabled: settings.securityEnabled
+			})
+		});
+	}
+	/** Sends the request and returns the unwrapped `data` envelope (or `undefined` for an empty body). */
+	async request(operation, path, init, query) {
+		const rsp = await this.context.fetchGkApi(path, {
+			...init,
+			headers: { "Content-Type": "application/json" }
+		}, query);
+		if (!rsp.ok) throw new NotificationsApiError(rsp.status, operation, rsp.statusText);
+		const text = await rsp.text();
+		if (!text) return void 0;
+		let json;
+		try {
+			json = JSON.parse(text);
+		} catch (ex) {
+			throw new NotificationsApiError(rsp.status, operation, "invalid JSON response", { cause: ex });
+		}
+		return isRecord(json) ? json.data ?? json : json;
+	}
+};
+//#endregion
+export { NotificationsApi, notificationsPageSize };
+
+//# sourceMappingURL=api.js.map

package/dist/plus/notifications/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","names":[],"sources":["../../../../plus/notifications/src/api.ts"],"sourcesContent":["import type { NotificationsContext } from './context.js';\nimport { NotificationsApiError } from './errors.js';\nimport type { GkNotification, NotificationSettings, NotificationsPage } from './models.js';\nimport { isRecord, parseNotification } from './parse.js';\n\nexport const notificationsPageSize = 50;\n\n/** A thin client over the `notifications-service-v2` v1 API. */\nexport class NotificationsApi {\n\tconstructor(private readonly context: NotificationsContext) {}\n\n\t/** Loads one page (1-based), newest first. Invalid notifications are dropped (and logged). */\n\tasync list(page: number, pageSize: number = notificationsPageSize): Promise<NotificationsPage> {\n\t\tconst query = new URLSearchParams({\n\t\t\tproductType: this.context.productType,\n\t\t\tpage: String(page),\n\t\t\tpageSize: String(pageSize),\n\t\t});\n\t\tconst data = await this.request('list', 'v1/notifications', { method: 'GET' }, query);\n\n\t\tconst results = isRecord(data) && Array.isArray(data.results) ? (data.results as unknown[]) : [];\n\t\tconst items: GkNotification[] = [];\n\t\tfor (const raw of results) {\n\t\t\tconst notification = parseNotification(raw, this.context.log);\n\t\t\tif (notification != null) {\n\t\t\t\titems.push(notification);\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\titems: items,\n\t\t\thasMore: isRecord(data) && data.hasMore === true,\n\t\t\tpage: isRecord(data) && typeof data.page === 'number' ? data.page : page,\n\t\t};\n\t}\n\n\tasync markRead(ids: readonly string[]): Promise<void> {\n\t\tawait this.request('markRead', 'v1/notifications/read', {\n\t\t\tmethod: 'POST',\n\t\t\tbody: JSON.stringify({ notificationIds: ids }),\n\t\t});\n\t}\n\n\tasync markUnread(ids: readonly string[]): Promise<void> {\n\t\tawait this.request('markUnread', 'v1/notifications/unread', {\n\t\t\tmethod: 'POST',\n\t\t\tbody: JSON.stringify({ notificationIds: ids }),\n\t\t});\n\t}\n\n\tasync delete(ids: readonly string[]): Promise<void> {\n\t\tawait this.request('delete', 'v1/notifications', {\n\t\t\tmethod: 'DELETE',\n\t\t\tbody: JSON.stringify({ notificationIds: ids }),\n\t\t});\n\t}\n\n\tasync getSettings(): Promise<NotificationSettings> {\n\t\tconst data = await this.request('getSettings', 'v1/notifications/user-settings', { method: 'GET' });\n\t\tconst settings = isRecord(data) ? data : {};\n\t\t// A missing flag means the service default, which is opted in\n\t\treturn {\n\t\t\tmarketingEnabled: settings.marketingEnabled !== false,\n\t\t\thelpEnabled: settings.helpEnabled !== false,\n\t\t\tsecurityEnabled: settings.securityEnabled !== false,\n\t\t};\n\t}\n\n\tasync updateSettings(settings: NotificationSettings): Promise<void> {\n\t\tawait this.request('updateSettings', 'v1/notifications/user-settings', {\n\t\t\tmethod: 'POST',\n\t\t\tbody: JSON.stringify({\n\t\t\t\tmarketingEnabled: settings.marketingEnabled,\n\t\t\t\thelpEnabled: settings.helpEnabled,\n\t\t\t\tsecurityEnabled: settings.securityEnabled,\n\t\t\t} satisfies NotificationSettings),\n\t\t});\n\t}\n\n\t/** Sends the request and returns the unwrapped `data` envelope (or `undefined` for an empty body). */\n\tprivate async request(\n\t\toperation: string,\n\t\tpath: string,\n\t\tinit: RequestInit,\n\t\tquery?: URLSearchParams,\n\t): Promise<unknown> {\n\t\tconst rsp = await this.context.fetchGkApi(\n\t\t\tpath,\n\t\t\t{\n\t\t\t\t...init,\n\t\t\t\theaders: { 'Content-Type': 'application/json' },\n\t\t\t},\n\t\t\tquery,\n\t\t);\n\t\tif (!rsp.ok) throw new NotificationsApiError(rsp.status, operation, rsp.statusText);\n\n\t\tconst text = await rsp.text();\n\t\tif (!text) return undefined;\n\n\t\tlet json: unknown;\n\t\ttry {\n\t\t\tjson = JSON.parse(text);\n\t\t} catch (ex) {\n\t\t\tthrow new NotificationsApiError(rsp.status, operation, 'invalid JSON response', { cause: ex });\n\t\t}\n\t\treturn isRecord(json) ? (json.data ?? json) : json;\n\t}\n}\n"],"mappings":";;;AAKA,MAAa,wBAAwB;;AAGrC,IAAa,mBAAb,MAA8B;CACA;CAA7B,YAAY,SAAgD;EAA/B,KAAA,UAAA;CAAgC;;CAG7D,MAAM,KAAK,MAAc,WAAA,IAAsE;EAC9F,MAAM,QAAQ,IAAI,gBAAgB;GACjC,aAAa,KAAK,QAAQ;GAC1B,MAAM,OAAO,IAAI;GACjB,UAAU,OAAO,QAAQ;EAC1B,CAAC;EACD,MAAM,OAAO,MAAM,KAAK,QAAQ,QAAQ,oBAAoB,EAAE,QAAQ,MAAM,GAAG,KAAK;EAEpF,MAAM,UAAU,SAAS,IAAI,KAAK,MAAM,QAAQ,KAAK,OAAO,IAAK,KAAK,UAAwB,CAAC;EAC/F,MAAM,QAA0B,CAAC;EACjC,KAAK,MAAM,OAAO,SAAS;GAC1B,MAAM,eAAe,kBAAkB,KAAK,KAAK,QAAQ,GAAG;GAC5D,IAAI,gBAAgB,MACnB,MAAM,KAAK,YAAY;EAEzB;EAEA,OAAO;GACC;GACP,SAAS,SAAS,IAAI,KAAK,KAAK,YAAY;GAC5C,MAAM,SAAS,IAAI,KAAK,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO;EACrE;CACD;CAEA,MAAM,SAAS,KAAuC;EACrD,MAAM,KAAK,QAAQ,YAAY,yBAAyB;GACvD,QAAQ;GACR,MAAM,KAAK,UAAU,EAAE,iBAAiB,IAAI,CAAC;EAC9C,CAAC;CACF;CAEA,MAAM,WAAW,KAAuC;EACvD,MAAM,KAAK,QAAQ,cAAc,2BAA2B;GAC3D,QAAQ;GACR,MAAM,KAAK,UAAU,EAAE,iBAAiB,IAAI,CAAC;EAC9C,CAAC;CACF;CAEA,MAAM,OAAO,KAAuC;EACnD,MAAM,KAAK,QAAQ,UAAU,oBAAoB;GAChD,QAAQ;GACR,MAAM,KAAK,UAAU,EAAE,iBAAiB,IAAI,CAAC;EAC9C,CAAC;CACF;CAEA,MAAM,cAA6C;EAClD,MAAM,OAAO,MAAM,KAAK,QAAQ,eAAe,kCAAkC,EAAE,QAAQ,MAAM,CAAC;EAClG,MAAM,WAAW,SAAS,IAAI,IAAI,OAAO,CAAC;EAE1C,OAAO;GACN,kBAAkB,SAAS,qBAAqB;GAChD,aAAa,SAAS,gBAAgB;GACtC,iBAAiB,SAAS,oBAAoB;EAC/C;CACD;CAEA,MAAM,eAAe,UAA+C;EACnE,MAAM,KAAK,QAAQ,kBAAkB,kCAAkC;GACtE,QAAQ;GACR,MAAM,KAAK,UAAU;IACpB,kBAAkB,SAAS;IAC3B,aAAa,SAAS;IACtB,iBAAiB,SAAS;GAC3B,CAAgC;EACjC,CAAC;CACF;;CAGA,MAAc,QACb,WACA,MACA,MACA,OACmB;EACnB,MAAM,MAAM,MAAM,KAAK,QAAQ,WAC9B,MACA;GACC,GAAG;GACH,SAAS,EAAE,gBAAgB,mBAAmB;EAC/C,GACA,KACD;EACA,IAAI,CAAC,IAAI,IAAI,MAAM,IAAI,sBAAsB,IAAI,QAAQ,WAAW,IAAI,UAAU;EAElF,MAAM,OAAO,MAAM,IAAI,KAAK;EAC5B,IAAI,CAAC,MAAM,OAAO,KAAA;EAElB,IAAI;EACJ,IAAI;GACH,OAAO,KAAK,MAAM,IAAI;EACvB,SAAS,IAAI;GACZ,MAAM,IAAI,sBAAsB,IAAI,QAAQ,WAAW,yBAAyB,EAAE,OAAO,GAAG,CAAC;EAC9F;EACA,OAAO,SAAS,IAAI,IAAK,KAAK,QAAQ,OAAQ;CAC/C;AACD"}

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

@@ -0,0 +1,28 @@
+//#region ../plus/notifications/src/context.d.ts
+/**
+ * Optional diagnostics sink. The package never logs on its own; the host routes these to its logger.
+ */
+export interface NotificationsLogger {
+  debug?(message: string): void;
+  warn?(message: string): void;
+  error?(ex: unknown, message?: string): void;
+}
+/**
+ * Everything the notifications package needs from its host. The package cannot import `vscode` or reach
+ * into the extension host, so the only way it talks to the outside world is through this context.
+ */
+export interface NotificationsContext {
+  /** The `productType` the notifications service filters by, e.g. `gitlens`. The package never hardcodes one. */
+  readonly productType: string;
+  /**
+   * Authenticated request against the GK cloud API. `path` is relative to the API root, has no leading slash
+   * and never carries a query string, e.g. `v1/notifications`; any query comes separately in `query`. A non-2xx
+   * response is returned, not thrown.
+   */
+  fetchGkApi(path: string, init?: RequestInit, query?: URLSearchParams): Promise<Response>;
+  /** Current time in ms since the epoch; a test seam that defaults to `Date.now()`. */
+  now?(): number;
+  readonly log?: NotificationsLogger;
+}
+//#endregion
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1,13 @@
+//#region ../plus/notifications/src/errors.d.ts
+/**
+ * A failed request to the notifications service: a non-2xx response, or a 2xx one whose body isn't valid JSON
+ * (e.g. an HTML error page from a proxy). The message is for logs, not for display.
+ */
+export declare class NotificationsApiError extends Error {
+  readonly status: number;
+  readonly operation: string;
+  static is(ex: unknown): ex is NotificationsApiError;
+  constructor(status: number, operation: string, reason?: string, options?: ErrorOptions);
+}
+//#endregion
+//# sourceMappingURL=errors.d.ts.map

package/dist/plus/notifications/errors.js

@@ -0,0 +1,22 @@
+//#region ../plus/notifications/src/errors.ts
+/**
+* A failed request to the notifications service: a non-2xx response, or a 2xx one whose body isn't valid JSON
+* (e.g. an HTML error page from a proxy). The message is for logs, not for display.
+*/
+var NotificationsApiError = class NotificationsApiError extends Error {
+	status;
+	operation;
+	static is(ex) {
+		return ex instanceof NotificationsApiError;
+	}
+	constructor(status, operation, reason, options) {
+		super(`Notifications request '${operation}' failed: ${status}${reason ? ` ${reason}` : ""}`, options);
+		this.status = status;
+		this.operation = operation;
+		this.name = "NotificationsApiError";
+	}
+};
+//#endregion
+export { NotificationsApiError };
+
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../../../plus/notifications/src/errors.ts"],"sourcesContent":["/**\n * A failed request to the notifications service: a non-2xx response, or a 2xx one whose body isn't valid JSON\n * (e.g. an HTML error page from a proxy). The message is for logs, not for display.\n */\nexport class NotificationsApiError extends Error {\n\tstatic is(ex: unknown): ex is NotificationsApiError {\n\t\treturn ex instanceof NotificationsApiError;\n\t}\n\n\tconstructor(\n\t\treadonly status: number,\n\t\treadonly operation: string,\n\t\treason?: string,\n\t\toptions?: ErrorOptions,\n\t) {\n\t\tsuper(`Notifications request '${operation}' failed: ${status}${reason ? ` ${reason}` : ''}`, options);\n\t\tthis.name = 'NotificationsApiError';\n\t}\n}\n"],"mappings":";;;;;AAIA,IAAa,wBAAb,MAAa,8BAA8B,MAAM;CAMtC;CACA;CANV,OAAO,GAAG,IAA0C;EACnD,OAAO,cAAc;CACtB;CAEA,YACC,QACA,WACA,QACA,SACC;EACD,MAAM,0BAA0B,UAAU,YAAY,SAAS,SAAS,IAAI,WAAW,MAAM,OAAO;EAL3F,KAAA,SAAA;EACA,KAAA,YAAA;EAKT,KAAK,OAAO;CACb;AACD"}

package/dist/plus/notifications/models.d.ts

@@ -0,0 +1,94 @@
+//#region ../plus/notifications/src/models.d.ts
+export type NotificationContentType = 'feature' | 'help' | 'marketing' | 'system' | 'security';
+/** The events this package knows how to render; anything else is `unknown` and shown via its `fallback`. */
+export type NotificationEvent = 'general' | 'callToAction' | 'projectShared' | 'nudge' | 'unknown';
+/** A notification as `notifications-service-v2` returns it from `GET v1/notifications`. Untrusted input. */
+export interface RawNotification {
+  notificationId: string;
+  name: string;
+  title?: string | null;
+  notificationType: 'system' | 'user';
+  contentType: NotificationContentType;
+  /** Any string; the known values are those of {@link NotificationEvent} other than `unknown`. */
+  event: string;
+  /** ISO 8601 timestamps. */
+  readAt?: string | null;
+  expiresAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  fallback?: string | null;
+  payload?: unknown;
+}
+export interface NotificationSettings {
+  marketingEnabled: boolean;
+  helpEnabled: boolean;
+  securityEnabled: boolean;
+}
+/**
+ * The parts of a `projectShared` notification. The package cannot localize, so the host assembles the sentence
+ * ("In {organization}, {owner} created a new Team Workspace: {project}", plus the teams when there are any).
+ */
+export interface ProjectSharedDetails {
+  organization: string;
+  owner: string;
+  project: string;
+  teams: string[];
+}
+/** A validated notification. Plain data, so it can be persisted and sent over RPC as is. */
+export interface GkNotification {
+  id: string;
+  event: NotificationEvent;
+  contentType: NotificationContentType;
+  /**
+   * The server's display `title`; `undefined` when unset, in which case the host supplies its own header.
+   * Never the server's internal `name`.
+   */
+  headline?: string;
+  /**
+   * A plain-text one-line summary of the notice (the server's `payload.desktopMessage`, else `fallback`), when set;
+   * the host uses it where there's no {@link headline}. Never markdown-rendered.
+   */
+  summary?: string;
+  /** Markdown. `undefined` for `projectShared`, whose body the host builds from {@link projectShared}. */
+  body: string | undefined;
+  /** Only for `callToAction`; the URL is always `https:`. */
+  cta?: {
+    text: string;
+    url: string;
+  };
+  /** Only for `projectShared`. */
+  projectShared?: ProjectSharedDetails;
+  /** Timestamps in ms since the epoch. */
+  createdAt: number;
+  readAt?: number;
+  expiresAt?: number;
+  /** Set when an unknown event is shown through its `fallback` text. */
+  needsNewerVersion?: boolean;
+}
+export interface NotificationsPage {
+  items: GkNotification[];
+  hasMore: boolean;
+  page: number;
+}
+export type NotificationsStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface NotificationsState {
+  /** Newest first. */
+  readonly items: readonly GkNotification[];
+  readonly hasMore: boolean;
+  readonly status: NotificationsStatus;
+  readonly lastSyncedAt: number | undefined;
+  readonly settings: NotificationSettings | undefined;
+  /** Unread among the loaded items. */
+  readonly unreadCount: number;
+}
+/** What the host persists between sessions; see `NotificationsService.toSnapshot()` and `restore()`. */
+export interface NotificationsSnapshot {
+  items: GkNotification[];
+  hasMore: boolean;
+  /** The last page loaded, 1-based. */
+  page: number;
+  lastSyncedAt: number | undefined;
+  settings: NotificationSettings | undefined;
+}
+//#endregion
+//# sourceMappingURL=models.d.ts.map

package/dist/plus/notifications/notificationsService.d.ts

@@ -0,0 +1,115 @@
+import { UnifiedDisposable } from "../../utils/disposable.js";
+import { Event } from "../../utils/event.js";
+import { NotificationsContext } from "./context.js";
+import { GkNotification, NotificationSettings, NotificationsSnapshot, NotificationsState } from "./models.js";
+//#region ../plus/notifications/src/notificationsService.d.ts
+/**
+ * How far before the newest previously-held notification's `createdAt` a notification may fall and still count as
+ * newly arrived in {@link NotificationsService.refresh}'s result. Both sides are server timestamps; the margin only
+ * covers concurrent inserts committing out of `created_at` order on the server.
+ */
+export declare const newToastableSkewMargin: number;
+/**
+ * Holds the user's notifications for one product and keeps them in sync with `notifications-service-v2`.
+ * Read/unread/delete and settings changes apply optimistically and roll back if the request fails (a 404 on
+ * read/unread/delete means the notifications are already gone, so it isn't a failure). The service never polls on
+ * its own: the host decides when to {@link refresh}, and each refresh reports which notices newly arrived and
+ * should toast; how (and whether) to show them stays the host's call.
+ */
+export declare class NotificationsService implements UnifiedDisposable {
+  private readonly context;
+  private readonly _onDidChange;
+  get onDidChange(): Event<void>;
+  private readonly api;
+  private _items;
+  private _hasMore;
+  /** The last page loaded, 1-based; 0 before the first load. */
+  private _page;
+  private _status;
+  private _lastSyncedAt;
+  private _settings;
+  /** The settings the server last acknowledged (fetched, or successfully saved) */
+  private _confirmedSettings;
+  private _settingsPost;
+  private _settingsFollowUp;
+  private _refreshing;
+  private _loadingMore;
+  /**
+   * Actions in flight (or settled while a refresh that started before them was still fetching), by id. A refresh
+   * re-applies them so data fetched before the server saw an action doesn't undo it.
+   */
+  private readonly _overrides;
+  /** For items a refresh re-applied an override to: the override's output → which override and the server's item */
+  private readonly _overridden;
+  constructor(context: NotificationsContext);
+  dispose(): void;
+  [Symbol.dispose](): void;
+  get unreadCount(): number;
+  getState(): NotificationsState;
+  /**
+   * Re-fetches every page already loaded (up to {@link maxRefreshPages}), so read state, deletions and expiry
+   * from elsewhere reach them without collapsing a list the user paged through. Expired items are pruned and
+   * local actions still in flight are kept. Never throws: on failure the cached items stay and the status
+   * becomes `error`.
+   *
+   * Resolves to the notices to toast: the unread, toast-eligible ones that newly arrived with this refresh,
+   * newest first. Empty when the refresh failed, when nothing had synced before it (no backfill: the first load
+   * for an account is the existing inbox, not news; a restored snapshot with a `lastSyncedAt` does count as
+   * synced, so what arrived while the host was closed still toasts), or when nothing is new. New means its id
+   * wasn't held before the refresh AND it was created after the newest of those held, less
+   * {@link newToastableSkewMargin}. Only server timestamps are compared, so the client's clock can't hide a
+   * notice. The id check keeps a notice already seen from toasting again; the time check keeps an old one that
+   * only now shifts into the first page (after a deletion, or a page boundary moving) from toasting as if it
+   * were new. With nothing held before there is no cutoff.
+   *
+   * Concurrent calls share one request and resolve to the same list, so the result is for ONE caller to act on
+   * once (the host's refresh loop); other callers should ignore it.
+   */
+  refresh(): Promise<GkNotification[]>;
+  private refreshCore;
+  /**
+   * Loads the next page, after any refresh in flight (which may change which page is next). Throws on failure,
+   * leaving the loaded items as they were. Concurrent calls share one request.
+   */
+  loadMore(): Promise<void>;
+  private loadMoreCore;
+  markRead(ids: readonly string[]): Promise<void>;
+  markUnread(ids: readonly string[]): Promise<void>;
+  delete(ids: readonly string[]): Promise<void>;
+  /** Marks every loaded unread notification read. */
+  markAllRead(): Promise<void>;
+  /** Deletes every loaded read notification. */
+  deleteAllRead(): Promise<void>;
+  /** Fetches the user's notification settings (and caches them in the state). */
+  getSettings(): Promise<NotificationSettings>;
+  /**
+   * Applies `changes` optimistically, then saves. The server stores the whole settings object from each request,
+   * so POSTs must not overlap (they could land out of order and leave the older state): at most one is in flight,
+   * and calls made meanwhile share ONE follow-up POST that sends the latest state. Each call settles with the
+   * outcome of the POST that carried its change.
+   */
+  updateSettings(changes: Partial<NotificationSettings>): Promise<NotificationSettings>;
+  private trackSettingsPost;
+  /** Sends the latest optimistic settings; the confirmed state is what was sent, not the server's echo. */
+  private postSettings;
+  /** The held notices that are new relative to `previous`, newest first; see {@link refresh} for the rules */
+  private newToastableSince;
+  toSnapshot(): NotificationsSnapshot;
+  /** Seeds the state from a snapshot the host persisted; expired items are pruned. */
+  restore(snapshot: NotificationsSnapshot): void;
+  /** On a 404 (the notifications are already gone) the targets are removed instead of rolled back. */
+  private updateOptimistically;
+  /**
+   * Records `override` for `ids` until the action settles; on success, until any refresh or Load More in flight
+   * (either may have fetched before the server applied the action) has landed too. Returns the release for when
+   * it settles.
+   */
+  private trackOverrides;
+  private applyOverrides;
+  private pruneExpired;
+  private setStatus;
+  private fireChange;
+  private now;
+}
+//#endregion
+//# sourceMappingURL=notificationsService.d.ts.map