@backstage/integration 0.6.6 → 0.6.10

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { RestEndpointMethodTypes } from '@octokit/rest';
 
 /**
  * Encapsulates a single SCM integration.
+ *
+ * @public
  */
 interface ScmIntegration {
     /**
@@ -25,14 +27,19 @@ interface ScmIntegration {
      * within the file tree of a certain repo, an absolute path of `/b.yaml` does
      * not resolve to `https://hostname/b.yaml` but rather to
      * `<repo root url>/b.yaml` inside the file tree of that same repo.
-     *
-     * @param options.url The (absolute or relative) URL or path to resolve
-     * @param options.base The base URL onto which this resolution happens
-     * @param options.lineNumber The line number in the target file to link to, starting with 1. Only applicable when linking to files.
      */
     resolveUrl(options: {
+        /**
+         * The (absolute or relative) URL or path to resolve
+         */
         url: string;
+        /**
+         * The base URL onto which this resolution happens
+         */
         base: string;
+        /**
+         * The line number in the target file to link to, starting with 1. Only applicable when linking to files.
+         */
         lineNumber?: number;
     }): string;
     /**
@@ -44,12 +51,14 @@ interface ScmIntegration {
      * If this is not possible, the integration can fall back to a URL to view
      * the file in the web interface.
      *
-     * @param url The absolute URL to the file that should be edited.
+     * @param url - The absolute URL to the file that should be edited.
      */
     resolveEditUrl(url: string): string;
 }
 /**
  * Encapsulates several integrations, that are all of the same type.
+ *
+ * @public
  */
 interface ScmIntegrationsGroup<T extends ScmIntegration> {
     /**
@@ -59,22 +68,29 @@ interface ScmIntegrationsGroup<T extends ScmIntegration> {
     /**
      * Fetches an integration of this type by URL.
      *
-     * @param url A URL that matches a registered integration of this type
+     * @param url - A URL that matches a registered integration of this type
      */
     byUrl(url: string | URL): T | undefined;
     /**
      * Fetches an integration of this type by host name.
      *
-     * @param url A host name that matches a registered integration of this type
+     * @param host - A host name that matches a registered integration of this type
      */
     byHost(host: string): T | undefined;
 }
