@backstage/integration 0.6.10 → 0.7.2

package/dist/index.d.ts

@@ -397,17 +397,6 @@ declare function readGitHubIntegrationConfig(config: Config): GitHubIntegrationC
  */
 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.
  *
@@ -427,38 +416,12 @@ declare type GithubCredentials = {
     type: GithubCredentialType;
 };
 /**
- * Handles the creation and caching of credentials for GitHub integrations.
+ * This allows implementations to be provided to retrieve GitHub credentials.
  *
  * @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 {@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}.
-     */
+interface GithubCredentialsProvider {
     getCredentials(opts: {
         url: string;
     }): Promise<GithubCredentials>;
@@ -491,6 +454,79 @@ declare function getGitHubRequestOptions(config: GitHubIntegrationConfig, creden
     headers: Record<string, string>;
 };
 
+/**
+ * The configuration parameters for a single AWS S3 provider.
+ *
+ * @public
+ */
+declare type AwsS3IntegrationConfig = {
+    /**
+     * Host, derived from endpoint, and defaults to amazonaws.com
+     */
+    host: string;
+    /**
+     * (Optional) AWS Endpoint.
+     * The endpoint URI to send requests to. The default endpoint is built from the configured region.
+     * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#constructor-property
+     *
+     * Supports non-AWS providers, e.g. for LocalStack, endpoint may look like http://localhost:4566
+     */
+    endpoint?: string;
+    /**
+     * (Optional) Whether to use path style URLs when communicating with S3.
+     * Defaults to false.
+     * This allows providers like LocalStack, Minio and Wasabi (and possibly others) to be used.
+     */
+    s3ForcePathStyle?: boolean;
+    /**
+     * (Optional) User access key id
+     */
+    accessKeyId?: string;
+    /**
+     * (Optional) User secret access key
+     */
+    secretAccessKey?: string;
+    /**
+     * (Optional) ARN of role to be assumed
+     */
+    roleArn?: string;
+};
+/**
+ * Reads a single Aws S3 integration config.
+ *
+ * @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>;
+    get type(): string;
+    get title(): string;
+    get config(): AwsS3IntegrationConfig;
+    constructor(integrationConfig: AwsS3IntegrationConfig);
+    resolveUrl(options: {
+        url: string;
+        base: string;
+        lineNumber?: number | undefined;
+    }): string;
+    resolveEditUrl(url: string): string;
+}
+
 /**
  * A GitHub based integration.
  *
@@ -526,12 +562,12 @@ declare function replaceGitHubUrlType(url: string, type: 'blob' | 'tree' | 'edit
  */
 declare type GitLabIntegrationConfig = {
     /**
-     * The host of the target that this matches on, e.g. "gitlab.com".
+     * The host of the target that this matches on, e.g. `gitlab.com`.
      */
     host: string;
     /**
      * The base URL of the API of this provider, e.g.
-     * "https://gitlab.com/api/v4", with no trailing slash.
+     * `https://gitlab.com/api/v4`, with no trailing slash.
      *
      * May be omitted specifically for public GitLab; then it will be deduced.
      */
@@ -543,10 +579,10 @@ declare type GitLabIntegrationConfig = {
      */
     token?: string;
     /**
-     * The baseUrl of this provider, e.g. "https://gitlab.com", which is passed
+     * The baseUrl of this provider, e.g. `https://gitlab.com`, which is passed
      * into the GitLab client.
      *
-     * If no baseUrl is provided, it will default to https://${host}
+     * If no baseUrl is provided, it will default to `https://${host}`
      */
     baseUrl: string;
 };
@@ -566,34 +602,6 @@ declare function readGitLabIntegrationConfig(config: Config): GitLabIntegrationC
  */
 declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrationConfig[];
 
-/**
- * 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
- * -or-
- * 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
- * @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
- * @public
- */
-declare function getGitLabRequestOptions(config: GitLabIntegrationConfig): {
-    headers: Record<string, string>;
-};
-
 /**
  * A GitLab based integration.
  *
@@ -614,102 +622,6 @@ declare class GitLabIntegration implements ScmIntegration {
     resolveEditUrl(url: string): string;
 }
 
-/**
- * The configuration parameters for a single Google Cloud Storage provider.
- *
- * @public
- */
-declare type GoogleGcsIntegrationConfig = {
-    /**
-     * Service account email used to authenticate requests.
-     */
-    clientEmail?: string;
-    /**
-     * Service account private key used to authenticate requests.
-     */
-    privateKey?: string;
-};
-/**
- * Reads a single Google GCS integration config.
- *
- * @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 = {
-    /**
-     * The host of the target that this matches on, e.g. "amazonaws.com"
-     *
-     * Currently only "amazonaws.com" is supported.
-     */
-    host: string;
-    /**
-     * accessKeyId
-     */
-    accessKeyId?: string;
-    /**
-     * secretAccessKey
-     */
-    secretAccessKey?: string;
-    /**
-     * roleArn
-     */
-    roleArn?: string;
-};
-/**
- * Reads a single Aws S3 integration config.
- *
- * @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>;
-    get type(): string;
-    get title(): string;
-    get config(): AwsS3IntegrationConfig;
-    constructor(integrationConfig: AwsS3IntegrationConfig);
-    resolveUrl(options: {
-        url: string;
-        base: string;
-        lineNumber?: number | undefined;
-    }): string;
-    resolveEditUrl(url: string): string;
-}
-
-/**
- * Default implementation of {@link ScmIntegration} `resolveUrl`, that only
- * works with URL pathname based providers.
- *
- * @public
- */
-declare function defaultScmResolveUrl(options: {
-    url: string;
-    base: string;
-    lineNumber?: number;
-}): string;
-
 /**
  * Holds all registered SCM integrations, of all types.
  *
@@ -761,6 +673,159 @@ interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
     resolveEditUrl(url: string): string;
 }
 
+/**
+ * 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 DefaultGithubCredentialsProvider implements GithubCredentialsProvider {
+    private readonly providers;
+    static fromIntegrations(integrations: ScmIntegrationRegistry): DefaultGithubCredentialsProvider;
+    private constructor();
+    /**
+     * 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}.
+     */
+    getCredentials(opts: {
+        url: string;
+    }): Promise<GithubCredentials>;
+}
+
+/**
+ * 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>;
+}
+/**
+ * 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 SingleInstanceGithubCredentialsProvider implements GithubCredentialsProvider {
+    private readonly githubAppCredentialsMux;
+    private readonly token?;
+    static create: (config: GitHubIntegrationConfig) => GithubCredentialsProvider;
+    private constructor();
+    /**
+     * 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}.
+     */
+    getCredentials(opts: {
+        url: string;
+    }): Promise<GithubCredentials>;
+}
+
+/**
+ * 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
+ * -or-
+ * 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
+ * @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
+ * @public
+ */
+declare function getGitLabRequestOptions(config: GitLabIntegrationConfig): {
+    headers: Record<string, string>;
+};
+
+/**
+ * The configuration parameters for a single Google Cloud Storage provider.
+ *
+ * @public
+ */
+declare type GoogleGcsIntegrationConfig = {
+    /**
+     * Service account email used to authenticate requests.
+     */
+    clientEmail?: string;
+    /**
+     * Service account private key used to authenticate requests.
+     */
+    privateKey?: string;
+};
+/**
+ * Reads a single Google GCS integration config.
+ *
+ * @param config - The config object of a single integration
+ * @public
+ */
+declare function readGoogleGcsIntegrationConfig(config: Config): GoogleGcsIntegrationConfig;
+
+/**
+ * Default implementation of {@link ScmIntegration} `resolveUrl`, that only
+ * works with URL pathname based providers.
+ *
+ * @public
+ */
+declare function defaultScmResolveUrl(options: {
+    url: string;
+    base: string;
+    lineNumber?: number;
+}): string;
+
 /**
  * The set of supported integrations.
  *
@@ -798,4 +863,4 @@ declare class ScmIntegrations implements ScmIntegrationRegistry {
     resolveEditUrl(url: string): string;
 }
 
-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 };
+export { AwsS3Integration, AwsS3IntegrationConfig, AzureIntegration, AzureIntegrationConfig, BitbucketIntegration, BitbucketIntegrationConfig, DefaultGithubCredentialsProvider, GitHubIntegration, GitHubIntegrationConfig, GitLabIntegration, GitLabIntegrationConfig, GithubAppConfig, GithubAppCredentialsMux, GithubCredentialType, GithubCredentials, GithubCredentialsProvider, GoogleGcsIntegrationConfig, IntegrationsByType, ScmIntegration, ScmIntegrationRegistry, ScmIntegrations, ScmIntegrationsFactory, ScmIntegrationsGroup, SingleInstanceGithubCredentialsProvider, 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 };