@backstage/integration 1.4.2-next.0 → 1.4.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @backstage/integration
 
+## 1.4.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/config@1.0.6
+  - @backstage/errors@1.1.4
+
 ## 1.4.2-next.0
 
 ### Patch Changes

package/dist/index.cjs.js

@@ -193,6 +193,11 @@ const _AzureUrl = class {
     __privateSet(this, _path, path);
     __privateSet(this, _ref, ref);
   }
+  /**
+   * Parses an azure URL as copied from the browser address bar.
+   *
+   * Throws an error if the URL is not a valid azure repo URL.
+   */
   static fromRepoUrl(repoUrl) {
     var _a;
     const url = new URL(repoUrl);
@@ -227,6 +232,11 @@ const _AzureUrl = class {
     }
     return new _AzureUrl(url.origin, owner, project, repo, path, ref);
   }
+  /**
+   * Returns a repo URL that can be used to navigate to the resource in azure.
+   *
+   * Throws an error if the URL is not a valid azure repo URL.
+   */
   toRepoUrl() {
     let url;
     if (__privateGet(this, _project) === __privateGet(this, _repo)) {
@@ -242,6 +252,11 @@ const _AzureUrl = class {
     }
     return url.toString();
   }
+  /**
+   * Returns the file download URL for this azure resource.
+   *
+   * Throws an error if the URL does not point to a file.
+   */
   toFileUrl() {
     if (!__privateGet(this, _path)) {
       throw new Error(
@@ -256,6 +271,11 @@ const _AzureUrl = class {
     }
     return url.toString();
   }
+  /**
+   * Returns the archive download URL for this azure resource.
+   *
+   * Throws an error if the URL does not point to a repo.
+   */
   toArchiveUrl() {
     const url = __privateGet(this, _baseUrl).call(this, __privateGet(this, _owner), __privateGet(this, _project), "_apis", "git", "repositories", __privateGet(this, _repo), "items");
     url.searchParams.set("recursionLevel", "full");
@@ -269,6 +289,11 @@ const _AzureUrl = class {
     }
     return url.toString();
   }
+  /**
+   * Returns the API url for fetching commits from a branch for this azure resource.
+   *
+   * Throws an error if the URL does not point to a commit.
+   */
   toCommitsUrl() {
     const url = __privateGet(this, _baseUrl).call(this, __privateGet(this, _owner), __privateGet(this, _project), "_apis", "git", "repositories", __privateGet(this, _repo), "commits");
     url.searchParams.set("api-version", "6.0");
@@ -277,18 +302,33 @@ const _AzureUrl = class {
     }
     return url.toString();
   }
+  /**
+   * Returns the name of the owner, a user or an organization.
+   */
   getOwner() {
     return __privateGet(this, _owner);
   }
+  /**
+   * Returns the name of the project.
+   */
   getProject() {
     return __privateGet(this, _project);
   }
+  /**
+   * Returns the name of the repo.
+   */
   getRepo() {
     return __privateGet(this, _repo);
   }
+  /**
+   * Returns the file path within the repo if the URL contains one.
+   */
   getPath() {
     return __privateGet(this, _path);
   }
+  /**
+   * Returns the git ref in the repo if the URL contains one.
+   */
   getRef() {
     return __privateGet(this, _ref);
   }
@@ -335,6 +375,11 @@ const _AzureIntegration = class {
   get config() {
     return this.integrationConfig;
   }
+  /*
+   * Azure repo URLs on the form with a `path` query param are treated specially.
+   *
+   * Example base URL: https://dev.azure.com/organization/project/_git/repository?path=%2Fcatalog-info.yaml
+   */
   resolveUrl(options) {
     var _a;
     const { url, base } = options;
@@ -474,6 +519,9 @@ BitbucketIntegration.factory = ({
   var _a, _b, _c;
   const configs = readBitbucketIntegrationConfigs(
     (_c = config.getOptionalConfigArray("integrations.bitbucket")) != null ? _c : [
+      // if integrations.bitbucket was not used assume the use was migrated to the new configs
+      // and backport for the deprecated integration to be usable for other parts of the system
+      // until these got migrated
       ...(_a = config.getOptionalConfigArray("integrations.bitbucketCloud")) != null ? _a : [],
       ...(_b = config.getOptionalConfigArray("integrations.bitbucketServer")) != null ? _b : []
     ]
@@ -1202,6 +1250,7 @@ const HEADERS = {
   Accept: "application/vnd.github.machine-man-preview+json"
 };
 class GithubAppManager {
+  // undefined allows all installations
   constructor(config, baseUrl) {
     this.cache = new Cache();
     this.allowedInstallationOwners = config.allowedInstallationOwners;
@@ -1322,6 +1371,26 @@ const _SingleInstanceGithubCredentialsProvider = class {
     this.githubAppCredentialsMux = githubAppCredentialsMux;
     this.token = token;
   }
+  /**
+   * Returns {@link GithubCredentials} for a given URL.
+   *
+   * @remarks
+   *
+   * Consecutive calls to this method with the same URL will return cached
+   * credentials.
+   *
+   * The shortest lifetime for a token returned is 10 minutes.
+   *
+   * @example
+   * ```ts
+   * const { token, headers } = await getCredentials({
+   *   url: 'github.com/backstage/foobar'
+   * })
+   * ```
+   *
+   * @param opts - The organization or repository URL
+   * @returns A promise of {@link GithubCredentials}.
+   */
   async getCredentials(opts) {
     const parsed = parseGitUrl__default["default"](opts.url);
     const owner = parsed.owner || parsed.name;
@@ -1359,6 +1428,30 @@ class DefaultGithubCredentialsProvider {
     });
     return new DefaultGithubCredentialsProvider(credentialsProviders);
   }
+  /**
+   * Returns {@link GithubCredentials} for a given URL.
+   *
+   * @remarks
+   *
+   * Consecutive calls to this method with the same URL will return cached
+   * credentials.
+   *
+   * The shortest lifetime for a token returned is 10 minutes.
+   *
+   * @example
+   * ```ts
+   * const { token, headers } = await getCredentials({
+   *   url: 'https://github.com/backstage/foobar'
+   * })
+   *
+   * const { token, headers } = await getCredentials({
+   *   url: 'https://github.com/backstage'
+   * })
+   * ```
+   *
+   * @param opts - The organization or repository URL
+   * @returns A promise of {@link GithubCredentials}.
+   */
   async getCredentials(opts) {
     const parsed = new URL(opts.url);
     const provider = this.providers.get(parsed.host);
@@ -1610,6 +1703,9 @@ class ScmIntegrations {
   get azure() {
     return this.byType.azure;
   }
+  /**
+   * @deprecated in favor of `bitbucketCloud()` and `bitbucketServer()`
+   */
   get bitbucket() {
     return this.byType.bitbucket;
   }