+/**
+ * A factory function that creates an integration group based on configuration.
+ *
+ * @public
+ */
 declare type ScmIntegrationsFactory<T extends ScmIntegration> = (options: {
     config: Config;
 }) => ScmIntegrationsGroup<T>;
 
 /**
  * The configuration parameters for a single Azure provider.
+ *
+ * @public
  */
 declare type AzureIntegrationConfig = {
     /**
@@ -93,17 +109,24 @@ declare type AzureIntegrationConfig = {
 /**
  * Reads a single Azure integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 declare function readAzureIntegrationConfig(config: Config): AzureIntegrationConfig;
 /**
  * Reads a set of Azure integration configs, and inserts some defaults for
  * public Azure if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 declare function readAzureIntegrationConfigs(configs: Config[]): AzureIntegrationConfig[];
 
+/**
+ * Microsoft Azure based integration.
+ *
+ * @public
+ */
 declare class AzureIntegration implements ScmIntegration {
     private readonly integrationConfig;
     static factory: ScmIntegrationsFactory<AzureIntegration>;
@@ -123,35 +146,45 @@ declare class AzureIntegration implements ScmIntegration {
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
- * from: https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents
- * to:   https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}
+ * - from: `https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents`
+ * - to:   `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}`
  *
- * @param url A URL pointing to a file
+ * @param url - A URL pointing to a file
+ * @public
  */
 declare function getAzureFileFetchUrl(url: string): string;
 /**
  * Given a URL pointing to a path on a provider, returns a URL that is suitable
  * for downloading the subtree.
  *
- * @param url A URL pointing to a path
+ * @param url - A URL pointing to a path
+ * @public
  */
 declare function getAzureDownloadUrl(url: string): string;
 /**
  * Given a URL, return the API URL to fetch commits on the branch.
  *
- * @param url A URL pointing to a repository or a sub-path
+ * @param url - A URL pointing to a repository or a sub-path
+ * @public
  */
 declare function getAzureCommitsUrl(url: string): string;
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
-declare function getAzureRequestOptions(config: AzureIntegrationConfig, additionalHeaders?: Record<string, string>): RequestInit;
+declare function getAzureRequestOptions(config: AzureIntegrationConfig, additionalHeaders?: Record<string, string>): {
+    headers: Record<string, string>;
+};
 
 /**
  * The configuration parameters for a single Bitbucket API provider.
+ *
+ * @public
  */
 declare type BitbucketIntegrationConfig = {
     /**
@@ -190,17 +223,24 @@ declare type BitbucketIntegrationConfig = {
 /**
  * Reads a single Bitbucket integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 declare function readBitbucketIntegrationConfig(config: Config): BitbucketIntegrationConfig;
 /**
  * Reads a set of Bitbucket integration configs, and inserts some defaults for
  * public Bitbucket if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 declare function readBitbucketIntegrationConfigs(configs: Config[]): BitbucketIntegrationConfig[];
 
+/**
+ * A Bitbucket based integration.
+ *
+ * @public
+ */
 declare class BitbucketIntegration implements ScmIntegration {
     private readonly integrationConfig;
     static factory: ScmIntegrationsFactory<BitbucketIntegration>;
@@ -219,39 +259,49 @@ declare class BitbucketIntegration implements ScmIntegration {
 /**
  * Given a URL pointing to a path on a provider, returns the default branch.
  *
- * @param url A URL pointing to a path
- * @param config The relevant provider config
+ * @param url - A URL pointing to a path
+ * @param config - The relevant provider config
+ * @public
  */
 declare function getBitbucketDefaultBranch(url: string, config: BitbucketIntegrationConfig): Promise<string>;
 /**
  * Given a URL pointing to a path on a provider, returns a URL that is suitable
  * for downloading the subtree.
  *
- * @param url A URL pointing to a path
- * @param config The relevant provider config
+ * @param url - A URL pointing to a path
+ * @param config - The relevant provider config
+ * @public
  */
 declare function getBitbucketDownloadUrl(url: string, config: BitbucketIntegrationConfig): Promise<string>;
 /**
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
  * from: https://bitbucket.org/orgname/reponame/src/master/file.yaml
  * to:   https://api.bitbucket.org/2.0/repositories/orgname/reponame/src/master/file.yaml
  *
- * @param url A URL pointing to a file
- * @param config The relevant provider config
+ * @param url - A URL pointing to a file
+ * @param config - The relevant provider config
+ * @public
  */
 declare function getBitbucketFileFetchUrl(url: string, config: BitbucketIntegrationConfig): string;
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
-declare function getBitbucketRequestOptions(config: BitbucketIntegrationConfig): RequestInit;
+declare function getBitbucketRequestOptions(config: BitbucketIntegrationConfig): {
+    headers: Record<string, string>;
+};
 
 /**
  * The configuration parameters for a single GitHub integration.
+ *
+ * @public
  */
 declare type GitHubIntegrationConfig = {
     /**
@@ -293,7 +343,12 @@ declare type GitHubIntegrationConfig = {
 };
 /**
  * The configuration parameters for authenticating a GitHub Application.
- * A Github Apps configuration can be generated using the `backstage-cli create-github-app` command.
+ *
+ * @remarks
+ *
+ * A GitHub Apps configuration can be generated using the `backstage-cli create-github-app` command.
+ *
+ * @public
  */
 declare type GithubAppConfig = {
     /**
@@ -329,24 +384,41 @@ declare type GithubAppConfig = {
 /**
  * Reads a single GitHub integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 declare function readGitHubIntegrationConfig(config: Config): GitHubIntegrationConfig;
 /**
  * Reads a set of GitHub integration configs, and inserts some defaults for
  * public GitHub if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 declare function readGitHubIntegrationConfigs(configs: Config[]): GitHubIntegrationConfig[];
 
+/**
+ * Corresponds to a Github installation which internally could hold several GitHub Apps.
+ *
+ * @public
+ */
 declare class GithubAppCredentialsMux {
     private readonly apps;
     constructor(config: GitHubIntegrationConfig);
     getAllInstallations(): Promise<RestEndpointMethodTypes['apps']['listInstallations']['response']['data']>;
     getAppToken(owner: string, repo?: string): Promise<string | undefined>;
 }
+/**
+ * The type of credentials produced by the credential provider.
+ *
+ * @public
+ */
 declare type GithubCredentialType = 'app' | 'token';
+/**
+ * A set of credentials information for a GitHub integration.
+ *
+ * @public
+ */
 declare type GithubCredentials = {
     headers?: {
         [name: string]: string;
@@ -354,19 +426,38 @@ declare type GithubCredentials = {
     token?: string;
     type: GithubCredentialType;
 };
+/**
+ * Handles the creation and caching of credentials for GitHub integrations.
+ *
+ * @public
+ * @remarks
+ *
+ * TODO: Possibly move this to a backend only package so that it's not used in the frontend by mistake
+ */
 declare class GithubCredentialsProvider {
     private readonly githubAppCredentialsMux;
     private readonly token?;
     static create(config: GitHubIntegrationConfig): GithubCredentialsProvider;
     private constructor();
     /**
-     * Returns GithubCredentials for requested url.
-     * Consecutive calls to this method with the same url will return cached credentials.
+     * 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.
-     * @param opts containing the organization or repository url
-     * @returns {Promise} of @type {GithubCredentials}.
+     *
      * @example
-     * const { token, headers } = await getCredentials({url: 'github.com/backstage/foobar'})
+     * ```ts
+     * const { token, headers } = await getCredentials({
+     *   url: 'github.com/backstage/foobar'
+     * })
+     * ```
+     *
+     * @param opts - The organization or repository URL
+     * @returns A promise of {@link GithubCredentials}.
      */
     getCredentials(opts: {
         url: string;
@@ -377,23 +468,34 @@ declare class GithubCredentialsProvider {
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
  * from: https://github.com/a/b/blob/branchname/path/to/c.yaml
  * to:   https://api.github.com/repos/a/b/contents/path/to/c.yaml?ref=branchname
  * or:   https://raw.githubusercontent.com/a/b/branchname/c.yaml
  *
- * @param url A URL pointing to a file
- * @param config The relevant provider config
+ * @param url - A URL pointing to a file
+ * @param config - The relevant provider config
+ * @public
  */
 declare function getGitHubFileFetchUrl(url: string, config: GitHubIntegrationConfig, credentials: GithubCredentials): string;
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
  * @deprecated This function is no longer used internally
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
-declare function getGitHubRequestOptions(config: GitHubIntegrationConfig, credentials: GithubCredentials): RequestInit;
+declare function getGitHubRequestOptions(config: GitHubIntegrationConfig, credentials: GithubCredentials): {
+    headers: Record<string, string>;
+};
 
+/**
+ * A GitHub based integration.
+ *
+ * @public
+ */
 declare class GitHubIntegration implements ScmIntegration {
     private readonly integrationConfig;
     static factory: ScmIntegrationsFactory<GitHubIntegration>;
@@ -408,10 +510,19 @@ declare class GitHubIntegration implements ScmIntegration {
     }): string;
     resolveEditUrl(url: string): string;
 }
-declare function replaceUrlType(url: string, type: 'blob' | 'tree' | 'edit'): string;
+/**
+ * Takes a GitHub URL and replaces the type part (blob, tree etc).
+ *
+ * @param url - The original URL
+ * @param type - The desired type, e.g. "blob"
+ * @public
+ */
+declare function replaceGitHubUrlType(url: string, type: 'blob' | 'tree' | 'edit'): string;
 
 /**
  * The configuration parameters for a single GitLab integration.
+ *
+ * @public
  */
 declare type GitLabIntegrationConfig = {
     /**
@@ -442,14 +553,16 @@ declare type GitLabIntegrationConfig = {
 /**
  * Reads a single GitLab integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 declare function readGitLabIntegrationConfig(config: Config): GitLabIntegrationConfig;
 /**
  * Reads a set of GitLab integration configs, and inserts some defaults for
  * public GitLab if not specified.
  *
- * @param configs All of the integration config objects
+ * @param configs - All of the integration config objects
+ * @public
  */
 declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrationConfig[];
 
@@ -457,6 +570,8 @@ declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrat
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
  * for fetching the contents of the data.
  *
+ * @remarks
+ *
  * Converts
  * from: https://gitlab.example.com/a/b/blob/master/c.yaml
  * to:   https://gitlab.example.com/a/b/raw/master/c.yaml
@@ -464,17 +579,26 @@ declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrat
  * from: https://gitlab.com/groupA/teams/teamA/subgroupA/repoA/-/blob/branch/filepath
  * to:   https://gitlab.com/api/v4/projects/projectId/repository/files/filepath?ref=branch
  *
- * @param url A URL pointing to a file
- * @param config The relevant provider config
+ * @param url - A URL pointing to a file
+ * @param config - The relevant provider config
+ * @public
  */
 declare function getGitLabFileFetchUrl(url: string, config: GitLabIntegrationConfig): Promise<string>;
 /**
  * Gets the request options necessary to make requests to a given provider.
  *
- * @param config The relevant provider config
+ * @param config - The relevant provider config
+ * @public
  */
-declare function getGitLabRequestOptions(config: GitLabIntegrationConfig): RequestInit;
+declare function getGitLabRequestOptions(config: GitLabIntegrationConfig): {
+    headers: Record<string, string>;
+};
 
+/**
+ * A GitLab based integration.
+ *
+ * @public
+ */
 declare class GitLabIntegration implements ScmIntegration {
     private readonly integrationConfig;
     static factory: ScmIntegrationsFactory<GitLabIntegration>;
@@ -492,6 +616,8 @@ declare class GitLabIntegration implements ScmIntegration {
 
 /**
  * The configuration parameters for a single Google Cloud Storage provider.
+ *
+ * @public
  */
 declare type GoogleGcsIntegrationConfig = {
     /**
@@ -506,12 +632,15 @@ declare type GoogleGcsIntegrationConfig = {
 /**
  * Reads a single Google GCS integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 declare function readGoogleGcsIntegrationConfig(config: Config): GoogleGcsIntegrationConfig;
 
 /**
  * The configuration parameters for a single AWS S3 provider.
+ *
+ * @public
  */
 declare type AwsS3IntegrationConfig = {
     /**
@@ -536,11 +665,24 @@ declare type AwsS3IntegrationConfig = {
 /**
  * Reads a single Aws S3 integration config.
  *
- * @param config The config object of a single integration
+ * @param config - The config object of a single integration
+ * @public
  */
 declare function readAwsS3IntegrationConfig(config: Config): AwsS3IntegrationConfig;
+/**
+ * Reads a set of AWS S3 integration configs, and inserts some defaults for
+ * public Amazon AWS if not specified.
+ *
+ * @param configs - The config objects of the integrations
+ * @public
+ */
 declare function readAwsS3IntegrationConfigs(configs: Config[]): AwsS3IntegrationConfig[];
 
+/**
+ * Integrates with AWS S3 or compatible solutions.
+ *
+ * @public
+ */
 declare class AwsS3Integration implements ScmIntegration {
     private readonly integrationConfig;
     static factory: ScmIntegrationsFactory<AwsS3Integration>;
@@ -557,8 +699,10 @@ declare class AwsS3Integration implements ScmIntegration {
 }
 
 /**
- * Default implementation of ScmIntegration.resolveUrl, that only works with
- * URL pathname based providers.
+ * Default implementation of {@link ScmIntegration} `resolveUrl`, that only
+ * works with URL pathname based providers.
+ *
+ * @public
  */
 declare function defaultScmResolveUrl(options: {
     url: string;
@@ -568,6 +712,8 @@ declare function defaultScmResolveUrl(options: {
 
 /**
  * Holds all registered SCM integrations, of all types.
+ *
+ * @public
  */
 interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
     awsS3: ScmIntegrationsGroup<AwsS3Integration>;
@@ -586,14 +732,19 @@ interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
      * within the file tree of a certain repo, an absolute path of `/b.yaml` does
      * not resolve to `https://hostname/b.yaml` but rather to
      * `<repo root url>/b.yaml` inside the file tree of that same repo.
-     *
-     * @param options.url The (absolute or relative) URL or path to resolve
-     * @param options.base The base URL onto which this resolution happens
-     * @param options.lineNumber The line number in the target file to link to, starting with 1. Only applicable when linking to files.
      */
     resolveUrl(options: {
+        /**
+         * The (absolute or relative) URL or path to resolve.
+         */
         url: string;
+        /**
+         * The base URL onto which this resolution happens
+         */
         base: string;
+        /**
+         * The line number in the target file to link to, starting with 1. Only applicable when linking to files.
+         */
         lineNumber?: number;
     }): string;
     /**
@@ -605,18 +756,28 @@ interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
      * If this is not possible, the integration can fall back to a URL to view
      * the file in the web interface.
      *
-     * @param url The absolute URL to the file that should be edited.
+     * @param url - The absolute URL to the file that should be edited.
      */
     resolveEditUrl(url: string): string;
 }
 
-declare type IntegrationsByType = {
+/**
+ * The set of supported integrations.
+ *
+ * @public
+ */
+interface IntegrationsByType {
     awsS3: ScmIntegrationsGroup<AwsS3Integration>;
     azure: ScmIntegrationsGroup<AzureIntegration>;
     bitbucket: ScmIntegrationsGroup<BitbucketIntegration>;
     github: ScmIntegrationsGroup<GitHubIntegration>;
     gitlab: ScmIntegrationsGroup<GitLabIntegration>;
-};
+}
+/**
+ * Exposes the set of supported integrations.
+ *
+ * @public
+ */
 declare class ScmIntegrations implements ScmIntegrationRegistry {
     private readonly byType;
     static fromConfig(config: Config): ScmIntegrations;
@@ -637,4 +798,4 @@ declare class ScmIntegrations implements ScmIntegrationRegistry {
     resolveEditUrl(url: string): string;
 }
 
-export { AwsS3Integration, AwsS3IntegrationConfig, AzureIntegration, AzureIntegrationConfig, BitbucketIntegration, BitbucketIntegrationConfig, GitHubIntegration, GitHubIntegrationConfig, GitLabIntegration, GitLabIntegrationConfig, GithubAppCredentialsMux, GithubCredentialType, GithubCredentialsProvider, GoogleGcsIntegrationConfig, ScmIntegration, ScmIntegrationRegistry, ScmIntegrations, ScmIntegrationsGroup, defaultScmResolveUrl, getAzureCommitsUrl, getAzureDownloadUrl, getAzureFileFetchUrl, getAzureRequestOptions, getBitbucketDefaultBranch, getBitbucketDownloadUrl, getBitbucketFileFetchUrl, getBitbucketRequestOptions, getGitHubFileFetchUrl, getGitHubRequestOptions, getGitLabFileFetchUrl, getGitLabRequestOptions, readAwsS3IntegrationConfig, readAwsS3IntegrationConfigs, readAzureIntegrationConfig, readAzureIntegrationConfigs, readBitbucketIntegrationConfig, readBitbucketIntegrationConfigs, readGitHubIntegrationConfig, readGitHubIntegrationConfigs, readGitLabIntegrationConfig, readGitLabIntegrationConfigs, readGoogleGcsIntegrationConfig, replaceUrlType as replaceGitHubUrlType };
+export { AwsS3Integration, AwsS3IntegrationConfig, AzureIntegration, AzureIntegrationConfig, BitbucketIntegration, BitbucketIntegrationConfig, GitHubIntegration, GitHubIntegrationConfig, GitLabIntegration, GitLabIntegrationConfig, GithubAppConfig, GithubAppCredentialsMux, GithubCredentialType, GithubCredentials, GithubCredentialsProvider, GoogleGcsIntegrationConfig, IntegrationsByType, ScmIntegration, ScmIntegrationRegistry, ScmIntegrations, ScmIntegrationsFactory, ScmIntegrationsGroup, defaultScmResolveUrl, getAzureCommitsUrl, getAzureDownloadUrl, getAzureFileFetchUrl, getAzureRequestOptions, getBitbucketDefaultBranch, getBitbucketDownloadUrl, getBitbucketFileFetchUrl, getBitbucketRequestOptions, getGitHubFileFetchUrl, getGitHubRequestOptions, getGitLabFileFetchUrl, getGitLabRequestOptions, readAwsS3IntegrationConfig, readAwsS3IntegrationConfigs, readAzureIntegrationConfig, readAzureIntegrationConfigs, readBitbucketIntegrationConfig, readBitbucketIntegrationConfigs, readGitHubIntegrationConfig, readGitHubIntegrationConfigs, readGitLabIntegrationConfig, readGitLabIntegrationConfigs, readGoogleGcsIntegrationConfig, replaceGitHubUrlType };