@backstage/frontend-plugin-api 0.13.0 → 0.13.2-next.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.
Files changed (74) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/dist/analytics/useAnalytics.esm.js +14 -1
  3. package/dist/analytics/useAnalytics.esm.js.map +1 -1
  4. package/dist/apis/definitions/AlertApi.esm.js +11 -0
  5. package/dist/apis/definitions/AlertApi.esm.js.map +1 -0
  6. package/dist/apis/definitions/AnalyticsApi.esm.js +4 -1
  7. package/dist/apis/definitions/AnalyticsApi.esm.js.map +1 -1
  8. package/dist/apis/definitions/AppLanguageApi.esm.js +11 -0
  9. package/dist/apis/definitions/AppLanguageApi.esm.js.map +1 -0
  10. package/dist/apis/definitions/AppThemeApi.esm.js +11 -0
  11. package/dist/apis/definitions/AppThemeApi.esm.js.map +1 -0
  12. package/dist/apis/definitions/AppTreeApi.esm.js +4 -1
  13. package/dist/apis/definitions/AppTreeApi.esm.js.map +1 -1
  14. package/dist/apis/definitions/ConfigApi.esm.js +11 -0
  15. package/dist/apis/definitions/ConfigApi.esm.js.map +1 -0
  16. package/dist/apis/definitions/DialogApi.esm.js +4 -1
  17. package/dist/apis/definitions/DialogApi.esm.js.map +1 -1
  18. package/dist/apis/definitions/DiscoveryApi.esm.js +11 -0
  19. package/dist/apis/definitions/DiscoveryApi.esm.js.map +1 -0
  20. package/dist/apis/definitions/ErrorApi.esm.js +11 -0
  21. package/dist/apis/definitions/ErrorApi.esm.js.map +1 -0
  22. package/dist/apis/definitions/FeatureFlagsApi.esm.js +21 -0
  23. package/dist/apis/definitions/FeatureFlagsApi.esm.js.map +1 -0
  24. package/dist/apis/definitions/FetchApi.esm.js +11 -0
  25. package/dist/apis/definitions/FetchApi.esm.js.map +1 -0
  26. package/dist/apis/definitions/IconsApi.esm.js +4 -1
  27. package/dist/apis/definitions/IconsApi.esm.js.map +1 -1
  28. package/dist/apis/definitions/IdentityApi.esm.js +11 -0
  29. package/dist/apis/definitions/IdentityApi.esm.js.map +1 -0
  30. package/dist/apis/definitions/OAuthRequestApi.esm.js +11 -0
  31. package/dist/apis/definitions/OAuthRequestApi.esm.js.map +1 -0
  32. package/dist/apis/definitions/RouteResolutionApi.esm.js +4 -1
  33. package/dist/apis/definitions/RouteResolutionApi.esm.js.map +1 -1
  34. package/dist/apis/definitions/StorageApi.esm.js +11 -0
  35. package/dist/apis/definitions/StorageApi.esm.js.map +1 -0
  36. package/dist/apis/definitions/SwappableComponentsApi.esm.js +4 -1
  37. package/dist/apis/definitions/SwappableComponentsApi.esm.js.map +1 -1
  38. package/dist/apis/definitions/TranslationApi.esm.js +11 -0
  39. package/dist/apis/definitions/TranslationApi.esm.js.map +1 -0
  40. package/dist/apis/definitions/auth.esm.js +51 -0
  41. package/dist/apis/definitions/auth.esm.js.map +1 -0
  42. package/dist/apis/system/ApiRef.esm.js +27 -0
  43. package/dist/apis/system/ApiRef.esm.js.map +1 -0
  44. package/dist/apis/system/helpers.esm.js +13 -0
  45. package/dist/apis/system/helpers.esm.js.map +1 -0
  46. package/dist/apis/system/useApi.esm.js +50 -0
  47. package/dist/apis/system/useApi.esm.js.map +1 -0
  48. package/dist/blueprints/NavItemBlueprint.esm.js.map +1 -1
  49. package/dist/blueprints/PageBlueprint.esm.js +15 -1
  50. package/dist/blueprints/PageBlueprint.esm.js.map +1 -1
  51. package/dist/blueprints/SignInPageBlueprint.esm.js +15 -1
  52. package/dist/blueprints/SignInPageBlueprint.esm.js.map +1 -1
  53. package/dist/blueprints/ThemeBlueprint.esm.js.map +1 -1
  54. package/dist/components/ExtensionBoundary.esm.js +2 -1
  55. package/dist/components/ExtensionBoundary.esm.js.map +1 -1
  56. package/dist/components/createSwappableComponent.esm.js +14 -1
  57. package/dist/components/createSwappableComponent.esm.js.map +1 -1
  58. package/dist/frontend-internal/src/wiring/InternalExtensionInput.esm.js.map +1 -1
  59. package/dist/index.d.ts +1595 -148
  60. package/dist/index.esm.js +20 -2
  61. package/dist/index.esm.js.map +1 -1
  62. package/dist/routing/useRouteRef.esm.js +14 -1
  63. package/dist/routing/useRouteRef.esm.js.map +1 -1
  64. package/dist/translation/TranslationMessages.esm.js +11 -0
  65. package/dist/translation/TranslationMessages.esm.js.map +1 -0
  66. package/dist/translation/TranslationRef.esm.js +62 -0
  67. package/dist/translation/TranslationRef.esm.js.map +1 -0
  68. package/dist/translation/TranslationResource.esm.js +21 -0
  69. package/dist/translation/TranslationResource.esm.js.map +1 -0
  70. package/dist/translation/useTranslationRef.esm.js +89 -0
  71. package/dist/translation/useTranslationRef.esm.js.map +1 -0
  72. package/dist/wiring/createExtension.esm.js +2 -2
  73. package/dist/wiring/createExtension.esm.js.map +1 -1
  74. package/package.json +28 -21
package/dist/index.d.ts CHANGED
@@ -1,15 +1,11 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import * as react from 'react';
3
- import { ReactNode, JSX as JSX$1, ComponentType } from 'react';
4
- import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
5
- import { ApiHolder, ConfigApi, ApiRef, TypesToApiRefs, ApiFactory, AnyApiFactory, IconComponent as IconComponent$2, SignInPageProps, AppTheme } from '@backstage/core-plugin-api';
6
- export { AlertApi, AlertMessage, AnyApiFactory, AnyApiRef, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, AppTheme, AppThemeApi, AuthProviderInfo, AuthRequestOptions, BackstageIdentityApi, BackstageIdentityResponse, BackstageUserIdentity, ConfigApi, DiscoveryApi, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlag, FeatureFlagState, FeatureFlagsApi, FeatureFlagsSaveOptions, FetchApi, IdentityApi, OAuthApi, OAuthRequestApi, OAuthRequester, OAuthRequesterOptions, OAuthScope, OpenIdConnectApi, PendingOAuthRequest, ProfileInfo, ProfileInfoApi, SessionApi, SessionState, StorageApi, StorageValueSnapshot, TypesToApiRefs, alertApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, createApiFactory, createApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, storageApiRef, useApi, useApiHolder, vmwareCloudAuthApiRef, withApis } from '@backstage/core-plugin-api';
7
- import { Expand, JsonObject } from '@backstage/types';
3
+ import { ReactNode, ComponentType, PropsWithChildren, JSX as JSX$1 } from 'react';
4
+ import { Expand, JsonObject, Observable, JsonValue, ExpandRecursive } from '@backstage/types';
8
5
  import { z } from 'zod';
6
+ import { Config } from '@backstage/config';
9
7
  import * as _backstage_frontend_plugin_api from '@backstage/frontend-plugin-api';
10
8
  import { IconComponent as IconComponent$1, RouteRef as RouteRef$1 } from '@backstage/frontend-plugin-api';
11
- import { TranslationResource, TranslationMessages } from '@backstage/core-plugin-api/alpha';
12
- export { TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, createTranslationMessages, createTranslationRef, createTranslationResource, useTranslationRef } from '@backstage/core-plugin-api/alpha';
13
9
 
14
10
  /**
15
11
  * Analytics context envelope.
@@ -44,6 +40,122 @@ declare const AnalyticsContext: (options: {
44
40
  children: ReactNode;
45
41
  }) => react_jsx_runtime.JSX.Element;
46
42
 
43
+ /**
44
+ * API reference.
45
+ *
46
+ * @public
47
+ */
48
+ type ApiRef<T> = {
49
+ id: string;
50
+ T: T;
51
+ };
52
+ /**
53
+ * Catch-all {@link ApiRef} type.
54
+ *
55
+ * @public
56
+ */
57
+ type AnyApiRef = ApiRef<unknown>;
58
+ /**
59
+ * Wraps a type with API properties into a type holding their respective {@link ApiRef}s.
60
+ *
61
+ * @public
62
+ */
63
+ type TypesToApiRefs<T> = {
64
+ [key in keyof T]: ApiRef<T[key]>;
65
+ };
66
+ /**
67
+ * Provides lookup of APIs through their {@link ApiRef}s.
68
+ *
69
+ * @public
70
+ */
71
+ type ApiHolder = {
72
+ get<T>(api: ApiRef<T>): T | undefined;
73
+ };
74
+ /**
75
+ * Describes type returning API implementations.
76
+ *
77
+ * @public
78
+ */
79
+ type ApiFactory<Api, Impl extends Api, Deps extends {
80
+ [name in string]: unknown;
81
+ }> = {
82
+ api: ApiRef<Api>;
83
+ deps: TypesToApiRefs<Deps>;
84
+ factory(deps: Deps): Impl;
85
+ };
86
+ /**
87
+ * Catch-all {@link ApiFactory} type.
88
+ *
89
+ * @public
90
+ */
91
+ type AnyApiFactory = ApiFactory<unknown, unknown, {
92
+ [key in string]: unknown;
93
+ }>;
94
+
95
+ /**
96
+ * React hook for retrieving {@link ApiHolder}, an API catalog.
97
+ *
98
+ * @public
99
+ */
100
+ declare function useApiHolder(): ApiHolder;
101
+ /**
102
+ * React hook for retrieving APIs.
103
+ *
104
+ * @param apiRef - Reference of the API to use.
105
+ * @public
106
+ */
107
+ declare function useApi<T>(apiRef: ApiRef<T>): T;
108
+ /**
109
+ * Wrapper for giving component an API context.
110
+ *
111
+ * @param apis - APIs for the context.
112
+ * @public
113
+ */
114
+ declare function withApis<T extends {}>(apis: TypesToApiRefs<T>): <TProps extends T>(WrappedComponent: ComponentType<TProps>) => {
115
+ (props: PropsWithChildren<Omit<TProps, keyof T>>): react_jsx_runtime.JSX.Element;
116
+ displayName: string;
117
+ };
118
+
119
+ /**
120
+ * API reference configuration - holds an ID of the referenced API.
121
+ *
122
+ * @public
123
+ */
124
+ type ApiRefConfig = {
125
+ id: string;
126
+ };
127
+ /**
128
+ * Creates a reference to an API.
129
+ *
130
+ * @param config - The descriptor of the API to reference.
131
+ * @returns An API reference.
132
+ * @public
133
+ */
134
+ declare function createApiRef<T>(config: ApiRefConfig): ApiRef<T>;
135
+
136
+ /**
137
+ * Used to infer types for a standalone {@link ApiFactory} that isn't immediately passed
138
+ * to another function.
139
+ *
140
+ * @remarks
141
+ *
142
+ * This function doesn't actually do anything, it's only used to infer types.
143
+ *
144
+ * @public
145
+ */
146
+ declare function createApiFactory<Api, Impl extends Api, Deps extends {
147
+ [name in string]: unknown;
148
+ }>(factory: ApiFactory<Api, Impl, Deps>): ApiFactory<Api, Impl, Deps>;
149
+ /**
150
+ * Used to infer types for a standalone {@link ApiFactory} that isn't immediately passed
151
+ * to another function.
152
+ *
153
+ * @param api - Ref of the API that will be produced by the factory.
154
+ * @param instance - Implementation of the API to use.
155
+ * @public
156
+ */
157
+ declare function createApiFactory<Api, Impl extends Api>(api: ApiRef<Api>, instance: Impl): ApiFactory<Api, Impl, {}>;
158
+
47
159
  /** @public */
