@gitkraken/provider-apis 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.21.0
+
+### ⚠️ Breaking Changes
+
+Added new entity ID API for encoding/decoding entity IDs (previously known as unique IDs). This API replaces the `getPullRequestUniqueId` and `getIssueUniqueId` utility functions in older versions of this library.
+
+The `EntityIdentifier` type represents a particular pull request or issue for a particular provider. The information stored in this type is enough to query the provider's REST or GraphQL API to fetch additional information about the entity (i.e. title, description, assignees, etc) or mutate the entity. `EntityIdentifier` is designed to be 
+serialized so we can send it to our backend services, giving us a portable way to communicate about pull requests or issues.
+
+These are the new functions provided by the API:
+- `validate`: takes an `EntityIdentifier` as input and validates that it is correctly formed
+- `encode`: takes an `EntityIdentifier` as input and encodes it to an array of strings, which can be serialized and sent to our REST APIs
+- `decode`: takes an array string and decodes it to an `EntityIdentifier`
+
+Conversion guide:
+```ts
+const pullRequest: GitPullRequest = { /* ... pr from somewhere ... */ };
+const githubEnterpriseDomain: string | undefined = ...; // undefined if this PR exists on https://github.com
+
+// pre-v0.21.0 way to encode a unique ID (now called a V0 entity ID)
+Utils.github.getPullRequestUniqueId({
+  pullRequest.id,
+  githubEnterpriseDomain,
+});
+
+// v0.21.0 way to encode an entity ID
+encode({
+  provider: EntityIdentifierProviderType.Github,
+  entityType: EntityType.PullRequest,
+  version: EntityVersion.One,
+  domain: githubEnterpriseDomain ?? null,
+  resourceId: null,
+  accountOrOrgId: null,
+  organizationName: null,
+  projectId: null,
+  repoId: null,
+  entityId: pullRequest.id,
+});
+```
+
 ## 0.20.0
 
 - added `getActionablePullRequests` utility function

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { Trello } from './providers/trello/trello';
 import * as AzureDevopsUtils from './providerUtils/azureDevops';
 import * as BitbucketUtils from './providerUtils/bitbucket';
 import * as BitbucketServerUtils from './providerUtils/bitbucketServer';
+import * as EntityIdentifier from './providerUtils/entityIdentifiers/entityIdentifier';
 import * as GitProviderUtils from './providerUtils/gitProvider';
 import * as GitHubUtils from './providerUtils/github';
 import * as GitLabUtils from './providerUtils/gitlab';
@@ -45,5 +46,6 @@ declare const Utils: {
     gitProvider: typeof GitProviderUtils;
     jira: typeof JiraUtils;
     trello: typeof TrelloUtils;
+    entityIdentifier: typeof EntityIdentifier;
 };
-export { AzureDevopsUtils, BitbucketServerUtils, BitbucketUtils, GitHubUtils, GitLabUtils, GitProviderUtils, JiraUtils, TrelloUtils, Utils, };
+export { AzureDevopsUtils, BitbucketServerUtils, BitbucketUtils, EntityIdentifier, GitHubUtils, GitLabUtils, GitProviderUtils, JiraUtils, TrelloUtils, Utils, };