@backstage/core-app-api 0.1.15 → 0.1.19

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/CHANGELOG.md CHANGED
@@ -1,5 +1,80 @@
1
1
  # @backstage/core-app-api
2
2
 
3
+ ## 0.1.19
4
+
5
+ ### Patch Changes
6
+
7
+ - 10615525f3: Switch to use the json and observable types from `@backstage/types`
8
+ - 41c49884d2: Start using the new `@backstage/types` package. Initially, this means using the `Observable` and `Json*` types from there. The types also remain in their old places but deprecated, and will be removed in a future release.
9
+ - 925a967f36: Replace usage of test-utils-core with test-utils
10
+ - 6b615e92c8: Api cleanup, adding `@public` where necessary and tweaking some comments
11
+ - Updated dependencies
12
+ - @backstage/config@0.1.11
13
+ - @backstage/theme@0.2.12
14
+ - @backstage/core-components@0.7.2
15
+ - @backstage/core-plugin-api@0.1.12
16
+
17
+ ## 0.1.18
18
+
19
+ ### Patch Changes
20
+
21
+ - 202f322927: Atlassian auth provider
22
+
23
+ - AtlassianAuth added to core-app-api
24
+ - Atlassian provider added to plugin-auth-backend
25
+ - Updated user-settings with Atlassian connection
26
+
27
+ - 36e67d2f24: Internal updates to apply more strict checks to throw errors.
28
+ - Updated dependencies
29
+ - @backstage/core-components@0.7.1
30
+ - @backstage/core-plugin-api@0.1.11
31
+
32
+ ## 0.1.17
33
+
34
+ ### Patch Changes
35
+
36
+ - 75bc878221: Internal refactor to avoid importing all of `@material-ui/core`.
37
+ - Updated dependencies
38
+ - @backstage/core-components@0.7.0
39
+ - @backstage/theme@0.2.11
40
+
41
+ ## 0.1.16
42
+
43
+ ### Patch Changes
44
+
45
+ - d9fd798cc8: The Core App API now automatically instruments all route location changes using
46
+ the new Analytics API. Each location change triggers a `navigate` event, which
47
+ is an analogue of a "pageview" event in traditional web analytics systems. In
48
+ addition to the path, these events provide plugin-level metadata via the
49
+ analytics context, which can be useful for analyzing plugin usage:
50
+
51
+ ```json
52
+ {
53
+ "action": "navigate",
54
+ "subject": "/the-path/navigated/to?with=params#and-hashes",
55
+ "context": {
56
+ "extension": "App",
57
+ "pluginId": "id-of-plugin-that-exported-the-route",
58
+ "routeRef": "associated-route-ref-id"
59
+ }
60
+ }
61
+ ```
62
+
63
+ These events can be identified and handled by checking for the action
64
+ `navigate` and the extension `App`.
65
+
66
+ - 4c3eea7788: Bitbucket Cloud authentication - based on the existing GitHub authentication + changes around BB apis and updated scope.
67
+
68
+ - BitbucketAuth added to core-app-api.
69
+ - Bitbucket provider added to plugin-auth-backend.
70
+ - Cosmetic entry for Bitbucket connection in user-settings Authentication Providers tab.
71
+
72
+ - d6ad46eb22: Stop calling connector.removeSession in StaticAuthSessionManager, instead just discarding the
73
+ session locally.
74
+ - Updated dependencies
75
+ - @backstage/core-components@0.6.1
76
+ - @backstage/core-plugin-api@0.1.10
77
+
3
78
  ## 0.1.15
4
79
 
5
80
  ### Patch Changes
package/dist/index.d.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  import { PropsWithChildren, ReactNode, ComponentType } from 'react';
2
2
  import PropTypes from 'prop-types';
