@gitkraken/provider-apis 0.50.0 → 0.52.0

package/dist/providers/azureDevops/azureDevOps.d.ts

@@ -182,6 +182,7 @@ export declare class AzureDevOps extends EnterpriseProvider implements GitProvid
         includeRemoteInfo?: boolean;
     } & GetReposInput, options?: EnterpriseOptions): Promise<{
         data: GitPullRequest[];
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
     }>;
     private getPullRequestsForProjectBase;
     getPullRequestsForProject(input: {
@@ -215,6 +216,7 @@ export declare class AzureDevOps extends EnterpriseProvider implements GitProvid
         includeRemoteInfo?: boolean;
     }, options?: EnterpriseOptions): Promise<{
         data: GitPullRequest[];
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
     }>;
     getAzurePullRequestLastMergeStatus(input: {
         repo: GetRepoInput;

package/dist/providers/bitbucket/bitbucket.d.ts

@@ -180,6 +180,7 @@ export declare class Bitbucket extends Provider implements GitProvider {
         pageSize?: number;
     } & GetReposInput, options?: Options): Promise<{
         data: GitPullRequest[];
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
     }>;
     getAccountsForWorkspace(input: {
         workspace: string;

package/dist/providers/bitbucketServer/bitbucketServer.d.ts

@@ -72,6 +72,7 @@ export declare class BitbucketServer extends EnterpriseProvider implements GitPr
         pageSize?: number;
     } & GetReposInput, options?: EnterpriseOptions): Promise<{
         data: GitPullRequest[];
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
     }>;
     getPullRequestsForCurrentUser(input: {
         reviewerLogin?: string;

package/dist/providers/jira/jira.d.ts

@@ -29,6 +29,7 @@ export declare class Jira extends Provider implements IssueProvider {
             hasNextPage: boolean;
             endCursor: string;
         };
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
         data: {
             id: string;
             key: string;
@@ -47,6 +48,7 @@ export declare class Jira extends Provider implements IssueProvider {
             hasNextPage: boolean;
             endCursor: string;
         };
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
         data: {
             id: string;
             name: string;

package/dist/providers/trello/trello.d.ts

@@ -56,6 +56,7 @@ export declare class Trello extends Provider implements IssueProvider {
         }>;
     }, options?: EnterpriseOptions): Promise<{
         data: Issue[];
+        metadata: import("../../types/exportedTypes/types").CollectionMetadata;
     }>;
     private updateIssue;
     setIssueStatus(input: {

package/dist/types/exportedTypes/types.d.ts

@@ -88,12 +88,50 @@ export interface NumberedPageInfo {
      */
     totalCount?: number | null;
 }
+export type CollectionCompleteness = 'complete' | 'partial' | 'unknown';
+export type CollectionScopeFailureKind = 'authentication' | 'rate-limit' | 'not-found' | 'network' | 'provider' | 'unknown';
+export interface CollectionScope {
+    providerId?: string;
+    resourceId?: string;
+    projectId?: string;
+    repositoryId?: string;
+}
+export interface CollectionScopeFailure {
+    scope?: CollectionScope;
+    kind: CollectionScopeFailureKind;
+    message?: string;
+}
+/**
+ * Additional facts about a collection result that are independent from provider-native pagination.
+ *
+ * `pageInfo` remains the only source of cursor/numbered-page continuation. For paged results,
+ * `completeness` describes whether the returned page is known to fully cover the requested scope for
+ * that call; it does not imply that the entire collection has been exhausted.
+ */
+export interface CollectionMetadata {
+    /**
+     * Whether the SDK knows the returned collection fully covers the requested scope.
+     *
+     * - `complete`: no known omissions for the requested scope.
+     * - `partial`: the SDK knows items were omitted (for example due to a provider cap, a dropped
+     *   sub-scope, or another explicit provider signal).
+     * - `unknown`: the upstream API does not expose enough information to assert completeness.
+     */
+    completeness: CollectionCompleteness;
+    /**
+     * Per-scope failures captured while still returning successful data from other scopes.
+     * These are structured provider facts only; callers decide how to warn, retry, or recover.
+     */
+    failures?: CollectionScopeFailure[];
+}
 export type Result<T> = {
     data: T;
+    metadata?: CollectionMetadata;
 };
 export type PagedResult<T> = {
     pageInfo: CursorPageInfo | NumberedPageInfo;
     data: T[];
+    metadata?: CollectionMetadata;
 };
 export type FullFieldMap<T> = Record<keyof T, boolean>;
 export type FieldMap<T> = Partial<FullFieldMap<T>>;

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
-import { GitPullRequest, GitPullRequestState } from './types/exportedTypes/gitProvider';
-import { CursorPageInfo, FieldMap, NumberedPageInfo } from './types/exportedTypes/types';
+import { GetRepoInput, GitPullRequest, GitPullRequestState } from './types/exportedTypes/gitProvider';
+import { CollectionCompleteness, CollectionMetadata, CollectionScope, CollectionScopeFailure, CollectionScopeFailureKind, CursorPageInfo, FieldMap, NumberedPageInfo } from './types/exportedTypes/types';
 export declare const getRequestHeaders: (token?: string, basicAuth?: boolean) => Record<string, string>;
 export declare const toFieldMap: <T, K extends keyof T = keyof T>(fields?: K[] | undefined) => Partial<import("./types/exportedTypes/types").FullFieldMap<T>> | undefined;
 /**
@@ -27,6 +27,48 @@ export declare const resolvePageSize: (pageSize: number | null | undefined, { fa
     max?: number | undefined;
 }) => number;
 export declare const filterPullRequestsByStates: (pullRequests: GitPullRequest[], states?: GitPullRequestState[]) => GitPullRequest[];
+export declare const getErrorStatusCode: (error: unknown) => number | undefined;
+export declare const getCollectionFailureKind: (error: unknown) => CollectionScopeFailureKind;
+export declare const createCollectionFailure: (scope: CollectionScopeFailure['scope'], error: unknown) => CollectionScopeFailure;
+export declare const createCollectionMetadata: (completeness: CollectionCompleteness, failures?: CollectionScopeFailure[]) => CollectionMetadata;
+/**
+ * Combines two completeness signals into the more degraded of the two. A multi-scope fan-out is only
+ * as complete as its least-complete scope, so `partial` (a known omission) outranks `unknown` (the
+ * provider can't assert completeness), which outranks `complete`.
+ */
+export declare const mergeCompleteness: (a: CollectionCompleteness, b: CollectionCompleteness) => CollectionCompleteness;
+/**
+ * Stable scope identifier for a repo fan-out failure: the provider repository id when known, else a
+ * `namespace/name` fallback. Returns `undefined` when no repo is in scope (for example an Azure
+ * project fan-out with no repo filter).
+ */
+export declare const getRepoScopeId: (repo: GetRepoInput | undefined) => string | undefined;
+export interface CollectScopeSuccess<S, R> {
+    scope: S;
+    result: R;
+}
+export interface CollectAcrossScopesResult<S, R> {
+    successes: CollectScopeSuccess<S, Exclude<R, undefined>>[];
+    metadata: CollectionMetadata;
+}
+/**
+ * Runs `run` over every requested `scope` in parallel and aggregates the outcomes into common
+ * collection metadata, without throwing when individual scopes fail.
+ *
+ * - A scope whose `run` rejects is recorded as a per-scope failure (built from `failureScope`) and
+ *   degrades completeness to `partial`.
+ * - A scope whose `run` resolves to `undefined` is skipped entirely: no data, no failure, and no
+ *   effect on completeness (used when a scope is filtered out before any request is made).
+ * - A scope that resolves to a value contributes its `completeness` signal (defaulting to `complete`)
+ *   and is returned in `successes` for the caller to shape into its own data type.
+ *
+ * An empty `scopes` list yields `complete` metadata with no failures.
+ */
+export declare function collectAcrossScopes<S, R>(scopes: S[], { run, failureScope, completeness, }: {
+    run: (scope: S) => Promise<R | undefined>;
+    failureScope: (scope: S) => CollectionScope;
+    completeness?: (result: Exclude<R, undefined>) => CollectionCompleteness;
+}): Promise<CollectAcrossScopesResult<S, R>>;
 export declare function getSettledValue<T>(promise: PromiseSettledResult<Awaited<T | undefined>>): T | undefined;
 export declare function getSettledValue<T>(promise: PromiseSettledResult<Awaited<T | undefined>> | undefined, defaultValue: NonNullable<T>): NonNullable<T>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitkraken/provider-apis",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "An SDK around different third-party APIs that accepts and returns data in a common format.",
   "author": "Axosoft, LLC dba GitKraken",
   "license": "SEE LICENSE IN LICENSE",