48
160
  type ExtensionDataValue<TData, TId extends string> = {
49
161
  readonly $$type: '@backstage/ExtensionDataValue';
@@ -290,8 +402,8 @@ type SortExtensions<T extends readonly ExtensionDefinition[]> = T extends [
290
402
  low: infer ILow extends readonly ExtensionDefinition[],
291
403
  high: infer IHigh extends readonly ExtensionDefinition[]
292
404
  ] ? [...SortExtensions<ILow>, IPivot, ...SortExtensions<IHigh>] : 'invalid SortExtensionsInner' : [];
293
- type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
294
- type PopUnion$1<U> = UnionToIntersection<U extends any ? () => U : never> extends () => infer R ? [next: R, rest: Exclude<U, R>] : undefined;
405
+ type UnionToIntersection$1<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
406
+ type PopUnion$1<U> = UnionToIntersection$1<U extends any ? () => U : never> extends () => infer R ? [next: R, rest: Exclude<U, R>] : undefined;
295
407
  type UnionToArray<U, T = U, TResult extends T[] = []> = PopUnion$1<U> extends [
296
408
  next: infer INext extends T,
297
409
  rest: infer IRest extends T
@@ -1240,173 +1352,936 @@ interface AppTreeApi {
1240
1352
  *
1241
1353
  * @public
1242
1354
  */
1243
- declare const appTreeApiRef: _backstage_core_plugin_api.ApiRef<AppTreeApi>;
1244
-
1245
- /** @public */
1246
- interface ExtensionBoundaryProps {
1247
- node: AppNode;
1248
- children: ReactNode;
1249
- }
1250
- /** @public */
1251
- declare function ExtensionBoundary(props: ExtensionBoundaryProps): react_jsx_runtime.JSX.Element;
1252
- /** @public */
1253
- declare namespace ExtensionBoundary {
1254
- function lazy(appNode: AppNode, loader: () => Promise<JSX.Element>): JSX.Element;
1255
- function lazyComponent<TProps extends {}>(appNode: AppNode, loader: () => Promise<(props: TProps) => JSX.Element>): (props: TProps) => JSX.Element;
1256
- }
1355
+ declare const appTreeApiRef: ApiRef<AppTreeApi>;
1257
1356
 
1258
- /** @public */
1259
- type SwappableComponentRef<TInnerComponentProps extends {} = {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
1260
- id: string;
1261
- TProps: TInnerComponentProps;
1262
- TExternalProps: TExternalComponentProps;
1263
- $$type: '@backstage/SwappableComponentRef';
1264
- };
1265
1357
  /**
1266
- * Options for creating an SwappableComponent.
1358
+ * IconComponent is the common icon type used throughout Backstage when
1359
+ * working with and rendering generic icons, including the app system icons.
1360
+ *
1361
+ * @remarks
1362
+ *
1363
+ * The type is based on SvgIcon from Material UI, but we do not want the plugin-api
1364
+ * package to have a dependency on Material UI, nor do we want the props to be as broad
1365
+ * as the SvgIconProps interface.
1366
+ *
1367
+ * If you have the need to forward additional props from SvgIconProps, you can
1368
+ * open an issue or submit a PR to the main Backstage repo. When doing so please
1369
+ * also describe your use-case and reasoning of the addition.
1267
1370
  *
1268
1371
  * @public
1269
1372
  */
1270
- type CreateSwappableComponentOptions<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
1271
- id: string;
1272
- loader?: (() => (props: TInnerComponentProps) => JSX.Element | null) | (() => Promise<(props: TInnerComponentProps) => JSX.Element | null>);
1273
- transformProps?: (props: TExternalComponentProps) => TInnerComponentProps;
1274
- };
1373
+ type IconComponent = ComponentType<{
1374
+ fontSize?: 'medium' | 'large' | 'small' | 'inherit';
1375
+ }>;
1376
+
1275
1377
  /**
1276
- * Creates a SwappableComponent that can be used to render the component, optionally overridden by the app.
1378
+ * This file contains declarations for common interfaces of auth-related APIs.
1379
+ * The declarations should be used to signal which type of authentication and
1380
+ * authorization methods each separate auth provider supports.
1277
1381
  *
1278
- * @public
1382
+ * For example, a Google OAuth provider that supports OAuth 2 and OpenID Connect,
1383
+ * would be declared as follows:
1384
+ *
1385
+ * const googleAuthApiRef = createApiRef<OAuthApi & OpenIDConnectApi>({ ... })
1279
1386
  */
1280
- declare function createSwappableComponent<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps>(options: CreateSwappableComponentOptions<TInnerComponentProps, TExternalComponentProps>): {
1281
- (props: TExternalComponentProps): JSX.Element | null;
1282
- ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;
1283
- };
1284
-
1285
1387
  /**
1286
- * React hook providing access to the current {@link AppNode}.
1388
+ * Information about the auth provider.
1287
1389
  *
1288
- * @public
1289
1390
  * @remarks
1290
1391
  *
1291
- * This hook will return the {@link AppNode} for the closest extension. This
1292
- * relies on the extension using the {@link (ExtensionBoundary:function)} component in its
1293
- * implementation, which is included by default for all common blueprints.
1392
+ * This information is used both to connect the correct auth provider in the backend, as
1393
+ * well as displaying the provider to the user.
1294
1394
  *
1295
- * If the current component is not inside an {@link (ExtensionBoundary:function)}, it will
1296
- * return `undefined`.
1395
+ * @public
1297
1396
  */
1298
- declare function useAppNode(): AppNode | undefined;
1299
-
1300
- /** @public */
1301
- type ProgressProps = {};
1302
- /** @public */
1303
- type NotFoundErrorPageProps = {
1304
- children?: ReactNode;
1305
- };
1306
- /** @public */
1307
- type ErrorDisplayProps = {
1308
- plugin?: FrontendPlugin;
1309
- error: Error;
1310
- resetError: () => void;
1397
+ type AuthProviderInfo = {
1398
+ /**
1399
+ * The ID of the auth provider. This should match with ID of the provider in the `@backstage/auth-backend`.
1400
+ */
1401
+ id: string;
1402
+ /**
1403
+ * Title for the auth provider, for example "GitHub"
1404
+ */
1405
+ title: string;
1406
+ /**
1407
+ * Icon for the auth provider.
1408
+ */
1409
+ icon: IconComponent;
1410
+ /**
1411
+ * Optional user friendly messaage to display for the auth provider.
1412
+ */
1413
+ message?: string;
1311
1414
  };
1312
-
1313
1415
  /**
1416
+ * An array of scopes, or a scope string formatted according to the
1417
+ * auth provider, which is typically a space separated list.
1418
+ *
1419
+ * @remarks
1420
+ *
1421
+ * See the documentation for each auth provider for the list of scopes
1422
+ * supported by each provider.
1423
+ *
1314
1424
  * @public
1315
1425
  */
1316
- declare const Progress: {
1317
- (props: ProgressProps): JSX.Element | null;
1318
- ref: SwappableComponentRef<ProgressProps, ProgressProps>;
1319
- };
1426
+ type OAuthScope = string | string[];
1320
1427
  /**
1428
+ * Configuration of an authentication request.
1429
+ *
1321
1430
  * @public
1322
1431
  */
1323
- declare const NotFoundErrorPage: {
1324
- (props: NotFoundErrorPageProps): JSX.Element | null;
1325
- ref: SwappableComponentRef<NotFoundErrorPageProps, NotFoundErrorPageProps>;
1432
+ type AuthRequestOptions = {
1433
+ /**
1434
+ * If this is set to true, the user will not be prompted to log in,
1435
+ * and an empty response will be returned if there is no existing session.
1436
+ *
1437
+ * This can be used to perform a check whether the user is logged in, or if you don't
1438
+ * want to force a user to be logged in, but provide functionality if they already are.
1439
+ *
1440
+ * @defaultValue false
1441
+ */
1442
+ optional?: boolean;
1443
+ /**
1444
+ * If this is set to true, the request will bypass the regular oauth login modal
1445
+ * and open the login popup directly.
1446
+ *
1447
+ * The method must be called synchronously from a user action for this to work in all browsers.
1448
+ *
1449
+ * @defaultValue false
1450
+ */
1451
+ instantPopup?: boolean;
1326
1452
  };
1327
1453
  /**
1454
+ * This API provides access to OAuth 2 credentials. It lets you request access tokens,
1455
+ * which can be used to act on behalf of the user when talking to APIs.
1456
+ *
1328
1457
  * @public
1329
1458
  */
1330
- declare const ErrorDisplay: {
1331
- (props: ErrorDisplayProps): JSX.Element | null;
1332
- ref: SwappableComponentRef<ErrorDisplayProps, ErrorDisplayProps>;
1459
+ type OAuthApi = {
1460
+ /**
1461
+ * Requests an OAuth 2 Access Token, optionally with a set of scopes. The access token allows
1462
+ * you to make requests on behalf of the user, and the copes may grant you broader access, depending
1463
+ * on the auth provider.
1464
+ *
1465
+ * Each auth provider has separate handling of scope, so you need to look at the documentation
1466
+ * for each one to know what scope you need to request.
1467
+ *
1468
+ * This method is cheap and should be called each time an access token is used. Do not for example
1469
+ * store the access token in React component state, as that could cause the token to expire. Instead
1470
+ * fetch a new access token for each request.
1471
+ *
1472
+ * Be sure to include all required scopes when requesting an access token. When testing your implementation
1473
+ * it is best to log out the Backstage session and then visit your plugin page directly, as
1474
+ * you might already have some required scopes in your existing session. Not requesting the correct
1475
+ * scopes can lead to 403 or other authorization errors, which can be tricky to debug.
1476
+ *
1477
+ * If the user has not yet granted access to the provider and the set of requested scopes, the user
1478
+ * will be prompted to log in. The returned promise will not resolve until the user has
1479
+ * successfully logged in. The returned promise can be rejected, but only if the user rejects the login request.
1480
+ */
1481
+ getAccessToken(scope?: OAuthScope, options?: AuthRequestOptions): Promise<string>;
1333
1482
  };
1334
-
1335
1483
  /**
1336
- * API for looking up components based on component refs.
1484
+ * This API provides access to OpenID Connect credentials. It lets you request ID tokens,
1485
+ * which can be passed to backend services to prove the user's identity.
1337
1486
  *
1338
1487
  * @public
1339
1488
  */
1340
- interface SwappableComponentsApi {
1341
- getComponent<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps>(ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>): (props: TInnerComponentProps) => JSX.Element | null;
1342
- }
1489
+ type OpenIdConnectApi = {
1490
+ /**
1491
+ * Requests an OpenID Connect ID Token.
1492
+ *
1493
+ * This method is cheap and should be called each time an ID token is used. Do not for example
1494
+ * store the id token in React component state, as that could cause the token to expire. Instead
1495
+ * fetch a new id token for each request.
1496
+ *
1497
+ * If the user has not yet logged in to Google inside Backstage, the user will be prompted
1498
+ * to log in. The returned promise will not resolve until the user has successfully logged in.
1499
+ * The returned promise can be rejected, but only if the user rejects the login request.
1500
+ */
1501
+ getIdToken(options?: AuthRequestOptions): Promise<string>;
1502
+ };
1343
1503
  /**
1344
- * The `ApiRef` of {@link SwappableComponentsApi}.
1504
+ * This API provides access to profile information of the user from an auth provider.
1345
1505
  *
1346
1506
  * @public
1347
1507
  */
1348
- declare const swappableComponentsApiRef: _backstage_core_plugin_api.ApiRef<SwappableComponentsApi>;
1349
-
1508
+ type ProfileInfoApi = {
1509
+ /**
1510
+ * Get profile information for the user as supplied by this auth provider.
1511
+ *
1512
+ * If the optional flag is not set, a session is guaranteed to be returned, while if
1513
+ * the optional flag is set, the session may be undefined. See {@link AuthRequestOptions} for more details.
1514
+ */
1515
+ getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
1516
+ };
1350
1517
  /**
1351
- * IconComponent is the common icon type used throughout Backstage when
1352
- * working with and rendering generic icons, including the app system icons.
1518
+ * This API provides access to the user's identity within Backstage.
1353
1519
  *
1354
1520
  * @remarks
1355
1521
  *
1356
- * The type is based on SvgIcon from Material UI, but we do not want the plugin-api
1357
- * package to have a dependency on Material UI, nor do we want the props to be as broad
1358
- * as the SvgIconProps interface.
1359
- *
1360
- * If you have the need to forward additional props from SvgIconProps, you can
1361
- * open an issue or submit a PR to the main Backstage repo. When doing so please
1362
- * also describe your use-case and reasoning of the addition.
1522
+ * An auth provider that implements this interface can be used to sign-in to backstage. It is
1523
+ * not intended to be used directly from a plugin, but instead serves as a connection between
1524
+ * this authentication method and the app's {@link IdentityApi}
1363
1525
  *
1364
1526
  * @public
1365
1527
  */
1366
- type IconComponent = ComponentType<{
1367
- fontSize?: 'medium' | 'large' | 'small' | 'inherit';
1368
- }>;
1369
-
1528
+ type BackstageIdentityApi = {
1529
+ /**
1530
+ * Get the user's identity within Backstage. This should normally not be called directly,
1531
+ * use the {@link IdentityApi} instead.
1532
+ *
1533
+ * If the optional flag is not set, a session is guaranteed to be returned, while if
1534
+ * the optional flag is set, the session may be undefined. See {@link AuthRequestOptions} for more details.
1535
+ */
1536
+ getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentityResponse | undefined>;
1537
+ };
1370
1538
  /**
1371
- * API for accessing app icons.
1539
+ * User identity information within Backstage.
1372
1540
  *
1373
1541
  * @public
1374
1542
  */
1375
- interface IconsApi {
1376
- getIcon(key: string): IconComponent | undefined;
1377
- listIconKeys(): string[];
1378
- }
1543
+ type BackstageUserIdentity = {
1544
+ /**
1545
+ * The type of identity that this structure represents. In the frontend app
1546
+ * this will currently always be 'user'.
1547
+ */
1548
+ type: 'user';
1549
+ /**
1550
+ * The entityRef of the user in the catalog.
1551
+ * For example User:default/sandra
1552
+ */
1553
+ userEntityRef: string;
1554
+ /**
1555
+ * The user and group entities that the user claims ownership through
1556
+ */
1557
+ ownershipEntityRefs: string[];
1558
+ };
1379
1559
  /**
1380
- * The `ApiRef` of {@link IconsApi}.
1560
+ * Token and Identity response, with the users claims in the Identity.
1381
1561
  *
1382
1562
  * @public
1383
1563
  */
1384
- declare const iconsApiRef: _backstage_core_plugin_api.ApiRef<IconsApi>;
1385
-
1564
+ type BackstageIdentityResponse = {
1565
+ /**
1566
+ * The token used to authenticate the user within Backstage.
1567
+ */
1568
+ token: string;
1569
+ /**
1570
+ * The time at which the token expires. If not set, it can be assumed that the token does not expire.
1571
+ */
1572
+ expiresAt?: Date;
1573
+ /**
1574
+ * Identity information derived from the token.
1575
+ */
1576
+ identity: BackstageUserIdentity;
1577
+ };
1386
1578
  /**
1387
- * A handle for an open dialog that can be used to interact with it.
1388
- *
1389
- * @remarks
1390
- *
1391
- * Dialogs can be opened using either {@link DialogApi.show} or {@link DialogApi.showModal}.
1579
+ * Profile information of the user.
1392
1580
  *
1393
1581
  * @public
1394
1582
  */
1395
- interface DialogApiDialog<TResult = void> {
1583
+ type ProfileInfo = {
1396
1584
  /**
1397
- * Closes the dialog with that provided result.
1398
- *
1399
- * @remarks
1400
- *
1401
- * If the dialog is a modal dialog a result must always be provided. If it's a regular dialog then passing a result is optional.
1585
+ * Email ID.
1402
1586
  */
1403
- close(...args: undefined extends TResult ? [result?: TResult] : [result: TResult]): void;
1587
+ email?: string;
1404
1588
  /**
1405
- * Replaces the content of the dialog with the provided element or component, causing it to be rerenedered.
1589
+ * Display name that can be presented to the user.
1406
1590
  */
1407
- update(elementOrComponent: React.JSX.Element | ((props: {
1408
- dialog: DialogApiDialog<TResult>;
1409
- }) => JSX.Element)): void;
1591
+ displayName?: string;
1592
+ /**
1593
+ * URL to an avatar image of the user.
1594
+ */
1595
+ picture?: string;
1596
+ };
1597
+ /**
1598
+ * Session state values passed to subscribers of the SessionApi.
1599
+ *
1600
+ * @public
1601
+ */
1602
+ declare const SessionState: {
1603
+ /**
1604
+ * User signed in.
1605
+ */
1606
+ readonly SignedIn: "SignedIn";
1607
+ /**
1608
+ * User not signed in.
1609
+ */
1610
+ readonly SignedOut: "SignedOut";
1611
+ };
1612
+ /**
1613
+ * @public
1614
+ */
1615
+ type SessionState = (typeof SessionState)[keyof typeof SessionState];
1616
+ /**
1617
+ * @public
1618
+ */
1619
+ declare namespace SessionState {
1620
+ type SignedIn = typeof SessionState.SignedIn;
1621
+ type SignedOut = typeof SessionState.SignedOut;
1622
+ }
1623
+ /**
1624
+ * The SessionApi provides basic controls for any auth provider that is tied to a persistent session.
1625
+ *
1626
+ * @public
1627
+ */
1628
+ type SessionApi = {
1629
+ /**
1630
+ * Sign in with a minimum set of permissions.
1631
+ */
1632
+ signIn(): Promise<void>;
1633
+ /**
1634
+ * Sign out from the current session. This will reload the page.
1635
+ */
1636
+ signOut(): Promise<void>;
1637
+ /**
1638
+ * Observe the current state of the auth session. Emits the current state on subscription.
1639
+ */
1640
+ sessionState$(): Observable<SessionState>;
1641
+ };
1642
+ /**
1643
+ * Provides authentication towards Google APIs and identities.
1644
+ *
1645
+ * @public
1646
+ * @remarks
1647
+ *
1648
+ * See {@link https://developers.google.com/identity/protocols/googlescopes} for a full list of supported scopes.
1649
+ *
1650
+ * Note that the ID token payload is only guaranteed to contain the user's numerical Google ID,
1651
+ * email and expiration information. Do not rely on any other fields, as they might not be present.
1652
+ */
1653
+ declare const googleAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1654
+ /**
1655
+ * Provides authentication towards GitHub APIs.
1656
+ *
1657
+ * @public
1658
+ * @remarks
1659
+ *
1660
+ * See {@link https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/}
1661
+ * for a full list of supported scopes.
1662
+ */
1663
+ declare const githubAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1664
+ /**
1665
+ * Provides authentication towards Okta APIs.
1666
+ *
1667
+ * @public
1668
+ * @remarks
1669
+ *
1670
+ * See {@link https://developer.okta.com/docs/guides/implement-oauth-for-okta/scopes/}
1671
+ * for a full list of supported scopes.
1672
+ */
1673
+ declare const oktaAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1674
+ /**
1675
+ * Provides authentication towards GitLab APIs.
1676
+ *
1677
+ * @public
1678
+ * @remarks
1679
+ *
1680
+ * See {@link https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#limiting-scopes-of-a-personal-access-token}
1681
+ * for a full list of supported scopes.
1682
+ */
1683
+ declare const gitlabAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1684
+ /**
1685
+ * Provides authentication towards Microsoft APIs and identities.
1686
+ *
1687
+ * @public
1688
+ * @remarks
1689
+ *
1690
+ * For more info and a full list of supported scopes, see:
1691
+ * - {@link https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent}
1692
+ * - {@link https://docs.microsoft.com/en-us/graph/permissions-reference}
1693
+ */
1694
+ declare const microsoftAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1695
+ /**
1696
+ * Provides authentication towards OneLogin APIs.
1697
+ *
1698
+ * @public
1699
+ */
1700
+ declare const oneloginAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1701
+ /**
1702
+ * Provides authentication towards Bitbucket APIs.
1703
+ *
1704
+ * @public
1705
+ * @remarks
1706
+ *
1707
+ * See {@link https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/}
1708
+ * for a full list of supported scopes.
1709
+ */
1710
+ declare const bitbucketAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1711
+ /**
1712
+ * Provides authentication towards Bitbucket Server APIs.
1713
+ *
1714
+ * @public
1715
+ * @remarks
1716
+ *
1717
+ * See {@link https://confluence.atlassian.com/bitbucketserver/bitbucket-oauth-2-0-provider-api-1108483661.html#BitbucketOAuth2.0providerAPI-scopes}
1718
+ * for a full list of supported scopes.
1719
+ */
1720
+ declare const bitbucketServerAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1721
+ /**
1722
+ * Provides authentication towards Atlassian APIs.
1723
+ *
1724
+ * @public
1725
+ * @remarks
1726
+ *
1727
+ * See {@link https://developer.atlassian.com/cloud/jira/platform/scopes-for-connect-and-oauth-2-3LO-apps/}
1728
+ * for a full list of supported scopes.
1729
+ */
1730
+ declare const atlassianAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1731
+ /**
1732
+ * Provides authentication towards VMware Cloud APIs and identities.
1733
+ *
1734
+ * @public
1735
+ * @remarks
1736
+ *
1737
+ * For more info about VMware Cloud identity and access management:
1738
+ * - {@link https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-53D39337-D93A-4B84-BD18-DDF43C21479A.html}
1739
+ */
1740
+ declare const vmwareCloudAuthApiRef: ApiRef<OAuthApi & OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1741
+ /**
1742
+ * Provides authentication towards OpenShift APIs and identities.
1743
+ *
1744
+ * @public
1745
+ * @remarks
1746
+ *
1747
+ * See {@link https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/authentication_and_authorization/configuring-oauth-clients}
1748
+ * on how to configure the OAuth clients and
1749
+ * {@link https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html-single/authentication_and_authorization/index#tokens-scoping-about_configuring-internal-oauth}
1750
+ * for available scopes.
1751
+ */
1752
+ declare const openshiftAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi>;
1753
+
1754
+ /**
1755
+ * Message handled by the {@link AlertApi}.
1756
+ *
1757
+ * @public
1758
+ */
1759
+ type AlertMessage = {
1760
+ message: string;
1761
+ severity?: 'success' | 'info' | 'warning' | 'error';
1762
+ display?: 'permanent' | 'transient';
1763
+ };
1764
+ /**
1765
+ * The alert API is used to report alerts to the app, and display them to the user.
1766
+ *
1767
+ * @public
1768
+ */
1769
+ type AlertApi = {
1770
+ /**
1771
+ * Post an alert for handling by the application.
1772
+ */
1773
+ post(alert: AlertMessage): void;
1774
+ /**
1775
+ * Observe alerts posted by other parts of the application.
1776
+ */
1777
+ alert$(): Observable<AlertMessage>;
1778
+ };
1779
+ /**
1780
+ * The {@link ApiRef} of {@link AlertApi}.
1781
+ *
1782
+ * @public
1783
+ */
1784
+ declare const alertApiRef: ApiRef<AlertApi>;
1785
+
1786
+ /** @public */
1787
+ type AppLanguageApi = {
1788
+ getAvailableLanguages(): {
1789
+ languages: string[];
1790
+ };
1791
+ setLanguage(language?: string): void;
1792
+ getLanguage(): {
1793
+ language: string;
1794
+ };
1795
+ language$(): Observable<{
1796
+ language: string;
1797
+ }>;
1798
+ };
1799
+ /**
1800
+ * @public
1801
+ */
1802
+ declare const appLanguageApiRef: ApiRef<AppLanguageApi>;
1803
+
1804
+ /**
1805
+ * Describes a theme provided by the app.
1806
+ *
1807
+ * @public
1808
+ */
1809
+ type AppTheme = {
1810
+ /**
1811
+ * ID used to remember theme selections.
1812
+ */
1813
+ id: string;
1814
+ /**
1815
+ * Title of the theme
1816
+ */
1817
+ title: string;
1818
+ /**
1819
+ * Theme variant
1820
+ */
1821
+ variant: 'light' | 'dark';
1822
+ /**
1823
+ * An Icon for the theme mode setting.
1824
+ */
1825
+ icon?: React.ReactElement;
1826
+ Provider(props: {
1827
+ children: ReactNode;
1828
+ }): JSX.Element | null;
1829
+ };
1830
+ /**
1831
+ * The AppThemeApi gives access to the current app theme, and allows switching
1832
+ * to other options that have been registered as a part of the App.
1833
+ *
1834
+ * @public
1835
+ */
1836
+ type AppThemeApi = {
1837
+ /**
1838
+ * Get a list of available themes.
1839
+ */
1840
+ getInstalledThemes(): AppTheme[];
1841
+ /**
1842
+ * Observe the currently selected theme. A value of undefined means no specific theme has been selected.
1843
+ */
1844
+ activeThemeId$(): Observable<string | undefined>;
1845
+ /**
1846
+ * Get the current theme ID. Returns undefined if no specific theme is selected.
1847
+ */
1848
+ getActiveThemeId(): string | undefined;
1849
+ /**
1850
+ * Set a specific theme to use in the app, overriding the default theme selection.
1851
+ *
1852
+ * Clear the selection by passing in undefined.
1853
+ */
1854
+ setActiveThemeId(themeId?: string): void;
1855
+ };
1856
+ /**
1857
+ * The {@link ApiRef} of {@link AppThemeApi}.
1858
+ *
1859
+ * @public
1860
+ */
1861
+ declare const appThemeApiRef: ApiRef<AppThemeApi>;
1862
+
1863
+ /** @public */
1864
+ interface ExtensionBoundaryProps {
1865
+ node: AppNode;
1866
+ children: ReactNode;
1867
+ }
1868
+ /** @public */
1869
+ declare function ExtensionBoundary(props: ExtensionBoundaryProps): react_jsx_runtime.JSX.Element;
1870
+ /** @public */
1871
+ declare namespace ExtensionBoundary {
1872
+ function lazy(appNode: AppNode, loader: () => Promise<JSX.Element>): JSX.Element;
1873
+ function lazyComponent<TProps extends {}>(appNode: AppNode, loader: () => Promise<(props: TProps) => JSX.Element>): (props: TProps) => JSX.Element;
1874
+ }
1875
+
1876
+ /** @public */
1877
+ type SwappableComponentRef<TInnerComponentProps extends {} = {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
1878
+ id: string;
1879
+ TProps: TInnerComponentProps;
1880
+ TExternalProps: TExternalComponentProps;
1881
+ $$type: '@backstage/SwappableComponentRef';
1882
+ };
1883
+ /**
1884
+ * Options for creating an SwappableComponent.
1885
+ *
1886
+ * @public
1887
+ */
1888
+ type CreateSwappableComponentOptions<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
1889
+ id: string;
1890
+ loader?: (() => (props: TInnerComponentProps) => JSX.Element | null) | (() => Promise<(props: TInnerComponentProps) => JSX.Element | null>);
1891
+ transformProps?: (props: TExternalComponentProps) => TInnerComponentProps;
1892
+ };
1893
+ /**
1894
+ * Creates a SwappableComponent that can be used to render the component, optionally overridden by the app.
1895
+ *
1896
+ * @public
1897
+ */
1898
+ declare function createSwappableComponent<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps>(options: CreateSwappableComponentOptions<TInnerComponentProps, TExternalComponentProps>): {
1899
+ (props: TExternalComponentProps): JSX.Element | null;
1900
+ ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;
1901
+ };
1902
+
1903
+ /**
1904
+ * React hook providing access to the current {@link AppNode}.
1905
+ *
1906
+ * @public
1907
+ * @remarks
1908
+ *
1909
+ * This hook will return the {@link AppNode} for the closest extension. This
1910
+ * relies on the extension using the {@link (ExtensionBoundary:function)} component in its
1911
+ * implementation, which is included by default for all common blueprints.
1912
+ *
1913
+ * If the current component is not inside an {@link (ExtensionBoundary:function)}, it will
1914
+ * return `undefined`.
1915
+ */
1916
+ declare function useAppNode(): AppNode | undefined;
1917
+
1918
+ /** @public */
1919
+ type ProgressProps = {};
1920
+ /** @public */
1921
+ type NotFoundErrorPageProps = {
1922
+ children?: ReactNode;
1923
+ };
1924
+ /** @public */
1925
+ type ErrorDisplayProps = {
1926
+ plugin?: FrontendPlugin;
1927
+ error: Error;
1928
+ resetError: () => void;
1929
+ };
1930
+
1931
+ /**
1932
+ * @public
1933
+ */
1934
+ declare const Progress: {
1935
+ (props: ProgressProps): JSX.Element | null;
1936
+ ref: SwappableComponentRef<ProgressProps, ProgressProps>;
1937
+ };
1938
+ /**
1939
+ * @public
1940
+ */
1941
+ declare const NotFoundErrorPage: {
1942
+ (props: NotFoundErrorPageProps): JSX.Element | null;
1943
+ ref: SwappableComponentRef<NotFoundErrorPageProps, NotFoundErrorPageProps>;
1944
+ };
1945
+ /**
1946
+ * @public
1947
+ */
1948
+ declare const ErrorDisplay: {
1949
+ (props: ErrorDisplayProps): JSX.Element | null;
1950
+ ref: SwappableComponentRef<ErrorDisplayProps, ErrorDisplayProps>;
1951
+ };
1952
+
1953
+ /**
1954
+ * API for looking up components based on component refs.
1955
+ *
1956
+ * @public
1957
+ */
1958
+ interface SwappableComponentsApi {
1959
+ getComponent<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps>(ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>): (props: TInnerComponentProps) => JSX.Element | null;
1960
+ }
1961
+ /**
1962
+ * The `ApiRef` of {@link SwappableComponentsApi}.
1963
+ *
1964
+ * @public
1965
+ */
1966
+ declare const swappableComponentsApiRef: ApiRef<SwappableComponentsApi>;
1967
+
1968
+ /**
1969
+ * The Config API is used to provide a mechanism to access the
1970
+ * runtime configuration of the system.
1971
+ *
1972
+ * @public
1973
+ */
1974
+ type ConfigApi = Config;
1975
+ /**
1976
+ * The {@link ApiRef} of {@link ConfigApi}.
1977
+ *
1978
+ * @public
1979
+ */
1980
+ declare const configApiRef: ApiRef<ConfigApi>;
1981
+
1982
+ /**
1983
+ * The discovery API is used to provide a mechanism for plugins to
1984
+ * discover the endpoint to use to talk to their backend counterpart.
1985
+ *
1986
+ * @remarks
1987
+ *
1988
+ * The purpose of the discovery API is to allow for many different deployment
1989
+ * setups and routing methods through a central configuration, instead
1990
+ * of letting each individual plugin manage that configuration.
1991
+ *
1992
+ * Implementations of the discovery API can be a simple as a URL pattern
1993
+ * using the pluginId, but could also have overrides for individual plugins,
1994
+ * or query a separate discovery service.
1995
+ *
1996
+ * @public
1997
+ */
1998
+ type DiscoveryApi = {
1999
+ /**
2000
+ * Returns the HTTP base backend URL for a given plugin, without a trailing slash.
2001
+ *
2002
+ * This method must always be called just before making a request, as opposed to
2003
+ * fetching the URL when constructing an API client. That is to ensure that more
2004
+ * flexible routing patterns can be supported.
2005
+ *
2006
+ * For example, asking for the URL for `auth` may return something
2007
+ * like `https://backstage.example.com/api/auth`
2008
+ */
2009
+ getBaseUrl(pluginId: string): Promise<string>;
2010
+ };
2011
+ /**
2012
+ * The {@link ApiRef} of {@link DiscoveryApi}.
2013
+ *
2014
+ * @public
2015
+ */
2016
+ declare const discoveryApiRef: ApiRef<DiscoveryApi>;
2017
+
2018
+ /**
2019
+ * Mirrors the JavaScript Error class, for the purpose of
2020
+ * providing documentation and optional fields.
2021
+ *
2022
+ * @public
2023
+ */
2024
+ type ErrorApiError = {
2025
+ name: string;
2026
+ message: string;
2027
+ stack?: string;
2028
+ };
2029
+ /**
2030
+ * Provides additional information about an error that was posted to the application.
2031
+ *
2032
+ * @public
2033
+ */
2034
+ type ErrorApiErrorContext = {
2035
+ /**
2036
+ * If set to true, this error should not be displayed to the user.
2037
+ *
2038
+ * Hidden errors are typically not displayed in the UI, but the ErrorApi
2039
+ * implementation may still report them to error tracking services
2040
+ * or other utilities that care about all errors.
2041
+ *
2042
+ * @defaultValue false
2043
+ */
2044
+ hidden?: boolean;
2045
+ };
2046
+ /**
2047
+ * The error API is used to report errors to the app, and display them to the user.
2048
+ *
2049
+ * @remarks
2050
+ *
2051
+ * Plugins can use this API as a method of displaying errors to the user, but also
2052
+ * to report errors for collection by error reporting services.
2053
+ *
2054
+ * If an error can be displayed inline, e.g. as feedback in a form, that should be
2055
+ * preferred over relying on this API to display the error. The main use of this API
2056
+ * for displaying errors should be for asynchronous errors, such as a failing background process.
2057
+ *
2058
+ * Even if an error is displayed inline, it should still be reported through this API
2059
+ * if it would be useful to collect or log it for debugging purposes, but with
2060
+ * the hidden flag set. For example, an error arising from form field validation
2061
+ * should probably not be reported, while a failed REST call would be useful to report.
2062
+ *
2063
+ * @public
2064
+ */
2065
+ type ErrorApi = {
2066
+ /**
2067
+ * Post an error for handling by the application.
2068
+ */
2069
+ post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
2070
+ /**
2071
+ * Observe errors posted by other parts of the application.
2072
+ */
2073
+ error$(): Observable<{
2074
+ error: ErrorApiError;
2075
+ context?: ErrorApiErrorContext;
2076
+ }>;
2077
+ };
2078
+ /**
2079
+ * The {@link ApiRef} of {@link ErrorApi}.
2080
+ *
2081
+ * @public
2082
+ */
2083
+ declare const errorApiRef: ApiRef<ErrorApi>;
2084
+
2085
+ /**
2086
+ * Feature flag descriptor.
2087
+ *
2088
+ * @public
2089
+ */
2090
+ type FeatureFlag = {
2091
+ name: string;
2092
+ pluginId: string;
2093
+ description?: string;
2094
+ };
2095
+ /**
2096
+ * Enum representing the state of a feature flag (inactive/active).
2097
+ *
2098
+ * @public
2099
+ */
2100
+ declare const FeatureFlagState: {
2101
+ /**
2102
+ * Feature flag inactive (disabled).
2103
+ */
2104
+ readonly None: 0;
2105
+ /**
2106
+ * Feature flag active (enabled).
2107
+ */
2108
+ readonly Active: 1;
2109
+ };
2110
+ /**
2111
+ * @public
2112
+ */
2113
+ type FeatureFlagState = (typeof FeatureFlagState)[keyof typeof FeatureFlagState];
2114
+ /**
2115
+ * @public
2116
+ */
2117
+ declare namespace FeatureFlagState {
2118
+ type None = typeof FeatureFlagState.None;
2119
+ type Active = typeof FeatureFlagState.Active;
2120
+ }
2121
+ /**
2122
+ * Options to use when saving feature flags.
2123
+ *
2124
+ * @public
2125
+ */
2126
+ type FeatureFlagsSaveOptions = {
2127
+ /**
2128
+ * The new feature flag states to save.
2129
+ */
2130
+ states: Record<string, FeatureFlagState>;
2131
+ /**
2132
+ * Whether the saves states should be merged into the existing ones, or replace them.
2133
+ *
2134
+ * Defaults to false.
2135
+ */
2136
+ merge?: boolean;
2137
+ };
2138
+ /**
2139
+ * The feature flags API is used to toggle functionality to users across plugins and Backstage.
2140
+ *
2141
+ * @remarks
2142
+ *
2143
+ * Plugins can use this API to register feature flags that they have available
2144
+ * for users to enable/disable, and this API will centralize the current user's
2145
+ * state of which feature flags they would like to enable.
2146
+ *
2147
+ * This is ideal for Backstage plugins, as well as your own App, to trial incomplete
2148
+ * or unstable upcoming features. Although there will be a common interface for users
2149
+ * to enable and disable feature flags, this API acts as another way to enable/disable.
2150
+ *
2151
+ * @public
2152
+ */
2153
+ interface FeatureFlagsApi {
2154
+ /**
2155
+ * Registers a new feature flag. Once a feature flag has been registered it
2156
+ * can be toggled by users, and read back to enable or disable features.
2157
+ */
2158
+ registerFlag(flag: FeatureFlag): void;
2159
+ /**
2160
+ * Get a list of all registered flags.
2161
+ */
2162
+ getRegisteredFlags(): FeatureFlag[];
2163
+ /**
2164
+ * Whether the feature flag with the given name is currently activated for the user.
2165
+ */
2166
+ isActive(name: string): boolean;
2167
+ /**
2168
+ * Save the user's choice of feature flag states.
2169
+ */
2170
+ save(options: FeatureFlagsSaveOptions): void;
2171
+ }
2172
+ /**
2173
+ * The {@link ApiRef} of {@link FeatureFlagsApi}.
2174
+ *
2175
+ * @public
2176
+ */
2177
+ declare const featureFlagsApiRef: ApiRef<FeatureFlagsApi>;
2178
+
2179
+ /**
2180
+ * A wrapper for the fetch API, that has additional behaviors such as the
2181
+ * ability to automatically inject auth information where necessary.
2182
+ *
2183
+ * @public
2184
+ */
2185
+ type FetchApi = {
2186
+ /**
2187
+ * The `fetch` implementation.
2188
+ */
2189
+ fetch: typeof fetch;
2190
+ };
2191
+ /**
2192
+ * The {@link ApiRef} of {@link FetchApi}.
2193
+ *
2194
+ * @remarks
2195
+ *
2196
+ * This is a wrapper for the fetch API, that has additional behaviors such as
2197
+ * the ability to automatically inject auth information where necessary.
2198
+ *
2199
+ * Note that the default behavior of this API (unless overridden by your org),
2200
+ * is to require that the user is already signed in so that it has auth
2201
+ * information to inject. Therefore, using the default implementation of this
2202
+ * utility API e.g. on the `SignInPage` or similar, would cause issues. In
2203
+ * special circumstances like those, you can use the regular system `fetch`
2204
+ * instead.
2205
+ *
2206
+ * @public
2207
+ */
2208
+ declare const fetchApiRef: ApiRef<FetchApi>;
2209
+
2210
+ /**
2211
+ * API for accessing app icons.
2212
+ *
2213
+ * @public
2214
+ */
2215
+ interface IconsApi {
2216
+ getIcon(key: string): IconComponent | undefined;
2217
+ listIconKeys(): string[];
2218
+ }
2219
+ /**
2220
+ * The `ApiRef` of {@link IconsApi}.
2221
+ *
2222
+ * @public
2223
+ */
2224
+ declare const iconsApiRef: ApiRef<IconsApi>;
2225
+
2226
+ /**
2227
+ * The Identity API used to identify and get information about the signed in user.
2228
+ *
2229
+ * @public
2230
+ */
2231
+ type IdentityApi = {
2232
+ /**
2233
+ * The profile of the signed in user.
2234
+ */
2235
+ getProfileInfo(): Promise<ProfileInfo>;
2236
+ /**
2237
+ * User identity information within Backstage.
2238
+ */
2239
+ getBackstageIdentity(): Promise<BackstageUserIdentity>;
2240
+ /**
2241
+ * Provides credentials in the form of a token which proves the identity of the signed in user.
2242
+ *
2243
+ * The token will be undefined if the signed in user does not have a verified
2244
+ * identity, such as a demo user or mocked user for e2e tests.
2245
+ */
2246
+ getCredentials(): Promise<{
2247
+ token?: string;
2248
+ }>;
2249
+ /**
2250
+ * Sign out the current user
2251
+ */
2252
+ signOut(): Promise<void>;
2253
+ };
2254
+ /**
2255
+ * The {@link ApiRef} of {@link IdentityApi}.
2256
+ *
2257
+ * @public
2258
+ */
2259
+ declare const identityApiRef: ApiRef<IdentityApi>;
2260
+
2261
+ /**
2262
+ * A handle for an open dialog that can be used to interact with it.
2263
+ *
2264
+ * @remarks
2265
+ *
2266
+ * Dialogs can be opened using either {@link DialogApi.show} or {@link DialogApi.showModal}.
2267
+ *
2268
+ * @public
2269
+ */
2270
+ interface DialogApiDialog<TResult = void> {
2271
+ /**
2272
+ * Closes the dialog with that provided result.
2273
+ *
2274
+ * @remarks
2275
+ *
2276
+ * If the dialog is a modal dialog a result must always be provided. If it's a regular dialog then passing a result is optional.
2277
+ */
2278
+ close(...args: undefined extends TResult ? [result?: TResult] : [result: TResult]): void;
2279
+ /**
2280
+ * Replaces the content of the dialog with the provided element or component, causing it to be rerenedered.
2281
+ */
2282
+ update(elementOrComponent: React.JSX.Element | ((props: {
2283
+ dialog: DialogApiDialog<TResult>;
2284
+ }) => JSX.Element)): void;
1410
2285
  /**
1411
2286
  * Wait until the dialog is closed and return the result.
1412
2287
  *
@@ -1495,37 +2370,135 @@ interface DialogApi {
1495
2370
  * const result = await dialog.result();
1496
2371
  * ```
1497
2372
  *
1498
- * @example
2373
+ * @example
2374
+ *
2375
+ * ### Example with separate dialog component
2376
+ * ```tsx
2377
+ * function CustomDialog({ dialog }: { dialog: DialogApiDialog<boolean> }) {
2378
+ * return (
2379
+ * <DialogContent>
2380
+ * <DialogTitle>Are you sure?</DialogTitle>
2381
+ * <DialogActions>
2382
+ * <Button onClick={() => dialog.close(true)}>Yes</Button>
2383
+ * <Button onClick={() => dialog.close(false)}>No</Button>
2384
+ * </DialogActions>
2385
+ * </DialogContent>
2386
+ * )
2387
+ * }
2388
+ * const result = await dialogApi.showModal(CustomDialog).result();
2389
+ * ```
2390
+ *
2391
+ * @param elementOrComponent - The element or component to render in the dialog. If a component is provided, it will be provided with a `dialog` prop that contains the dialog handle.
2392
+ * @public
2393
+ */
2394
+ showModal<TResult = void>(elementOrComponent: JSX.Element | ((props: {
2395
+ dialog: DialogApiDialog<TResult>;
2396
+ }) => JSX.Element)): DialogApiDialog<TResult>;
2397
+ }
2398
+ /**
2399
+ * The `ApiRef` of {@link DialogApi}.
2400
+ *
2401
+ * @public
2402
+ */
2403
+ declare const dialogApiRef: ApiRef<DialogApi>;
2404
+
2405
+ /**
2406
+ * Describes how to handle auth requests. Both how to show them to the user, and what to do when
2407
+ * the user accesses the auth request.
2408
+ *
2409
+ * @public
2410
+ */
2411
+ type OAuthRequesterOptions<TOAuthResponse> = {
2412
+ /**
2413
+ * Information about the auth provider, which will be forwarded to auth requests.
2414
+ */
2415
+ provider: AuthProviderInfo;
2416
+ /**
2417
+ * Implementation of the auth flow, which will be called synchronously when
2418
+ * trigger() is called on an auth requests.
2419
+ */
2420
+ onAuthRequest(scopes: Set<string>): Promise<TOAuthResponse>;
2421
+ };
2422
+ /**
2423
+ * Function used to trigger new auth requests for a set of scopes.
2424
+ *
2425
+ * @remarks
2426
+ *
2427
+ * The returned promise will resolve to the same value returned by the onAuthRequest in the
2428
+ * {@link OAuthRequesterOptions}. Or rejected, if the request is rejected.
2429
+ *
2430
+ * This function can be called multiple times before the promise resolves. All calls
2431
+ * will be merged into one request, and the scopes forwarded to the onAuthRequest will be the
2432
+ * union of all requested scopes.
2433
+ *
2434
+ * @public
2435
+ */
2436
+ type OAuthRequester<TAuthResponse> = (scopes: Set<string>) => Promise<TAuthResponse>;
2437
+ /**
2438
+ * An pending auth request for a single auth provider. The request will remain in this pending
2439
+ * state until either reject() or trigger() is called.
2440
+ *
2441
+ * @remarks
2442
+ *
2443
+ * Any new requests for the same provider are merged into the existing pending request, meaning
2444
+ * there will only ever be a single pending request for a given provider.
2445
+ *
2446
+ * @public
2447
+ */
2448
+ type PendingOAuthRequest = {
2449
+ /**
2450
+ * Information about the auth provider, as given in the AuthRequesterOptions
2451
+ */
2452
+ provider: AuthProviderInfo;
2453
+ /**
2454
+ * Rejects the request, causing all pending AuthRequester calls to fail with "RejectedError".
2455
+ */
2456
+ reject(): void;
2457
+ /**
2458
+ * Trigger the auth request to continue the auth flow, by for example showing a popup.
2459
+ *
2460
+ * Synchronously calls onAuthRequest with all scope currently in the request.
2461
+ */
2462
+ trigger(): Promise<void>;
2463
+ };
2464
+ /**
2465
+ * Provides helpers for implemented OAuth login flows within Backstage.
2466
+ *
2467
+ * @public
2468
+ */
2469
+ type OAuthRequestApi = {
2470
+ /**
2471
+ * A utility for showing login popups or similar things, and merging together multiple requests for
2472
+ * different scopes into one request that includes all scopes.
2473
+ *
2474
+ * The passed in options provide information about the login provider, and how to handle auth requests.
2475
+ *
2476
+ * The returned AuthRequester function is used to request login with new scopes. These requests
2477
+ * are merged together and forwarded to the auth handler, as soon as a consumer of auth requests
2478
+ * triggers an auth flow.
2479
+ *
2480
+ * See AuthRequesterOptions, AuthRequester, and handleAuthRequests for more info.
2481
+ */
2482
+ createAuthRequester<OAuthResponse>(options: OAuthRequesterOptions<OAuthResponse>): OAuthRequester<OAuthResponse>;
2483
+ /**
2484
+ * Observers pending auth requests. The returned observable will emit all
2485
+ * current active auth request, at most one for each created auth requester.
1499
2486
  *
1500
- * ### Example with separate dialog component
1501
- * ```tsx
1502
- * function CustomDialog({ dialog }: { dialog: DialogApiDialog<boolean> }) {
1503
- * return (
1504
- * <DialogContent>
1505
- * <DialogTitle>Are you sure?</DialogTitle>
1506
- * <DialogActions>
1507
- * <Button onClick={() => dialog.close(true)}>Yes</Button>
1508
- * <Button onClick={() => dialog.close(false)}>No</Button>
1509
- * </DialogActions>
1510
- * </DialogContent>
1511
- * )
1512
- * }
1513
- * const result = await dialogApi.showModal(CustomDialog).result();
1514
- * ```
2487
+ * Each request has its own info about the login provider, forwarded from the auth requester options.
1515
2488
  *
1516
- * @param elementOrComponent - The element or component to render in the dialog. If a component is provided, it will be provided with a `dialog` prop that contains the dialog handle.
1517
- * @public
2489
+ * Depending on user interaction, the request should either be rejected, or used to trigger the auth handler.
2490
+ * If the request is rejected, all pending AuthRequester calls will fail with a "RejectedError".
2491
+ * If a auth is triggered, and the auth handler resolves successfully, then all currently pending
2492
+ * AuthRequester calls will resolve to the value returned by the onAuthRequest call.
1518
2493
  */
1519
- showModal<TResult = void>(elementOrComponent: JSX.Element | ((props: {
1520
- dialog: DialogApiDialog<TResult>;
1521
- }) => JSX.Element)): DialogApiDialog<TResult>;
1522
- }
2494
+ authRequest$(): Observable<PendingOAuthRequest[]>;
2495
+ };
1523
2496
  /**
1524
- * The `ApiRef` of {@link DialogApi}.
2497
+ * The {@link ApiRef} of {@link OAuthRequestApi}.
1525
2498
  *
1526
2499
  * @public
1527
2500
  */
1528
- declare const dialogApiRef: _backstage_core_plugin_api.ApiRef<DialogApi>;
2501
+ declare const oauthRequestApiRef: ApiRef<OAuthRequestApi>;
1529
2502
 
1530
2503
  /**
1531
2504
  * TS magic for handling route parameters.
@@ -1558,7 +2531,87 @@ interface RouteResolutionApi {
1558
2531
  *
1559
2532
  * @public
1560
2533
  */
1561
- declare const routeResolutionApiRef: _backstage_core_plugin_api.ApiRef<RouteResolutionApi>;
2534
+ declare const routeResolutionApiRef: ApiRef<RouteResolutionApi>;
2535
+
2536
+ /**
2537
+ * A snapshot in time of the current known value of a storage key.
2538
+ *
2539
+ * @public
2540
+ */
2541
+ type StorageValueSnapshot<TValue extends JsonValue> = {
2542
+ key: string;
2543
+ presence: 'unknown' | 'absent';
2544
+ value?: undefined;
2545
+ } | {
2546
+ key: string;
2547
+ presence: 'present';
2548
+ value: TValue;
2549
+ };
2550
+ /**
2551
+ * Provides a key-value persistence API.
2552
+ *
2553
+ * @public
2554
+ */
2555
+ interface StorageApi {
2556
+ /**
2557
+ * Create a bucket to store data in.
2558
+ *
2559
+ * @param name - Namespace for the storage to be stored under,
2560
+ * will inherit previous namespaces too
2561
+ */
2562
+ forBucket(name: string): StorageApi;
2563
+ /**
2564
+ * Remove persistent data.
2565
+ *
2566
+ * @param key - Unique key associated with the data.
2567
+ */
2568
+ remove(key: string): Promise<void>;
2569
+ /**
2570
+ * Save persistent data, and emit messages to anyone that is using
2571
+ * {@link StorageApi.observe$} for this key.
2572
+ *
2573
+ * @param key - Unique key associated with the data.
2574
+ * @param data - The data to be stored under the key.
2575
+ */
2576
+ set<T extends JsonValue>(key: string, data: T): Promise<void>;
2577
+ /**
2578
+ * Observe the value over time for a particular key in the current bucket.
2579
+ *
2580
+ * @remarks
2581
+ *
2582
+ * The observable will only emit values when the value changes in the underlying
2583
+ * storage, although multiple values with the same shape may be emitted in a row.
2584
+ *
2585
+ * If a {@link StorageApi.snapshot} of a key is retrieved and the presence is
2586
+ * `'unknown'`, then you are guaranteed to receive a snapshot with a known
2587
+ * presence, as long as you observe the key within the same tick.
2588
+ *
2589
+ * Since the emitted values are shared across all subscribers, it is important
2590
+ * not to mutate the returned values. The values may be frozen as a precaution.
2591
+ *
2592
+ * @param key - Unique key associated with the data
2593
+ */
2594
+ observe$<T extends JsonValue>(key: string): Observable<StorageValueSnapshot<T>>;
2595
+ /**
2596
+ * Returns an immediate snapshot value for the given key, if possible.
2597
+ *
2598
+ * @remarks
2599
+ *
2600
+ * Combine with {@link StorageApi.observe$} to get notified of value changes.
2601
+ *
2602
+ * Note that this method is synchronous, and some underlying storages may be
2603
+ * unable to retrieve a value using this method - the result may or may not
2604
+ * consistently have a presence of 'unknown'. Use {@link StorageApi.observe$}
2605
+ * to be sure to receive an actual value eventually.
2606
+ */
2607
+ snapshot<T extends JsonValue>(key: string): StorageValueSnapshot<T>;
2608
+ }
2609
+ /**
2610
+ * The {@link ApiRef} of {@link StorageApi}.
2611
+ *
2612
+ * @public
2613
+ */
2614
+ declare const storageApiRef: ApiRef<StorageApi>;
1562
2615
 
1563
2616
  /**
1564
2617
  * Represents an event worth tracking in an analytics system that could inform
@@ -1683,6 +2736,385 @@ type AnalyticsApi = {
1683
2736
  */
1684
2737
  declare const analyticsApiRef: ApiRef<AnalyticsApi>;
1685
2738
 
2739
+ /** @public */
2740
+ interface TranslationRef<TId extends string = string, TMessages extends {
2741
+ [key in string]: string;
2742
+ } = {
2743
+ [key in string]: string;
2744
+ }> {
2745
+ $$type: '@backstage/TranslationRef';
2746
+ id: TId;
2747
+ T: TMessages;
2748
+ }
2749
+ /** @ignore */
2750
+ type AnyNestedMessages = {
2751
+ [key in string]: AnyNestedMessages | string;
2752
+ };
2753
+ /**
2754
+ * Flattens a nested message declaration into a flat object with dot-separated keys.
2755
+ *
2756
+ * @ignore
2757
+ */
2758
+ type FlattenedMessages<TMessages extends AnyNestedMessages> = {
2759
+ [TKey in keyof TMessages]: (_: TMessages[TKey] extends infer TValue ? TValue extends AnyNestedMessages ? FlattenedMessages<TValue> extends infer TNested ? {
2760
+ [TNestedKey in keyof TNested as `${TKey & string}.${TNestedKey & string}`]: TNested[TNestedKey];
2761
+ } : never : {
2762
+ [_ in TKey]: TValue;
2763
+ } : never) => void;
2764
+ }[keyof TMessages] extends (_: infer TIntersection) => void ? {
2765
+ readonly [TExpandKey in keyof TIntersection]: TIntersection[TExpandKey];
2766
+ } : never;
2767
+ /** @public */
2768
+ interface TranslationRefOptions<TId extends string, TNestedMessages extends AnyNestedMessages, TTranslations extends {
2769
+ [language in string]: () => Promise<{
2770
+ default: {
2771
+ [key in keyof FlattenedMessages<TNestedMessages>]: string | null;
2772
+ };
2773
+ }>;
2774
+ }> {
2775
+ id: TId;
2776
+ messages: TNestedMessages;
2777
+ translations?: TTranslations;
2778
+ }
2779
+ /** @public */
2780
+ declare function createTranslationRef<TId extends string, const TNestedMessages extends AnyNestedMessages, TTranslations extends {
2781
+ [language in string]: () => Promise<{
2782
+ default: {
2783
+ [key in keyof FlattenedMessages<TNestedMessages>]: string | null;
2784
+ };
2785
+ }>;
2786
+ }>(config: TranslationRefOptions<TId, TNestedMessages, TTranslations>): TranslationRef<TId, FlattenedMessages<TNestedMessages>>;
2787
+
2788
+ /**
2789
+ * Represents a collection of messages to be provided for a given translation ref.
2790
+ *
2791
+ * @public
2792
+ * @remarks
2793
+ *
2794
+ * This collection of messages can either be used directly as an override for the
2795
+ * default messages, or it can be used to provide translations for a language by
2796
+ * by being referenced by a {@link TranslationResource}.
2797
+ */
2798
+ interface TranslationMessages<TId extends string = string, TMessages extends {
2799
+ [key in string]: string;
2800
+ } = {
2801
+ [key in string]: string;
2802
+ }, TFull extends boolean = boolean> {
2803
+ $$type: '@backstage/TranslationMessages';
2804
+ /** The ID of the translation ref that these messages are for */
2805
+ id: TId;
2806
+ /** Whether or not these messages override all known messages */
2807
+ full: TFull;
2808
+ /** The messages provided for the given translation ref */
2809
+ messages: TMessages;
2810
+ }
2811
+ /**
2812
+ * Options for {@link createTranslationMessages}.
2813
+ *
2814
+ * @public
2815
+ */
2816
+ interface TranslationMessagesOptions<TId extends string, TMessages extends {
2817
+ [key in string]: string;
2818
+ }, TFull extends boolean> {
2819
+ ref: TranslationRef<TId, TMessages>;
2820
+ full?: TFull;
2821
+ messages: false extends TFull ? {
2822
+ [key in keyof TMessages]?: string | null;
2823
+ } : {
2824
+ [key in keyof TMessages]: string | null;
2825
+ };
2826
+ }
2827
+ /**
2828
+ * Creates a collection of messages for a given translation ref.
2829
+ *
2830
+ * @public
2831
+ */
2832
+ declare function createTranslationMessages<TId extends string, TMessages extends {
2833
+ [key in string]: string;
2834
+ }, TFull extends boolean>(options: TranslationMessagesOptions<TId, TMessages, TFull>): TranslationMessages<TId, TMessages, TFull>;
2835
+
2836
+ /** @public */
2837
+ interface TranslationResource<TId extends string = string> {
2838
+ $$type: '@backstage/TranslationResource';
2839
+ id: TId;
2840
+ }
2841
+ /** @public */
2842
+ interface TranslationResourceOptions<TId extends string, TMessages extends {
2843
+ [key in string]: string;
2844
+ }, TTranslations extends {
2845
+ [language in string]: () => Promise<{
2846
+ default: TranslationMessages<TId> | {
2847
+ [key in keyof TMessages]: string | null;
2848
+ };
2849
+ }>;
2850
+ }> {
2851
+ ref: TranslationRef<TId, TMessages>;
2852
+ translations: TTranslations;
2853
+ }
2854
+ /** @public */
2855
+ declare function createTranslationResource<TId extends string, TMessages extends {
2856
+ [key in string]: string;
2857
+ }, TTranslations extends {
2858
+ [language in string]: () => Promise<{
2859
+ default: TranslationMessages<TId> | {
2860
+ [key in keyof TMessages]: string | null;
2861
+ };
2862
+ }>;
2863
+ }>(options: TranslationResourceOptions<TId, TMessages, TTranslations>): TranslationResource<TId>;
2864
+
2865
+ /** @public */
2866
+ declare const useTranslationRef: <TMessages extends { [key in string]: string; }>(translationRef: TranslationRef<string, TMessages>) => {
2867
+ t: TranslationFunction<TMessages>;
2868
+ };
2869
+
2870
+ /**
2871
+ * Base translation options.
2872
+ *
2873
+ * @alpha
2874
+ */
2875
+ interface BaseOptions {
2876
+ interpolation?: {
2877
+ /** Whether to HTML escape provided values, defaults to false */
2878
+ escapeValue?: boolean;
2879
+ };
2880
+ }
2881
+ /**
2882
+ * All pluralization suffixes supported by i18next
2883
+ *
2884
+ * @ignore
2885
+ */
2886
+ type TranslationPlural = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
2887
+ /**
2888
+ * A mapping of i18n formatting types to their corresponding types and options.
2889
+ * @ignore
2890
+ */
2891
+ type I18nextFormatMap = {
2892
+ number: {
2893
+ type: number;
2894
+ options: Intl.NumberFormatOptions;
2895
+ };
2896
+ currency: {
2897
+ type: number;
2898
+ options: Intl.NumberFormatOptions;
2899
+ };
2900
+ datetime: {
2901
+ type: Date;
2902
+ options: Intl.DateTimeFormatOptions;
2903
+ };
2904
+ relativetime: {
2905
+ type: number;
2906
+ options: {
2907
+ range?: Intl.RelativeTimeFormatUnit;
2908
+ } & Intl.RelativeTimeFormatOptions;
2909
+ };
2910
+ list: {
2911
+ type: string[];
2912
+ options: Intl.ListFormatOptions;
2913
+ };
2914
+ };
2915
+ /**
2916
+ * Extracts all pluralized keys from the message map.
2917
+ *
2918
+ * @example
2919
+ * ```
2920
+ * { foo: 'foo', bar_one: 'bar', bar_other: 'bars' } -> 'bar'
2921
+ * ```
2922
+ *
2923
+ * @ignore
2924
+ */
2925
+ type PluralKeys<TMessages extends {
2926
+ [key in string]: string;
2927
+ }> = {
2928
+ [Key in keyof TMessages]: Key extends `${infer K}_${TranslationPlural}` ? K : never;
2929
+ }[keyof TMessages];
2930
+ /**
2931
+ * Collapses a message map into normalized keys with union values.
2932
+ *
2933
+ * @example
2934
+ * ```
2935
+ * { foo_one: 'foo', foo_other: 'foos' } -> { foo: 'foo' | 'foos' }
2936
+ * ```
2937
+ *
2938
+ * @ignore
2939
+ */
2940
+ type CollapsedMessages<TMessages extends {
2941
+ [key in string]: string;
2942
+ }> = {
2943
+ [key in keyof TMessages as key extends `${infer K}_${TranslationPlural}` ? K : key]: TMessages[key];
2944
+ };
2945
+ /**
2946
+ * Trim away whitespace
2947
+ *
2948
+ * @ignore
2949
+ */
2950
+ type Trim<T> = T extends ` ${infer U}` ? Trim<U> : T extends `${infer U} ` ? Trim<U> : T;
2951
+ /**
2952
+ * Extracts the key and format from a replacement string.
2953
+ *
2954
+ * @example
2955
+ * ```
2956
+ * 'foo, number' -> { foo: number }, 'foo' -> { foo: undefined }
2957
+ * ```
2958
+ */
2959
+ type ExtractFormat<Replacement extends string> = Replacement extends `${infer Key},${infer FullFormat}` ? {
2960
+ [key in Trim<Key>]: Lowercase<Trim<FullFormat extends `${infer Format}(${string})${string}` ? Format : FullFormat>>;
2961
+ } : {
2962
+ [key in Trim<Replacement>]: undefined;
2963
+ };
2964
+ /**
2965
+ * Expand the keys in a flat map to nested objects.
2966
+ *
2967
+ * @example
2968
+ * ```
2969
+ * { 'a.b': 'foo', 'a.c': 'bar' } -> { a: { b: 'foo', c: 'bar' }
2970
+ * ```
2971
+ *
2972
+ * @ignore
2973
+ */
2974
+ type ExpandKeys<TMap extends {}> = {
2975
+ [Key in keyof TMap as Key extends `${infer Prefix}.${string}` ? Prefix : Key]: Key extends `${string}.${infer Rest}` ? ExpandKeys<{
2976
+ [key in Rest]: TMap[Key];
2977
+ }> : TMap[Key];
2978
+ };
2979
+ /**
2980
+ * Extracts all option keys and their format from a message string.
2981
+ *
2982
+ * @example
2983
+ * ```
2984
+ * 'foo {{bar}} {{baz, number}}' -> { 'bar': undefined, 'baz': 'number' }
2985
+ * ```
2986
+ *
2987
+ * @ignore
2988
+ */
2989
+ type ReplaceFormatsFromMessage<TMessage> = TMessage extends `${string}{{${infer Replacement}}}${infer Tail}` ? ExpandKeys<ExtractFormat<Replacement>> & ReplaceFormatsFromMessage<Tail> : {};
2990
+ /**
2991
+ * Generates the replace options structure
2992
+ *
2993
+ * @ignore
2994
+ */
2995
+ type ReplaceOptionsFromFormats<TFormats extends {}, TValueType> = {
2996
+ [Key in keyof TFormats]: TFormats[Key] extends keyof I18nextFormatMap ? I18nextFormatMap[TFormats[Key]]['type'] : TFormats[Key] extends {} ? Expand<ReplaceOptionsFromFormats<TFormats[Key], TValueType>> : TValueType;
2997
+ };
2998
+ /**
2999
+ * Generates the formatParams options structure
3000
+ *
3001
+ * @ignore
3002
+ */
3003
+ type ReplaceFormatParamsFromFormats<TFormats extends {}> = {
3004
+ [Key in keyof TFormats]?: TFormats[Key] extends keyof I18nextFormatMap ? I18nextFormatMap[TFormats[Key]]['options'] : TFormats[Key] extends {} ? Expand<ReplaceFormatParamsFromFormats<TFormats[Key]>> : undefined;
3005
+ };
3006
+ /**
3007
+ * Extracts all nesting keys from a message string.
3008
+ *
3009
+ * @example
3010
+ * ```
3011
+ * 'foo $t(bar) $t(baz)' -> 'bar' | 'baz'
3012
+ * ```
3013
+ *
3014
+ * @ignore
3015
+ */
3016
+ type NestingKeysFromMessage<TMessage extends string> = TMessage extends `${string}$t(${infer Key})${infer Tail}` ? Trim<Key> | NestingKeysFromMessage<Tail> : never;
3017
+ /**
3018
+ * Find all referenced keys, given a starting key and the full set of messages.
3019
+ *
3020
+ * This will only discover keys up to 3 levels deep.
3021
+ *
3022
+ * @example
3023
+ * ```
3024
+ * <'x', { x: '$t(y) $t(z)', y: 'y', z: '$t(w)', w: 'w', foo: 'foo' }> -> 'x' | 'y' | 'z' | 'w'
3025
+ * ```
3026
+ *
3027
+ * @ignore
3028
+ */
3029
+ type NestedMessageKeys<TKey extends keyof TMessages, TMessages extends {
3030
+ [key in string]: string;
3031
+ }> = TKey | NestedMessageKeys2<NestingKeysFromMessage<TMessages[TKey]>, TMessages>;
3032
+ type NestedMessageKeys2<TKey extends keyof TMessages, TMessages extends {
3033
+ [key in string]: string;
3034
+ }> = TKey | NestedMessageKeys3<NestingKeysFromMessage<TMessages[TKey]>, TMessages>;
3035
+ type NestedMessageKeys3<TKey extends keyof TMessages, TMessages extends {
3036
+ [key in string]: string;
3037
+ }> = TKey | NestingKeysFromMessage<TMessages[TKey]>;
3038
+ /**
3039
+ * Converts a union type to an intersection type.
3040
+ *
3041
+ * @example
3042
+ * ```
3043
+ * { foo: 'foo' } | { bar: 'bar' } -> { foo: 'foo' } & { bar: 'bar' }
3044
+ * ```
3045
+ *
3046
+ * @ignore
3047
+ */
3048
+ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
3049
+ /**
3050
+ * Collects different types of options into a single object
3051
+ *
3052
+ * @ignore
3053
+ */
3054
+ type CollectOptions<TCount extends {
3055
+ count?: number;
3056
+ }, TFormats extends {}, TValueType> = TCount & (keyof Omit<TFormats, 'count'> extends never ? {} : (Expand<Omit<ReplaceOptionsFromFormats<TFormats, TValueType>, 'count'>> | {
3057
+ replace: Expand<Omit<ReplaceOptionsFromFormats<TFormats, TValueType>, 'count'>>;
3058
+ }) & {
3059
+ formatParams?: Expand<ReplaceFormatParamsFromFormats<TFormats>>;
3060
+ });
3061
+ /**
3062
+ * Helper type to only require options argument if needed
3063
+ *
3064
+ * @ignore
3065
+ */
3066
+ type OptionArgs<TOptions extends {}> = keyof TOptions extends never ? [options?: Expand<BaseOptions>] : [options: Expand<BaseOptions & TOptions>];
3067
+ /**
3068
+ * @ignore
3069
+ */
3070
+ type TranslationFunctionOptions<TKeys extends keyof TMessages, // All normalized message keys to be considered, i.e. included nested ones
3071
+ TPluralKeys extends keyof TMessages, // All keys in the message map that are pluralized
3072
+ TMessages extends {
3073
+ [key in string]: string;
3074
+ }, // Collapsed message map with normalized keys and union values
3075
+ TValueType> = OptionArgs<Expand<CollectOptions<TKeys & TPluralKeys extends never ? {} : {
3076
+ count: number;
3077
+ }, ExpandRecursive<UnionToIntersection<ReplaceFormatsFromMessage<TMessages[TKeys]>>>, TValueType>>>;
3078
+ /** @public */
3079
+ type TranslationFunction<TMessages extends {
3080
+ [key in string]: string;
3081
+ }> = CollapsedMessages<TMessages> extends infer IMessages extends {
3082
+ [key in string]: string;
3083
+ } ? {
3084
+ /**
3085
+ * A translation function that returns a string.
3086
+ */
3087
+ <TKey extends keyof IMessages>(key: TKey, ...[args]: TranslationFunctionOptions<NestedMessageKeys<TKey, IMessages>, PluralKeys<TMessages>, IMessages, string>): IMessages[TKey];
3088
+ /**
3089
+ * A translation function where at least one JSX.Element has been
3090
+ * provided as an interpolation value, and will therefore return a
3091
+ * JSX.Element.
3092
+ */
3093
+ <TKey extends keyof IMessages>(key: TKey, ...[args]: TranslationFunctionOptions<NestedMessageKeys<TKey, IMessages>, PluralKeys<TMessages>, IMessages, string | JSX$1.Element>): JSX$1.Element;
3094
+ } : never;
3095
+ /** @public */
3096
+ type TranslationSnapshot<TMessages extends {
3097
+ [key in string]: string;
3098
+ }> = {
3099
+ ready: false;
3100
+ } | {
3101
+ ready: true;
3102
+ t: TranslationFunction<TMessages>;
3103
+ };
3104
+ /** @public */
3105
+ type TranslationApi = {
3106
+ getTranslation<TMessages extends {
3107
+ [key in string]: string;
3108
+ }>(translationRef: TranslationRef<string, TMessages>): TranslationSnapshot<TMessages>;
3109
+ translation$<TMessages extends {
3110
+ [key in string]: string;
3111
+ }>(translationRef: TranslationRef<string, TMessages>): Observable<TranslationSnapshot<TMessages>>;
3112
+ };
3113
+ /**
3114
+ * @public
3115
+ */
3116
+ declare const translationApiRef: ApiRef<TranslationApi>;
3117
+
1686
3118
  /**
1687
3119
  * Gets a pre-configured analytics tracker.
1688
3120
  *
@@ -1853,12 +3285,12 @@ declare const NavItemBlueprint: ExtensionBlueprint<{
1853
3285
  kind: "nav-item";
1854
3286
  params: {
1855
3287
  title: string;
1856
- icon: IconComponent$2;
3288
+ icon: IconComponent;
1857
3289
  routeRef: RouteRef<undefined>;
1858
3290
  };
1859
3291
  output: ExtensionDataRef<{
1860
3292
  title: string;
1861
- icon: IconComponent$2;
3293
+ icon: IconComponent;
1862
3294
  routeRef: RouteRef<undefined>;
1863
3295
  }, "core.nav-item.target", {}>;
1864
3296
  inputs: {};
@@ -1867,7 +3299,7 @@ declare const NavItemBlueprint: ExtensionBlueprint<{
1867
3299
  dataRefs: {
1868
3300
  target: ConfigurableExtensionDataRef<{
1869
3301
  title: string;
1870
- icon: IconComponent$2;
3302
+ icon: IconComponent;
1871
3303
  routeRef: RouteRef<undefined>;
1872
3304
  }, "core.nav-item.target", {}>;
1873
3305
  };
@@ -1925,6 +3357,21 @@ declare const RouterBlueprint: ExtensionBlueprint<{
1925
3357
  };
1926
3358
  }>;
1927
3359
 
3360
+ /**
3361
+ * Props for the `SignInPage` component.
3362
+ *
3363
+ * @public
3364
+ */
3365
+ type SignInPageProps = {
3366
+ /**
3367
+ * Set the IdentityApi on successful sign-in. This should only be called once.
3368
+ */
3369
+ onSignInSuccess(identityApi: IdentityApi): void;
3370
+ /**
3371
+ * The children to render.
3372
+ */
3373
+ children?: ReactNode;
3374
+ };
1928
3375
  /**
1929
3376
  * Creates an extension that replaces the sign in page.
1930
3377
  *
@@ -2019,4 +3466,4 @@ declare const SwappableComponentBlueprint: ExtensionBlueprint<{
2019
3466
  };
2020
3467
  }>;
2021
3468
 
2022
- export { type AnalyticsApi, AnalyticsContext, type AnalyticsContextValue, type AnalyticsEvent, type AnalyticsEventAttributes, type AnalyticsImplementation, AnalyticsImplementationBlueprint, type AnalyticsImplementationFactory, type AnalyticsTracker, type AnyExtensionDataRef, type AnyRouteRefParams, ApiBlueprint, type AppNode, type AppNodeEdges, type AppNodeInstance, type AppNodeSpec, AppRootElementBlueprint, AppRootWrapperBlueprint, type AppTree, type AppTreeApi, type ConfigurableExtensionDataRef, type CreateExtensionBlueprintOptions, type CreateExtensionOptions, type CreateFrontendFeatureLoaderOptions, type CreateFrontendModuleOptions, type CreateSwappableComponentOptions, type DialogApi, type DialogApiDialog, ErrorDisplay, type ErrorDisplayProps, type Extension, type ExtensionAttachTo, type ExtensionAttachToSpec, type ExtensionBlueprint, type ExtensionBlueprintDefineParams, type ExtensionBlueprintParameters, type ExtensionBlueprintParams, ExtensionBoundary, type ExtensionBoundaryProps, type ExtensionDataContainer, type ExtensionDataRef, type ExtensionDataRefToValue, type ExtensionDataValue, type ExtensionDefinition, type ExtensionDefinitionAttachTo, type ExtensionDefinitionParameters, type ExtensionFactoryMiddleware, type ExtensionInput, type ExternalRouteRef, type FeatureFlagConfig, type FrontendFeature, type FrontendFeatureLoader, type FrontendModule, type FrontendPlugin, type FrontendPluginInfo, type FrontendPluginInfoOptions, IconBundleBlueprint, type IconComponent, type IconsApi, NavContentBlueprint, type NavContentComponent, type NavContentComponentProps, NavItemBlueprint, NotFoundErrorPage, type NotFoundErrorPageProps, type OverridableExtensionDefinition, type OverridableFrontendPlugin, PageBlueprint, type PluginOptions, type PortableSchema, Progress, type ProgressProps, type ResolvedExtensionInput, type ResolvedExtensionInputs, type RouteFunc, type RouteRef, type RouteResolutionApi, RouterBlueprint, SignInPageBlueprint, type SubRouteRef, SwappableComponentBlueprint, type SwappableComponentRef, type SwappableComponentsApi, ThemeBlueprint, TranslationBlueprint, analyticsApiRef, appTreeApiRef, coreExtensionData, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, createSwappableComponent, dialogApiRef, iconsApiRef, routeResolutionApiRef, swappableComponentsApiRef, useAnalytics, useAppNode, useRouteRef, useRouteRefParams };
3469
+ export { type AlertApi, type AlertMessage, type AnalyticsApi, AnalyticsContext, type AnalyticsContextValue, type AnalyticsEvent, type AnalyticsEventAttributes, type AnalyticsImplementation, AnalyticsImplementationBlueprint, type AnalyticsImplementationFactory, type AnalyticsTracker, type AnyApiFactory, type AnyApiRef, type AnyExtensionDataRef, type AnyRouteRefParams, ApiBlueprint, type ApiFactory, type ApiHolder, type ApiRef, type ApiRefConfig, type AppLanguageApi, type AppNode, type AppNodeEdges, type AppNodeInstance, type AppNodeSpec, AppRootElementBlueprint, AppRootWrapperBlueprint, type AppTheme, type AppThemeApi, type AppTree, type AppTreeApi, type AuthProviderInfo, type AuthRequestOptions, type BackstageIdentityApi, type BackstageIdentityResponse, type BackstageUserIdentity, type ConfigApi, type ConfigurableExtensionDataRef, type CreateExtensionBlueprintOptions, type CreateExtensionOptions, type CreateFrontendFeatureLoaderOptions, type CreateFrontendModuleOptions, type CreateSwappableComponentOptions, type DialogApi, type DialogApiDialog, type DiscoveryApi, type ErrorApi, type ErrorApiError, type ErrorApiErrorContext, ErrorDisplay, type ErrorDisplayProps, type Extension, type ExtensionAttachTo, type ExtensionAttachToSpec, type ExtensionBlueprint, type ExtensionBlueprintDefineParams, type ExtensionBlueprintParameters, type ExtensionBlueprintParams, ExtensionBoundary, type ExtensionBoundaryProps, type ExtensionDataContainer, type ExtensionDataRef, type ExtensionDataRefToValue, type ExtensionDataValue, type ExtensionDefinition, type ExtensionDefinitionAttachTo, type ExtensionDefinitionParameters, type ExtensionFactoryMiddleware, type ExtensionInput, type ExternalRouteRef, type FeatureFlag, type FeatureFlagConfig, FeatureFlagState, type FeatureFlagsApi, type FeatureFlagsSaveOptions, type FetchApi, type FrontendFeature, type FrontendFeatureLoader, type FrontendModule, type FrontendPlugin, type FrontendPluginInfo, type FrontendPluginInfoOptions, IconBundleBlueprint, type IconComponent, type IconsApi, type IdentityApi, NavContentBlueprint, type NavContentComponent, type NavContentComponentProps, NavItemBlueprint, NotFoundErrorPage, type NotFoundErrorPageProps, type OAuthApi, type OAuthRequestApi, type OAuthRequester, type OAuthRequesterOptions, type OAuthScope, type OpenIdConnectApi, type OverridableExtensionDefinition, type OverridableFrontendPlugin, PageBlueprint, type PendingOAuthRequest, type PluginOptions, type PortableSchema, type ProfileInfo, type ProfileInfoApi, Progress, type ProgressProps, type ResolvedExtensionInput, type ResolvedExtensionInputs, type RouteFunc, type RouteRef, type RouteResolutionApi, RouterBlueprint, type SessionApi, SessionState, SignInPageBlueprint, type SignInPageProps, type StorageApi, type StorageValueSnapshot, type SubRouteRef, SwappableComponentBlueprint, type SwappableComponentRef, type SwappableComponentsApi, ThemeBlueprint, type TranslationApi, TranslationBlueprint, type TranslationFunction, type TranslationMessages, type TranslationMessagesOptions, type TranslationRef, type TranslationRefOptions, type TranslationResource, type TranslationResourceOptions, type TranslationSnapshot, type TypesToApiRefs, alertApiRef, analyticsApiRef, appLanguageApiRef, appThemeApiRef, appTreeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, coreExtensionData, createApiFactory, createApiRef, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, createSwappableComponent, createTranslationMessages, createTranslationRef, createTranslationResource, dialogApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, iconsApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, openshiftAuthApiRef, routeResolutionApiRef, storageApiRef, swappableComponentsApiRef, translationApiRef, useAnalytics, useApi, useApiHolder, useAppNode, useRouteRef, useRouteRefParams, useTranslationRef, vmwareCloudAuthApiRef, withApis };