@backstage/integration 0.6.7 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -3,6 +3,8 @@ import { RestEndpointMethodTypes } from '@octokit/rest';
3
3
 
4
4
  /**
5
5
  * Encapsulates a single SCM integration.
6
+ *
7
+ * @public
6
8
  */
7
9
  interface ScmIntegration {
8
10
  /**
@@ -25,14 +27,19 @@ interface ScmIntegration {
25
27
  * within the file tree of a certain repo, an absolute path of `/b.yaml` does
26
28
  * not resolve to `https://hostname/b.yaml` but rather to
27
29
  * `<repo root url>/b.yaml` inside the file tree of that same repo.
28
- *
29
- * @param options.url The (absolute or relative) URL or path to resolve
30
- * @param options.base The base URL onto which this resolution happens
31
- * @param options.lineNumber The line number in the target file to link to, starting with 1. Only applicable when linking to files.
32
30
  */
33
31
  resolveUrl(options: {
32
+ /**
33
+ * The (absolute or relative) URL or path to resolve
34
+ */
34
35
  url: string;
36
+ /**
37
+ * The base URL onto which this resolution happens
38
+ */
35
39
  base: string;
40
+ /**
41
+ * The line number in the target file to link to, starting with 1. Only applicable when linking to files.
42
+ */
36
43
  lineNumber?: number;
37
44
  }): string;
38
45
  /**
@@ -44,12 +51,14 @@ interface ScmIntegration {
44
51
  * If this is not possible, the integration can fall back to a URL to view
45
52
  * the file in the web interface.
46
53
  *
47
- * @param url The absolute URL to the file that should be edited.
54
+ * @param url - The absolute URL to the file that should be edited.
48
55
  */
49
56
  resolveEditUrl(url: string): string;
50
57
  }
51
58
  /**
52
59
  * Encapsulates several integrations, that are all of the same type.
60
+ *
61
+ * @public
53
62
  */
54
63
  interface ScmIntegrationsGroup<T extends ScmIntegration> {
55
64
  /**
@@ -59,22 +68,29 @@ interface ScmIntegrationsGroup<T extends ScmIntegration> {
59
68
  /**
60
69
  * Fetches an integration of this type by URL.
61
70
  *
62
- * @param url A URL that matches a registered integration of this type
71
+ * @param url - A URL that matches a registered integration of this type
63
72
  */
64
73
  byUrl(url: string | URL): T | undefined;
65
74
  /**
66
75
  * Fetches an integration of this type by host name.
67
76
  *
68
- * @param url A host name that matches a registered integration of this type
77
+ * @param host - A host name that matches a registered integration of this type
69
78
  */
70
79
  byHost(host: string): T | undefined;
71
80
  }
81
+ /**
82
+ * A factory function that creates an integration group based on configuration.
83
+ *
84
+ * @public
85
+ */
72
86
  declare type ScmIntegrationsFactory<T extends ScmIntegration> = (options: {
73
87
  config: Config;
74
88
  }) => ScmIntegrationsGroup<T>;
75
89
 
76
90
  /**
77
91
  * The configuration parameters for a single Azure provider.
92
+ *
93
+ * @public
78
94
  */