3
- import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
4
- import { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentity, Observable, SessionState, OAuthRequestApi, DiscoveryApi, AuthProvider, OAuthApi, SessionApi, AuthRequestOptions, gitlabAuthApiRef, googleAuthApiRef, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, oktaAuthApiRef, auth0AuthApiRef, microsoftAuthApiRef, oneloginAuthApiRef, AlertApi, AlertMessage, AppThemeApi, AppTheme, ErrorApi, ErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, AuthRequesterOptions, AuthRequester, PendingAuthRequest, StorageApi, StorageValueChange, IconComponent, BackstagePlugin, ExternalRouteRef, PluginOutput, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
3
+ import { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentity, SessionState, OAuthRequestApi, DiscoveryApi, AuthProvider, OAuthApi, SessionApi, AuthRequestOptions, gitlabAuthApiRef, googleAuthApiRef, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, oktaAuthApiRef, auth0AuthApiRef, microsoftAuthApiRef, oneloginAuthApiRef, bitbucketAuthApiRef, atlassianAuthApiRef, AlertApi, AlertMessage, AnalyticsApi, AnalyticsEvent, AppThemeApi, AppTheme, ErrorApi, ErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, AuthRequesterOptions, AuthRequester, PendingAuthRequest, StorageApi, StorageValueChange, IconComponent, BackstagePlugin, ExternalRouteRef, PluginOutput, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
4
+ import * as _backstage_types from '@backstage/types';
5
+ import { Observable } from '@backstage/types';
5
6
  import { AppConfig } from '@backstage/config';
6
7
  export { ConfigReader } from '@backstage/config';
7
8
 
@@ -9,8 +10,14 @@ declare type ApiProviderProps = {
9
10
  apis: ApiHolder;
10
11
  children: ReactNode;
11
12
  };
13
+ /**
14
+ * Provides an {@link @backstage/core-plugin-api#ApiHolder} for consumption in
15
+ * the React tree.
16
+ *
17
+ * @public
18
+ */
12
19
  declare const ApiProvider: {
13
- ({ apis, children, }: PropsWithChildren<ApiProviderProps>): JSX.Element;
20
+ (props: PropsWithChildren<ApiProviderProps>): JSX.Element;
14
21
  propTypes: {
15
22
  apis: PropTypes.Validator<PropTypes.InferProps<{
16
23
  get: PropTypes.Validator<(...args: any[]) => any>;
@@ -25,34 +32,53 @@ declare class ApiRegistryBuilder {
25
32
  add<T, I extends T>(api: ApiRef<T>, impl: I): I;
26
33
  build(): ApiRegistry;
27
34
  }
35
+ /**
36
+ * A registry for utility APIs.
37
+ *
38
+ * @public
39
+ */
28
40
  declare class ApiRegistry implements ApiHolder {
29
41
  private readonly apis;
30
42
  static builder(): ApiRegistryBuilder;
43
+ /**
44
+ * Creates a new ApiRegistry with a list of API implementations.
45
+ *
46
+ * @param apis - A list of pairs mapping an ApiRef to its respective implementation
47
+ */
31
48
  static from(apis: ApiImpl[]): ApiRegistry;
32
49
  /**
33
50
  * Creates a new ApiRegistry with a single API implementation.
34
51
  *
35
- * @param api ApiRef for the API to add
36
- * @param impl Implementation of the API to add
52
+ * @param api - ApiRef for the API to add
53
+ * @param impl - Implementation of the API to add
37
54
  */
38
55
  static with<T>(api: ApiRef<T>, impl: T): ApiRegistry;
39
56
  constructor(apis: Map<string, unknown>);
40
57
  /**
41
58
  * Returns a new ApiRegistry with the provided API added to the existing ones.
42
59
  *
43
- * @param api ApiRef for the API to add
44
- * @param impl Implementation of the API to add
60
+ * @param api - ApiRef for the API to add
61
+ * @param impl - Implementation of the API to add
45
62
  */
46
63
  with<T>(api: ApiRef<T>, impl: T): ApiRegistry;
47
64
  get<T>(api: ApiRef<T>): T | undefined;
48
65
  }
49
66
 
67
+ /**
68
+ * @public
69
+ */
50
70
  declare type ApiFactoryHolder = {
51
71
  get<T>(api: ApiRef<T>): ApiFactory<T, T, {
52
72
  [key in string]: unknown;
53
73
  }> | undefined;
54
74
  };
55
75
 
76
+ /**
77
+ * Handles the actual on-demand instantiation and memoization of APIs out of
78
+ * an {@link ApiFactoryHolder}.
79
+ *
80
+ * @public
81
+ */
56
82
  declare class ApiResolver implements ApiHolder {
57
83
  private readonly factories;
58
84
  /**
@@ -74,6 +100,8 @@ declare type ApiFactoryScope = 'default' | 'app' | 'static';
74
100
  *
75
101
  * Each scope has an assigned priority, where factories registered with
76
102
  * higher priority scopes override ones with lower priority.
103
+ *
104
+ * @public
77
105
  */
78
106
  declare class ApiFactoryRegistry implements ApiFactoryHolder {
79
107
  private readonly factories;
@@ -93,6 +121,11 @@ declare class ApiFactoryRegistry implements ApiFactoryHolder {
93
121
  getAllApis(): Set<AnyApiRef>;
94
122
  }
95
123
 
124
+ /**
125
+ * Session information for GitHub auth.
126
+ *
127
+ * @public
128
+ */
96
129
  declare type GithubSession = {
97
130
  providerInfo: {
98
131
  accessToken: string;
@@ -131,6 +164,11 @@ declare type AuthApiCreateOptions = {
131
164
  };
132
165
  };
133
166
 
167
+ /**
168
+ * Implements the OAuth flow to GitHub products.
169
+ *
170
+ * @public
171
+ */
134
172
  declare class GithubAuth implements OAuthApi, SessionApi {
135
173
  private readonly sessionManager;
136
174
  static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): GithubAuth;
@@ -144,14 +182,29 @@ declare class GithubAuth implements OAuthApi, SessionApi {
144
182
  static normalizeScope(scope?: string): Set<string>;
145
183
  }
146
184
 
185
+ /**
186
+ * Implements the OAuth flow to GitLab products.
187
+ *
188
+ * @public
189
+ */
147
190
  declare class GitlabAuth {
148
191
  static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof gitlabAuthApiRef.T;
149
192
  }
150
193
 
194
+ /**
195
+ * Implements the OAuth flow to Google products.
196
+ *
197
+ * @public
198
+ */
151
199
  declare class GoogleAuth {
152
200
  static create({ discoveryApi, oauthRequestApi, environment, provider, defaultScopes, }: OAuthApiCreateOptions): typeof googleAuthApiRef.T;
153
201
  }
154
202
 
203
+ /**
204
+ * Session information for generic OAuth2 auth.
205
+ *
206
+ * @public
207
+ */
155
208
  declare type OAuth2Session = {
156
209
  providerInfo: {
157
210
  idToken: string;
@@ -163,18 +216,22 @@ declare type OAuth2Session = {
163
216
  backstageIdentity: BackstageIdentity;
164
217
  };
165
218
 
166
- declare type Options = {
167
- sessionManager: SessionManager<OAuth2Session>;
168
- scopeTransform: (scopes: string[]) => string[];
169
- };
170
219
  declare type CreateOptions$1 = OAuthApiCreateOptions & {
171
220
  scopeTransform?: (scopes: string[]) => string[];
172
221
  };
222
+ /**
223
+ * Implements a generic OAuth2 flow for auth.
224
+ *
225
+ * @public
226
+ */
173
227
  declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, SessionApi {
174
228
  static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, scopeTransform, }: CreateOptions$1): OAuth2;
175
229
  private readonly sessionManager;
176
230
  private readonly scopeTransform;
177
- constructor(options: Options);
231
+ constructor(options: {
232
+ sessionManager: SessionManager<OAuth2Session>;
233
+ scopeTransform: (scopes: string[]) => string[];
234
+ });
178
235
  signIn(): Promise<void>;
179
236
  signOut(): Promise<void>;
180
237
  sessionState$(): Observable<SessionState>;
@@ -185,16 +242,31 @@ declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, Back
185
242
  private static normalizeScopes;
186
243
  }
187
244
 
245
+ /**
246
+ * Implements the OAuth flow to Okta products.
247
+ *
248
+ * @public
249
+ */
188
250
  declare class OktaAuth {
189
251
  static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
190
252
  }
191
253
 
254
+ /**
255
+ * Session information for SAML auth.
256
+ *
257
+ * @public
258
+ */
192
259
  declare type SamlSession = {
193
260
  userId: string;
194
261
  profile: ProfileInfo;
195
262
  backstageIdentity: BackstageIdentity;
196
263
  };
197
264
 
265
+ /**
266
+ * Implements a general SAML based auth flow.
267
+ *
268
+ * @public
269
+ */
198
270
  declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionApi {
199
271
  private readonly sessionManager;
200
272
  static create({ discoveryApi, environment, provider, }: AuthApiCreateOptions): SamlAuth;
@@ -206,10 +278,20 @@ declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionA
206
278
  getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
207
279
  }
208
280
 
281
+ /**
282
+ * Implements the OAuth flow to Auth0 products.
283
+ *
284
+ * @public
285
+ */
209
286
  declare class Auth0Auth {
210
287
  static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof auth0AuthApiRef.T;
211
288
  }
212
289
 
290
+ /**
291
+ * Implements the OAuth flow to Microsoft products.
292
+ *
293
+ * @public
294
+ */
213
295
  declare class MicrosoftAuth {
214
296
  static create({ environment, provider, oauthRequestApi, discoveryApi, defaultScopes, }: OAuthApiCreateOptions): typeof microsoftAuthApiRef.T;
215
297
  }
@@ -222,12 +304,52 @@ declare type CreateOptions = {
222
304
  id: string;
223
305
  };
224
306
  };
307
+ /**
308
+ * Implements a OneLogin OAuth flow.
309
+ *
310
+ * @public
311
+ */
225
312
  declare class OneLoginAuth {
226
313
  static create({ discoveryApi, environment, provider, oauthRequestApi, }: CreateOptions): typeof oneloginAuthApiRef.T;
227
314
  }
228
315
 
316
+ /**
317
+ * Session information for Bitbucket auth.
318
+ *
319
+ * @public
320
+ */
321
+ declare type BitbucketSession = {
322
+ providerInfo: {
323
+ accessToken: string;
324
+ scopes: Set<string>;
325
+ expiresAt?: Date;
326
+ };
327
+ profile: ProfileInfo;
328
+ backstageIdentity: BackstageIdentity;
329
+ };
330
+
331
+ /**
332
+ * Implements the OAuth flow to Bitbucket products.
333
+ *
334
+ * @public
335
+ */
336
+ declare class BitbucketAuth {
337
+ static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof bitbucketAuthApiRef.T;
338
+ }
339
+
340
+ /**
341
+ * Implements the OAuth flow to Atlassian products.
342
+ *
343
+ * @public
344
+ */
345
+ declare class AtlassianAuth {
346
+ static create({ discoveryApi, environment, provider, oauthRequestApi, }: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T;
347
+ }
348
+
229
349
  /**
230
350
  * Base implementation for the AlertApi that simply forwards alerts to consumers.
351
+ *
352
+ * @public
231
353
  */
232
354
  declare class AlertApiForwarder implements AlertApi {
233
355
  private readonly subject;
@@ -235,6 +357,21 @@ declare class AlertApiForwarder implements AlertApi {
235
357
  alert$(): Observable<AlertMessage>;
236
358
  }
237
359
 
360
+ /**
361
+ * Base implementation for the AnalyticsApi that does nothing.
362
+ *
363
+ * @public
364
+ */
365
+ declare class NoOpAnalyticsApi implements AnalyticsApi {
366
+ captureEvent(_event: AnalyticsEvent): void;
367
+ }
368
+
369
+ /**
370
+ * Exposes the themes installed in the app, and permits switching the currently
371
+ * active theme.
372
+ *
373
+ * @public
374
+ */
238
375
  declare class AppThemeSelector implements AppThemeApi {
239
376
  private readonly themes;
240
377
  static createWithStorage(themes: AppTheme[]): AppThemeSelector;
@@ -250,6 +387,8 @@ declare class AppThemeSelector implements AppThemeApi {
250
387
  /**
251
388
  * UrlPatternDiscovery is a lightweight DiscoveryApi implementation.
252
389
  * It uses a single template string to construct URLs for each plugin.
390
+ *
391
+ * @public
253
392
  */
254
393
  declare class UrlPatternDiscovery implements DiscoveryApi {
255
394
  private readonly parts;
@@ -268,13 +407,15 @@ declare class UrlPatternDiscovery implements DiscoveryApi {
268
407
  /**
269
408
  * Decorates an ErrorApi by also forwarding error messages
270
409
  * to the alertApi with an 'error' severity.
410
+ *
411
+ * @public
271
412
  */
272
413
  declare class ErrorAlerter implements ErrorApi {
273
414
  private readonly alertApi;
274
415
  private readonly errorApi;
275
416
  constructor(alertApi: AlertApi, errorApi: ErrorApi);
276
417
  post(error: Error, context?: ErrorContext): void;
277
- error$(): _backstage_core_plugin_api.Observable<{
418
+ error$(): _backstage_types.Observable<{
278
419
  error: {
279
420
  name: string;
280
421
  message: string;
@@ -286,6 +427,8 @@ declare class ErrorAlerter implements ErrorApi {
286
427
 
287
428
  /**
288
429
  * Base implementation for the ErrorApi that simply forwards errors to consumers.
430
+ *
431
+ * @public
289
432
  */
290
433
  declare class ErrorApiForwarder implements ErrorApi {
291
434
  private readonly subject;
@@ -296,6 +439,11 @@ declare class ErrorApiForwarder implements ErrorApi {
296
439
  }>;
297
440
  }
298
441
 
442
+ /**
443
+ * Utility class that helps with error forwarding.
444
+ *
445
+ * @public
446
+ */
299
447
  declare class UnhandledErrorForwarder {
300
448
  /**
301
449
  * Add event listener, such that unhandled errors can be forwarded using an given `ErrorApi` instance
@@ -304,7 +452,10 @@ declare class UnhandledErrorForwarder {
304
452
  }
305
453
 
306
454
  /**
307
- * Create the FeatureFlags implementation based on the API.
455
+ * A feature flags implementation that stores the flags in the browser's local
456
+ * storage.
457
+ *
458
+ * @public
308
459
  */
309
460
  declare class LocalStorageFeatureFlags implements FeatureFlagsApi {
310
461
  private registeredFeatureFlags;
@@ -322,6 +473,8 @@ declare class LocalStorageFeatureFlags implements FeatureFlagsApi {
322
473
  * The purpose of this class and the API is to read a stream of incoming requests
323
474
  * of OAuth access tokens from different providers with varying scope, and funnel
324
475
  * them all together into a single request for each OAuth provider.
476
+ *
477
+ * @public
325
478
  */
326
479
  declare class OAuthRequestManager implements OAuthRequestApi {
327
480
  private readonly subject;
@@ -332,15 +485,19 @@ declare class OAuthRequestManager implements OAuthRequestApi {
332
485
  authRequest$(): Observable<PendingAuthRequest[]>;
333
486
  }
334
487
 
335
- declare type CreateStorageApiOptions = {
336
- errorApi: ErrorApi;
337
- namespace?: string;
338
- };
488
+ /**
489
+ * An implementation of the storage API, that uses the browser's local storage.
490
+ *
491
+ * @public
492
+ */
339
493
  declare class WebStorage implements StorageApi {
340
494
  private readonly namespace;
341
495
  private readonly errorApi;
342
496
  constructor(namespace: string, errorApi: ErrorApi);
343
- static create(options: CreateStorageApiOptions): WebStorage;
497
+ static create(options: {
498
+ errorApi: ErrorApi;
499
+ namespace?: string;
500
+ }): WebStorage;
344
501
  get<T>(key: string): T | undefined;
345
502
  forBucket(name: string): WebStorage;
346
503
  set<T>(key: string, data: T): Promise<void>;
@@ -357,10 +514,20 @@ declare type AppIcons = {
357
514
  [key in AppIconsKey]: IconComponent;
358
515
  };
359
516
 
517
+ /**
518
+ * Props for the `BootErrorPage` component of {@link AppComponents}.
519
+ *
520
+ * @public
521
+ */
360
522
  declare type BootErrorPageProps = {
361
523
  step: 'load-config' | 'load-chunk';
362
524
  error: Error;
363
525
  };
526
+ /**
527
+ * The outcome of signing in on the sign-in page.
528
+ *
529
+ * @public
530
+ */
364
531
  declare type SignInResult = {
365
532
  /**
366
533
  * User ID that will be returned by the IdentityApi
@@ -376,17 +543,32 @@ declare type SignInResult = {
376
543
  */
377
544
  signOut?: () => Promise<void>;
378
545
  };
546
+ /**
547
+ * Props for the `SignInPage` component of {@link AppComponents}.
548
+ *
549
+ * @public
550
+ */
379
551
  declare type SignInPageProps = {
380
552
  /**
381
553
  * Set the sign-in result for the app. This should only be called once.
382
554
  */
383
555
  onResult(result: SignInResult): void;
384
556
  };
557
+ /**
558
+ * Props for the fallback error boundary.
559
+ *
560
+ * @public
561
+ */
385
562
  declare type ErrorBoundaryFallbackProps = {
386
563
  plugin?: BackstagePlugin;
387
564
  error: Error;
388
565
  resetError: () => void;
389
566
  };
567
+ /**
568
+ * A set of replaceable core components that are part of every Backstage app.
569
+ *
570
+ * @public
571
+ */
390
572
  declare type AppComponents = {
391
573
  NotFoundErrorPage: ComponentType<{}>;
392
574
  BootErrorPage: ComponentType<BootErrorPageProps>;
@@ -410,6 +592,8 @@ declare type AppComponents = {
410
592
  *
411
593
  * If multiple config objects are returned in the array, values in the earlier configs
412
594
  * will override later ones.
595
+ *
596
+ * @public
413
597
  */
414
598
  declare type AppConfigLoader = () => Promise<AppConfig[]>;
415
599
  /**
@@ -434,15 +618,40 @@ declare type TargetRouteMap<ExternalRoutes extends {
434
618
  }> = {
435
619
  [name in keyof ExternalRoutes]: ExternalRoutes[name] extends ExternalRouteRef<infer Params, any> ? RouteRef<Params> | SubRouteRef<Params> : never;
436
620
  };
621
+ /**
622
+ * A function that can bind from external routes of a given plugin, to concrete
623
+ * routes of other plugins. See {@link createApp}.
624
+ *
625
+ * @public
626
+ */
437
627
  declare type AppRouteBinder = <ExternalRoutes extends {
438
628
  [name: string]: ExternalRouteRef;
439
629
  }>(externalRoutes: ExternalRoutes, targetRoutes: PartialKeys<TargetRouteMap<ExternalRoutes>, KeysWithType<ExternalRoutes, ExternalRouteRef<any, true>>>) => void;
440
- declare type UnknownPluginOutput = {
441
- type: string;
442
- };
630
+ /**
631
+ * Internal helper type that represents a plugin with any type of output.
632
+ *
633
+ * @public
634
+ * @remarks
635
+ *
636
+ * The `type: string` type is there to handle output from newer or older plugin
637
+ * API versions that might not be supported by this version of the app API, but
638
+ * we don't want to break at the type checking level. We only use this more
639
+ * permissive type for the `createApp` options, as we otherwise want to stick
640
+ * to using the type for the outputs that we know about in this version of the
641
+ * app api.
642
+ *
643
+ * TODO(freben): This should be marked internal but that's not supported by the api report generation tools yet
644
+ */
443
645
  declare type BackstagePluginWithAnyOutput = Omit<BackstagePlugin<any, any>, 'output'> & {
444
- output(): (PluginOutput | UnknownPluginOutput)[];
646
+ output(): (PluginOutput | {
647
+ type: string;
648
+ })[];
445
649
  };
650
+ /**
651
+ * The options accepted by {@link createApp}.
652
+ *
653
+ * @public
654
+ */
446
655
  declare type AppOptions = {
447
656
  /**
448
657
  * A collection of ApiFactories to register in the application to either
@@ -518,6 +727,11 @@ declare type AppOptions = {
518
727
  bind: AppRouteBinder;
519
728
  }): void;
520
729
  };
730
+ /**
731
+ * The public API of the output of {@link createApp}.
732
+ *
733
+ * @public
734
+ */
521
735
  declare type BackstageApp = {
522
736
  /**
523
737
  * Returns all plugins registered for the app.
@@ -538,6 +752,12 @@ declare type BackstageApp = {
538
752
  */
539
753
  getRouter(): ComponentType<{}>;
540
754
  };
755
+ /**
756
+ * The central context providing runtime app specific state that plugin views
757
+ * want to consume.
758
+ *
759
+ * @public
760
+ */
541
761
  declare type AppContext = {
542
762
  /**
543
763
  * Get a list of all plugins that are installed in the app.
@@ -595,18 +815,43 @@ declare class PrivateAppImpl implements BackstageApp {
595
815
  * which can be rewritten at runtime to contain an additional JSON config object.
596
816
  * If runtime config is present, it will be placed first in the config array, overriding
597
817
  * other config values.
818
+ *
819
+ * @public
598
820
  */
599
821
  declare const defaultConfigLoader: AppConfigLoader;
600
822
  /**
601
823
  * Creates a new Backstage App.
824
+ *
825
+ * @public
602
826
  */
603
827
  declare function createApp(options?: AppOptions): PrivateAppImpl;
604
828
 
829
+ /**
830
+ * Props for the {@link FlatRoutes} component.
831
+ *
832
+ * @public
833
+ */
605
834
  declare type FlatRoutesProps = {
606
835
  children: ReactNode;
607
836
  };
837
+ /**
838
+ * A wrapper around a set of routes.
839
+ *
840
+ * @remarks
841
+ *
842
+ * The root of the routing hierarchy in your app should use this component,
843
+ * instead of the one from `react-router-dom`. This ensures that all of the
844
+ * plugin route and utility API wiring happens under the hood.
845
+ *
846
+ * @public
847
+ */
608
848
  declare const FlatRoutes: (props: FlatRoutesProps) => JSX.Element | null;
609
849
 
850
+ /**
851
+ * Props for the {@link FeatureFlagged} component.
852
+ *
853
+ * @public
854
+ */
610
855
  declare type FeatureFlaggedProps = {
611
856
  children: ReactNode;
612
857
  } & ({
@@ -614,6 +859,12 @@ declare type FeatureFlaggedProps = {
614
859
  } | {
615
860
  without: string;
616
861
  });
862
+ /**
863
+ * Enables or disables rendering of its children based on the state of a given
864
+ * feature flag.
865
+ *
866
+ * @public
867
+ */
617
868
  declare const FeatureFlagged: (props: FeatureFlaggedProps) => JSX.Element;
618
869
 
619
- export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiProvider, ApiRegistry, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppOptions, AppRouteBinder, AppThemeSelector, Auth0Auth, BackstageApp, BackstagePluginWithAnyOutput, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FlatRoutes, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, OAuth2, OAuth2Session, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createApp, defaultConfigLoader };
870
+ export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiProvider, ApiRegistry, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, Auth0Auth, BackstageApp, BackstagePluginWithAnyOutput, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FlatRoutes, FlatRoutesProps, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2Session, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createApp, defaultConfigLoader };