@backstage/integration 1.4.2-next.0 → 1.4.2

package/dist/index.esm.js

@@ -184,6 +184,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);
@@ -218,6 +223,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)) {
@@ -233,6 +243,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(
@@ -247,6 +262,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");
@@ -260,6 +280,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");
@@ -268,18 +293,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);
   }
@@ -326,6 +366,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;
@@ -465,6 +510,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 : []
     ]
@@ -1193,6 +1241,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;
@@ -1313,6 +1362,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(opts.url);
     const owner = parsed.owner || parsed.name;
@@ -1350,6 +1419,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);
@@ -1601,6 +1694,9 @@ class ScmIntegrations {
   get azure() {
     return this.byType.azure;
   }
+  /**
+   * @deprecated in favor of `bitbucketCloud()` and `bitbucketServer()`
+   */
   get bitbucket() {
     return this.byType.bitbucket;
   }