79
95
  declare type AzureIntegrationConfig = {
80
96
  /**
@@ -93,17 +109,24 @@ declare type AzureIntegrationConfig = {
93
109
  /**
94
110
  * Reads a single Azure integration config.
95
111
  *
96
- * @param config The config object of a single integration
112
+ * @param config - The config object of a single integration
113
+ * @public
97
114
  */
98
115
  declare function readAzureIntegrationConfig(config: Config): AzureIntegrationConfig;
99
116
  /**
100
117
  * Reads a set of Azure integration configs, and inserts some defaults for
101
118
  * public Azure if not specified.
102
119
  *
103
- * @param configs All of the integration config objects
120
+ * @param configs - All of the integration config objects
121
+ * @public
104
122
  */
105
123
  declare function readAzureIntegrationConfigs(configs: Config[]): AzureIntegrationConfig[];
106
124
 
125
+ /**
126
+ * Microsoft Azure based integration.
127
+ *
128
+ * @public
129
+ */
107
130
  declare class AzureIntegration implements ScmIntegration {
108
131
  private readonly integrationConfig;
109
132
  static factory: ScmIntegrationsFactory<AzureIntegration>;
@@ -123,35 +146,45 @@ declare class AzureIntegration implements ScmIntegration {
123
146
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
124
147
  * for fetching the contents of the data.
125
148
  *
149
+ * @remarks
150
+ *
126
151
  * Converts
127
- * from: https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents
128
- * to: https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}
152
+ * - from: `https://dev.azure.com/{organization}/{project}/_git/reponame?path={path}&version=GB{commitOrBranch}&_a=contents`
153
+ * - to: `https://dev.azure.com/{organization}/{project}/_apis/git/repositories/reponame/items?path={path}&version={commitOrBranch}`
129
154
  *
130
- * @param url A URL pointing to a file
155
+ * @param url - A URL pointing to a file
156
+ * @public
131
157
  */
132
158
  declare function getAzureFileFetchUrl(url: string): string;
133
159
  /**
134
160
  * Given a URL pointing to a path on a provider, returns a URL that is suitable
135
161
  * for downloading the subtree.
136
162
  *
137
- * @param url A URL pointing to a path
163
+ * @param url - A URL pointing to a path
164
+ * @public
138
165
  */
139
166
  declare function getAzureDownloadUrl(url: string): string;
140
167
  /**
141
168
  * Given a URL, return the API URL to fetch commits on the branch.
142
169
  *
143
- * @param url A URL pointing to a repository or a sub-path
170
+ * @param url - A URL pointing to a repository or a sub-path
171
+ * @public
144
172
  */
145
173
  declare function getAzureCommitsUrl(url: string): string;
146
174
  /**
147
175
  * Gets the request options necessary to make requests to a given provider.
148
176
  *
149
- * @param config The relevant provider config
177
+ * @param config - The relevant provider config
178
+ * @public
150
179
  */
151
- declare function getAzureRequestOptions(config: AzureIntegrationConfig, additionalHeaders?: Record<string, string>): RequestInit;
180
+ declare function getAzureRequestOptions(config: AzureIntegrationConfig, additionalHeaders?: Record<string, string>): {
181
+ headers: Record<string, string>;
182
+ };
152
183
 
153
184
  /**
154
185
  * The configuration parameters for a single Bitbucket API provider.
186
+ *
187
+ * @public
155
188
  */
156
189
  declare type BitbucketIntegrationConfig = {
157
190
  /**
@@ -190,17 +223,24 @@ declare type BitbucketIntegrationConfig = {
190
223
  /**
191
224
  * Reads a single Bitbucket integration config.
192
225
  *
193
- * @param config The config object of a single integration
226
+ * @param config - The config object of a single integration
227
+ * @public
194
228
  */
195
229
  declare function readBitbucketIntegrationConfig(config: Config): BitbucketIntegrationConfig;
196
230
  /**
197
231
  * Reads a set of Bitbucket integration configs, and inserts some defaults for
198
232
  * public Bitbucket if not specified.
199
233
  *
200
- * @param configs All of the integration config objects
234
+ * @param configs - All of the integration config objects
235
+ * @public
201
236
  */
202
237
  declare function readBitbucketIntegrationConfigs(configs: Config[]): BitbucketIntegrationConfig[];
203
238
 
239
+ /**
240
+ * A Bitbucket based integration.
241
+ *
242
+ * @public
243
+ */
204
244
  declare class BitbucketIntegration implements ScmIntegration {
205
245
  private readonly integrationConfig;
206
246
  static factory: ScmIntegrationsFactory<BitbucketIntegration>;
@@ -219,39 +259,49 @@ declare class BitbucketIntegration implements ScmIntegration {
219
259
  /**
220
260
  * Given a URL pointing to a path on a provider, returns the default branch.
221
261
  *
222
- * @param url A URL pointing to a path
223
- * @param config The relevant provider config
262
+ * @param url - A URL pointing to a path
263
+ * @param config - The relevant provider config
264
+ * @public
224
265
  */
225
266
  declare function getBitbucketDefaultBranch(url: string, config: BitbucketIntegrationConfig): Promise<string>;
226
267
  /**
227
268
  * Given a URL pointing to a path on a provider, returns a URL that is suitable
228
269
  * for downloading the subtree.
229
270
  *
230
- * @param url A URL pointing to a path
231
- * @param config The relevant provider config
271
+ * @param url - A URL pointing to a path
272
+ * @param config - The relevant provider config
273
+ * @public
232
274
  */
233
275
  declare function getBitbucketDownloadUrl(url: string, config: BitbucketIntegrationConfig): Promise<string>;
234
276
  /**
235
277
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
236
278
  * for fetching the contents of the data.
237
279
  *
280
+ * @remarks
281
+ *
238
282
  * Converts
239
283
  * from: https://bitbucket.org/orgname/reponame/src/master/file.yaml
240
284
  * to: https://api.bitbucket.org/2.0/repositories/orgname/reponame/src/master/file.yaml
241
285
  *
242
- * @param url A URL pointing to a file
243
- * @param config The relevant provider config
286
+ * @param url - A URL pointing to a file
287
+ * @param config - The relevant provider config
288
+ * @public
244
289
  */
245
290
  declare function getBitbucketFileFetchUrl(url: string, config: BitbucketIntegrationConfig): string;
246
291
  /**
247
292
  * Gets the request options necessary to make requests to a given provider.
248
293
  *
249
- * @param config The relevant provider config
294
+ * @param config - The relevant provider config
295
+ * @public
250
296
  */
251
- declare function getBitbucketRequestOptions(config: BitbucketIntegrationConfig): RequestInit;
297
+ declare function getBitbucketRequestOptions(config: BitbucketIntegrationConfig): {
298
+ headers: Record<string, string>;
299
+ };
252
300
 
253
301
  /**
254
302
  * The configuration parameters for a single GitHub integration.
303
+ *
304
+ * @public
255
305
  */
256
306
  declare type GitHubIntegrationConfig = {
257
307
  /**
@@ -293,7 +343,12 @@ declare type GitHubIntegrationConfig = {
293
343
  };
294
344
  /**
295
345
  * The configuration parameters for authenticating a GitHub Application.
296
- * A Github Apps configuration can be generated using the `backstage-cli create-github-app` command.
346
+ *
347
+ * @remarks
348
+ *
349
+ * A GitHub Apps configuration can be generated using the `backstage-cli create-github-app` command.
350
+ *
351
+ * @public
297
352
  */
298
353
  declare type GithubAppConfig = {
299
354
  /**
@@ -329,24 +384,30 @@ declare type GithubAppConfig = {
329
384
  /**
330
385
  * Reads a single GitHub integration config.
331
386
  *
332
- * @param config The config object of a single integration
387
+ * @param config - The config object of a single integration
388
+ * @public
333
389
  */
334
390
  declare function readGitHubIntegrationConfig(config: Config): GitHubIntegrationConfig;
335
391
  /**
336
392
  * Reads a set of GitHub integration configs, and inserts some defaults for
337
393
  * public GitHub if not specified.
338
394
  *
339
- * @param configs All of the integration config objects
395
+ * @param configs - All of the integration config objects
396
+ * @public
340
397
  */
341
398
  declare function readGitHubIntegrationConfigs(configs: Config[]): GitHubIntegrationConfig[];
342
399
 
343
- declare class GithubAppCredentialsMux {
344
- private readonly apps;
345
- constructor(config: GitHubIntegrationConfig);
346
- getAllInstallations(): Promise<RestEndpointMethodTypes['apps']['listInstallations']['response']['data']>;
347
- getAppToken(owner: string, repo?: string): Promise<string | undefined>;
348
- }
400
+ /**
401
+ * The type of credentials produced by the credential provider.
402
+ *
403
+ * @public
404
+ */
349
405
  declare type GithubCredentialType = 'app' | 'token';
406
+ /**
407
+ * A set of credentials information for a GitHub integration.
408
+ *
409
+ * @public
410
+ */
350
411
  declare type GithubCredentials = {
351
412
  headers?: {
352
413
  [name: string]: string;
@@ -354,20 +415,13 @@ declare type GithubCredentials = {
354
415
  token?: string;
355
416
  type: GithubCredentialType;
356
417
  };
357
- declare class GithubCredentialsProvider {
358
- private readonly githubAppCredentialsMux;
359
- private readonly token?;
360
- static create(config: GitHubIntegrationConfig): GithubCredentialsProvider;
361
- private constructor();
362
- /**
363
- * Returns GithubCredentials for requested url.
364
- * Consecutive calls to this method with the same url will return cached credentials.
365
- * The shortest lifetime for a token returned is 10 minutes.
366
- * @param opts containing the organization or repository url
367
- * @returns {Promise} of @type {GithubCredentials}.
368
- * @example
369
- * const { token, headers } = await getCredentials({url: 'github.com/backstage/foobar'})
370
- */
418
+ /**
419
+ * This allows implementations to be provided to retrieve GitHub credentials.
420
+ *
421
+ * @public
422
+ *
423
+ */
424
+ interface GithubCredentialsProvider {
371
425
  getCredentials(opts: {
372
426
  url: string;
373
427
  }): Promise<GithubCredentials>;
@@ -377,23 +431,83 @@ declare class GithubCredentialsProvider {
377
431
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
378
432
  * for fetching the contents of the data.
379
433
  *
434
+ * @remarks
435
+ *
380
436
  * Converts
381
437
  * from: https://github.com/a/b/blob/branchname/path/to/c.yaml
382
438
  * to: https://api.github.com/repos/a/b/contents/path/to/c.yaml?ref=branchname
383
439
  * or: https://raw.githubusercontent.com/a/b/branchname/c.yaml
384
440
  *
385
- * @param url A URL pointing to a file
386
- * @param config The relevant provider config
441
+ * @param url - A URL pointing to a file
442
+ * @param config - The relevant provider config
443
+ * @public
387
444
  */
388
445
  declare function getGitHubFileFetchUrl(url: string, config: GitHubIntegrationConfig, credentials: GithubCredentials): string;
389
446
  /**
390
447
  * Gets the request options necessary to make requests to a given provider.
391
448
  *
392
449
  * @deprecated This function is no longer used internally
393
- * @param config The relevant provider config
450
+ * @param config - The relevant provider config
451
+ * @public
452
+ */
453
+ declare function getGitHubRequestOptions(config: GitHubIntegrationConfig, credentials: GithubCredentials): {
454
+ headers: Record<string, string>;
455
+ };
456
+
457
+ /**
458
+ * Corresponds to a Github installation which internally could hold several GitHub Apps.
459
+ *
460
+ * @public
461
+ */
462
+ declare class GithubAppCredentialsMux {
463
+ private readonly apps;
464
+ constructor(config: GitHubIntegrationConfig);
465
+ getAllInstallations(): Promise<RestEndpointMethodTypes['apps']['listInstallations']['response']['data']>;
466
+ getAppToken(owner: string, repo?: string): Promise<string | undefined>;
467
+ }
468
+ /**
469
+ * Handles the creation and caching of credentials for GitHub integrations.
470
+ *
471
+ * @public
472
+ * @remarks
473
+ *
474
+ * TODO: Possibly move this to a backend only package so that it's not used in the frontend by mistake
394
475
  */
395
- declare function getGitHubRequestOptions(config: GitHubIntegrationConfig, credentials: GithubCredentials): RequestInit;
476
+ declare class SingleInstanceGithubCredentialsProvider implements GithubCredentialsProvider {
477
+ private readonly githubAppCredentialsMux;
478
+ private readonly token?;
479
+ static create: (config: GitHubIntegrationConfig) => GithubCredentialsProvider;
480
+ private constructor();
481
+ /**
482
+ * Returns {@link GithubCredentials} for a given URL.
483
+ *
484
+ * @remarks
485
+ *
486
+ * Consecutive calls to this method with the same URL will return cached
487
+ * credentials.
488
+ *
489
+ * The shortest lifetime for a token returned is 10 minutes.
490
+ *
491
+ * @example
492
+ * ```ts
493
+ * const { token, headers } = await getCredentials({
494
+ * url: 'github.com/backstage/foobar'
495
+ * })
496
+ * ```
497
+ *
498
+ * @param opts - The organization or repository URL
499
+ * @returns A promise of {@link GithubCredentials}.
500
+ */
501
+ getCredentials(opts: {
502
+ url: string;
503
+ }): Promise<GithubCredentials>;
504
+ }
396
505
 
506
+ /**
507
+ * A GitHub based integration.
508
+ *
509
+ * @public
510
+ */
397
511
  declare class GitHubIntegration implements ScmIntegration {
398
512
  private readonly integrationConfig;
399
513
  static factory: ScmIntegrationsFactory<GitHubIntegration>;
@@ -408,10 +522,19 @@ declare class GitHubIntegration implements ScmIntegration {
408
522
  }): string;
409
523
  resolveEditUrl(url: string): string;
410
524
  }
411
- declare function replaceUrlType(url: string, type: 'blob' | 'tree' | 'edit'): string;
525
+ /**
526
+ * Takes a GitHub URL and replaces the type part (blob, tree etc).
527
+ *
528
+ * @param url - The original URL
529
+ * @param type - The desired type, e.g. "blob"
530
+ * @public
531
+ */
532
+ declare function replaceGitHubUrlType(url: string, type: 'blob' | 'tree' | 'edit'): string;
412
533
 
413
534
  /**
414
535
  * The configuration parameters for a single GitLab integration.
536
+ *
537
+ * @public
415
538
  */
416
539
  declare type GitLabIntegrationConfig = {
417
540
  /**
@@ -442,14 +565,16 @@ declare type GitLabIntegrationConfig = {
442
565
  /**
443
566
  * Reads a single GitLab integration config.
444
567
  *
445
- * @param config The config object of a single integration
568
+ * @param config - The config object of a single integration
569
+ * @public
446
570
  */
447
571
  declare function readGitLabIntegrationConfig(config: Config): GitLabIntegrationConfig;
448
572
  /**
449
573
  * Reads a set of GitLab integration configs, and inserts some defaults for
450
574
  * public GitLab if not specified.
451
575
  *
452
- * @param configs All of the integration config objects
576
+ * @param configs - All of the integration config objects
577
+ * @public
453
578
  */
454
579
  declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrationConfig[];
455
580
 
@@ -457,6 +582,8 @@ declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrat
457
582
  * Given a URL pointing to a file on a provider, returns a URL that is suitable
458
583
  * for fetching the contents of the data.
459
584
  *
585
+ * @remarks
586
+ *
460
587
  * Converts
461
588
  * from: https://gitlab.example.com/a/b/blob/master/c.yaml
462
589
  * to: https://gitlab.example.com/a/b/raw/master/c.yaml
@@ -464,17 +591,26 @@ declare function readGitLabIntegrationConfigs(configs: Config[]): GitLabIntegrat
464
591
  * from: https://gitlab.com/groupA/teams/teamA/subgroupA/repoA/-/blob/branch/filepath
465
592
  * to: https://gitlab.com/api/v4/projects/projectId/repository/files/filepath?ref=branch
466
593
  *
467
- * @param url A URL pointing to a file
468
- * @param config The relevant provider config
594
+ * @param url - A URL pointing to a file
595
+ * @param config - The relevant provider config
596
+ * @public
469
597
  */
470
598
  declare function getGitLabFileFetchUrl(url: string, config: GitLabIntegrationConfig): Promise<string>;
471
599
  /**
472
600
  * Gets the request options necessary to make requests to a given provider.
473
601
  *
474
- * @param config The relevant provider config
602
+ * @param config - The relevant provider config
603
+ * @public
475
604
  */
476
- declare function getGitLabRequestOptions(config: GitLabIntegrationConfig): RequestInit;
605
+ declare function getGitLabRequestOptions(config: GitLabIntegrationConfig): {
606
+ headers: Record<string, string>;
607
+ };
477
608
 
609
+ /**
610
+ * A GitLab based integration.
611
+ *
612
+ * @public
613
+ */
478
614
  declare class GitLabIntegration implements ScmIntegration {
479
615
  private readonly integrationConfig;
480
616
  static factory: ScmIntegrationsFactory<GitLabIntegration>;
@@ -492,6 +628,8 @@ declare class GitLabIntegration implements ScmIntegration {
492
628
 
493
629
  /**
494
630
  * The configuration parameters for a single Google Cloud Storage provider.
631
+ *
632
+ * @public
495
633
  */
496
634
  declare type GoogleGcsIntegrationConfig = {
497
635
  /**
@@ -506,41 +644,69 @@ declare type GoogleGcsIntegrationConfig = {
506
644
  /**
507
645
  * Reads a single Google GCS integration config.
508
646
  *
509
- * @param config The config object of a single integration
647
+ * @param config - The config object of a single integration
648
+ * @public
510
649
  */
511
650
  declare function readGoogleGcsIntegrationConfig(config: Config): GoogleGcsIntegrationConfig;
512
651
 
513
652
  /**
514
653
  * The configuration parameters for a single AWS S3 provider.
654
+ *
655
+ * @public
515
656
  */
516
657
  declare type AwsS3IntegrationConfig = {
517
658
  /**
518
- * The host of the target that this matches on, e.g. "amazonaws.com"
519
- *
520
- * Currently only "amazonaws.com" is supported.
659
+ * Host, derived from endpoint, and defaults to amazonaws.com
521
660
  */
522
661
  host: string;
523
662
  /**
524
- * accessKeyId
663
+ * (Optional) AWS Endpoint.
664
+ * The endpoint URI to send requests to. The default endpoint is built from the configured region.
665
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#constructor-property
666
+ *
667
+ * Supports non-AWS providers, e.g. for LocalStack, endpoint may look like http://localhost:4566
668
+ */
669
+ endpoint?: string;
670
+ /**
671
+ * (Optional) Whether to use path style URLs when communicating with S3.
672
+ * Defaults to false.
673
+ * This allows providers like LocalStack, Minio and Wasabi (and possibly others) to be used.
674
+ */
675
+ s3ForcePathStyle?: boolean;
676
+ /**
677
+ * (Optional) User access key id
525
678
  */
526
679
  accessKeyId?: string;
527
680
  /**
528
- * secretAccessKey
681
+ * (Optional) User secret access key
529
682
  */
530
683
  secretAccessKey?: string;
531
684
  /**
532
- * roleArn
685
+ * (Optional) ARN of role to be assumed
533
686
  */
534
687
  roleArn?: string;
535
688
  };
536
689
  /**
537
690
  * Reads a single Aws S3 integration config.
538
691
  *
539
- * @param config The config object of a single integration
692
+ * @param config - The config object of a single integration
693
+ * @public
540
694
  */
541
695
  declare function readAwsS3IntegrationConfig(config: Config): AwsS3IntegrationConfig;
696
+ /**
697
+ * Reads a set of AWS S3 integration configs, and inserts some defaults for
698
+ * public Amazon AWS if not specified.
699
+ *
700
+ * @param configs - The config objects of the integrations
701
+ * @public
702
+ */
542
703
  declare function readAwsS3IntegrationConfigs(configs: Config[]): AwsS3IntegrationConfig[];
543
704
 
705
+ /**
706
+ * Integrates with AWS S3 or compatible solutions.
707
+ *
708
+ * @public
709
+ */
544
710
  declare class AwsS3Integration implements ScmIntegration {
545
711
  private readonly integrationConfig;
546
712
  static factory: ScmIntegrationsFactory<AwsS3Integration>;
@@ -557,8 +723,10 @@ declare class AwsS3Integration implements ScmIntegration {
557
723
  }
558
724
 
559
725
  /**
560
- * Default implementation of ScmIntegration.resolveUrl, that only works with
561
- * URL pathname based providers.
726
+ * Default implementation of {@link ScmIntegration} `resolveUrl`, that only
727
+ * works with URL pathname based providers.
728
+ *
729
+ * @public
562
730
  */
563
731
  declare function defaultScmResolveUrl(options: {
564
732
  url: string;
@@ -568,6 +736,8 @@ declare function defaultScmResolveUrl(options: {
568
736
 
569
737
  /**
570
738
  * Holds all registered SCM integrations, of all types.
739
+ *
740
+ * @public
571
741
  */
572
742
  interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
573
743
  awsS3: ScmIntegrationsGroup<AwsS3Integration>;
@@ -586,14 +756,19 @@ interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
586
756
  * within the file tree of a certain repo, an absolute path of `/b.yaml` does
587
757
  * not resolve to `https://hostname/b.yaml` but rather to
588
758
  * `<repo root url>/b.yaml` inside the file tree of that same repo.
589
- *
590
- * @param options.url The (absolute or relative) URL or path to resolve
591
- * @param options.base The base URL onto which this resolution happens
592
- * @param options.lineNumber The line number in the target file to link to, starting with 1. Only applicable when linking to files.
593
759
  */
594
760
  resolveUrl(options: {
761
+ /**
762
+ * The (absolute or relative) URL or path to resolve.
763
+ */
595
764
  url: string;
765
+ /**
766
+ * The base URL onto which this resolution happens
767
+ */
596
768
  base: string;
769
+ /**
770
+ * The line number in the target file to link to, starting with 1. Only applicable when linking to files.
771
+ */
597
772
  lineNumber?: number;
598
773
  }): string;
599
774
  /**
@@ -605,18 +780,28 @@ interface ScmIntegrationRegistry extends ScmIntegrationsGroup<ScmIntegration> {
605
780
  * If this is not possible, the integration can fall back to a URL to view
606
781
  * the file in the web interface.
607
782
  *
608
- * @param url The absolute URL to the file that should be edited.
783
+ * @param url - The absolute URL to the file that should be edited.
609
784
  */
610
785
  resolveEditUrl(url: string): string;
611
786
  }
612
787
 
613
- declare type IntegrationsByType = {
788
+ /**
789
+ * The set of supported integrations.
790
+ *
791
+ * @public
792
+ */
793
+ interface IntegrationsByType {
614
794
  awsS3: ScmIntegrationsGroup<AwsS3Integration>;
615
795
  azure: ScmIntegrationsGroup<AzureIntegration>;
616
796
  bitbucket: ScmIntegrationsGroup<BitbucketIntegration>;
617
797
  github: ScmIntegrationsGroup<GitHubIntegration>;
618
798
  gitlab: ScmIntegrationsGroup<GitLabIntegration>;
619
- };
799
+ }
800
+ /**
801
+ * Exposes the set of supported integrations.
802
+ *
803
+ * @public
804
+ */
620
805
  declare class ScmIntegrations implements ScmIntegrationRegistry {
621
806
  private readonly byType;
622
807
  static fromConfig(config: Config): ScmIntegrations;
@@ -637,4 +822,4 @@ declare class ScmIntegrations implements ScmIntegrationRegistry {
637
822
  resolveEditUrl(url: string): string;
638
823
  }
639
824
 
640
- 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 };
825
+ export { AwsS3Integration, AwsS3IntegrationConfig, AzureIntegration, AzureIntegrationConfig, BitbucketIntegration, BitbucketIntegrationConfig, 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 };