@backstage/core-app-api 0.1.22 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,152 @@
 # @backstage/core-app-api
 
+## 0.2.1
+
+### Patch Changes
+
+- c11ce4f552: Deprecated `Auth0Auth`, pointing to using `OAuth2` directly instead.
+- 9d6503e86c: Switched out usage of deprecated `OAuthRequestApi` types from `@backstage/core-plugin-api`.
+- Updated dependencies
+  - @backstage/core-plugin-api@0.3.1
+  - @backstage/core-components@0.8.1
+
+## 0.2.0
+
+### Minor Changes
+
+- a036b65c2f: **BREAKING CHANGE**
+
+  The app `SignInPage` component has been updated to switch out the `onResult` callback for a new `onSignInSuccess` callback. This is an immediate breaking change without any deprecation period, as it was deemed to be the way of making this change that had the lowest impact.
+
+  The new `onSignInSuccess` callback directly accepts an implementation of an `IdentityApi`, rather than a `SignInResult`. The `SignInPage` from `@backstage/core-component` has been updated to fit this new API, and as long as you pass on `props` directly you should not see any breakage.
+
+  However, if you implement your own custom `SignInPage`, then this will be a breaking change and you need to migrate over to using the new callback. While doing so you can take advantage of the `UserIdentity.fromLegacy` helper from `@backstage/core-components` to make the migration simpler by still using the `SignInResult` type. This helper is also deprecated though and is only provided for immediate migration. Long-term it will be necessary to build the `IdentityApi` using for example `UserIdentity.create` instead.
+
+  The following is an example of how you can migrate existing usage immediately using `UserIdentity.fromLegacy`:
+
+  ```ts
+  onResult(signInResult);
+  // becomes
+  onSignInSuccess(UserIdentity.fromLegacy(signInResult));
+  ```
+
+  The following is an example of how implement the new `onSignInSuccess` callback of the `SignInPage` using `UserIdentity.create`:
+
+  ```ts
+  const identityResponse = await authApi.getBackstageIdentity();
+  // Profile is optional and will be removed, but allows the
+  // synchronous getProfile method of the IdentityApi to be used.
+  const profile = await authApi.getProfile();
+  onSignInSuccess(
+    UserIdentity.create({
+      identity: identityResponse.identity,
+      authApi,
+      profile,
+    }),
+  );
+  ```
+
+### Patch Changes
+
+- cd450844f6: Moved React dependencies to `peerDependencies` and allow both React v16 and v17 to be used.
+- dcd1a0c3f4: Minor improvement to the API reports, by not unpacking arguments directly
+- Updated dependencies
+  - @backstage/core-components@0.8.0
+  - @backstage/core-plugin-api@0.3.0
+  - @backstage/app-defaults@0.1.2
+  - @backstage/version-bridge@0.1.1
+
+## 0.1.24
+
+### Patch Changes
+
+- 0e7f256034: Fixed a bug where `useRouteRef` would fail in situations where relative navigation was needed and the app was is mounted on a sub-path. This would typically show up as a failure to navigate to a tab on an entity page.
+- Updated dependencies
+  - @backstage/core-components@0.7.6
+  - @backstage/theme@0.2.14
+  - @backstage/core-plugin-api@0.2.2
+
+## 0.1.23
+
+### Patch Changes
+
+- bab752e2b3: Change default port of backend from 7000 to 7007.
+
+  This is due to the AirPlay Receiver process occupying port 7000 and preventing local Backstage instances on MacOS to start.
+
+  You can change the port back to 7000 or any other value by providing an `app-config.yaml` with the following values:
+
+  ```
+  backend:
+    listen: 0.0.0.0:7123
+    baseUrl: http://localhost:7123
+  ```
+
+  More information can be found here: https://backstage.io/docs/conf/writing
+
+- 000190de69: The `ApiRegistry` from `@backstage/core-app-api` class has been deprecated and will be removed in a future release. To replace it, we have introduced two new helpers that are exported from `@backstage/test-utils`, namely `TestApiProvider` and `TestApiRegistry`.
+
+  These two new helpers are more tailored for writing tests and development setups, as they allow for partial implementations of each of the APIs.
+
+  When migrating existing code it is typically best to prefer usage of `TestApiProvider` when possible, so for example the following code:
+
+  ```tsx
+  render(
+    <ApiProvider
+      apis={ApiRegistry.from([
+        [identityApiRef, mockIdentityApi as unknown as IdentityApi]
+      ])}
+    >
+      {...}
+    </ApiProvider>
+  )
+  ```
+
+  Would be migrated to this:
+
+  ```tsx
+  render(
+    <TestApiProvider apis={[[identityApiRef, mockIdentityApi]]}>
+      {...}
+    </TestApiProvider>
+  )
+  ```
+
+  In cases where the `ApiProvider` is used in a more standalone way, for example to reuse a set of APIs across multiple tests, the `TestApiRegistry` can be used instead. Note that the `TestApiRegistry` only has a single static factory method, `.from()`, and it is slightly different from the existing `.from()` method on `ApiRegistry` in that it doesn't require the API pairs to be wrapped in an outer array.
+
+  Usage that looks like this:
+
+  ```ts
+  const apis = ApiRegistry.with(
+    identityApiRef,
+    mockIdentityApi as unknown as IdentityApi,
+  ).with(configApiRef, new ConfigReader({}));
+  ```
+
+  OR like this:
+
+  ```ts
+  const apis = ApiRegistry.from([
+    [identityApiRef, mockIdentityApi as unknown as IdentityApi],
+    [configApiRef, new ConfigReader({})],
+  ]);
+  ```
+
+  Would be migrated to this:
+
+  ```ts
+  const apis = TestApiRegistry.from(
+    [identityApiRef, mockIdentityApi],
+    [configApiRef, new ConfigReader({})],
+  );
+  ```
+
+  If your app is still using the `ApiRegistry` to construct the `apis` for `createApp`, we recommend that you move over to use the new method of supplying API factories instead, using `createApiFactory`.
+
+- Updated dependencies
+  - @backstage/core-plugin-api@0.2.1
+  - @backstage/core-components@0.7.5
+
 ## 0.1.22
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode, PropsWithChildren, ComponentType } from 'react';
 import PropTypes from 'prop-types';
-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, ErrorApiError, ErrorApiErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, AuthRequesterOptions, AuthRequester, PendingAuthRequest, StorageApi, StorageValueChange, BackstagePlugin, IconComponent, ExternalRouteRef, PluginOutput, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
+import { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentity, SessionState, OAuthRequestApi, DiscoveryApi, AuthProviderInfo, OAuthApi, SessionApi, AuthRequestOptions, gitlabAuthApiRef, googleAuthApiRef, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, oktaAuthApiRef, auth0AuthApiRef, microsoftAuthApiRef, oneloginAuthApiRef, bitbucketAuthApiRef, atlassianAuthApiRef, AlertApi, AlertMessage, AnalyticsApi, AnalyticsEvent, AppThemeApi, AppTheme, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, OAuthRequesterOptions, OAuthRequester, PendingOAuthRequest, StorageApi, StorageValueChange, IdentityApi, BackstagePlugin, IconComponent, ExternalRouteRef, PluginOutput, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
 import * as _backstage_types from '@backstage/types';
 import { Observable } from '@backstage/types';
 import { AppConfig } from '@backstage/config';
@@ -41,6 +41,7 @@ declare class ApiRegistryBuilder {
  * A registry for utility APIs.
  *
  * @public
+ * @deprecated Will be removed, use {@link @backstage/test-utils#TestApiProvider} or {@link @backstage/test-utils#TestApiRegistry} instead.
  */
 declare class ApiRegistry implements ApiHolder {
     private readonly apis;
@@ -176,9 +177,7 @@ declare type OAuthApiCreateOptions = AuthApiCreateOptions & {
 declare type AuthApiCreateOptions = {
     discoveryApi: DiscoveryApi;
     environment?: string;
-    provider?: AuthProvider & {
-        id: string;
-    };
+    provider?: AuthProviderInfo;
 };
 
 /**
@@ -188,7 +187,7 @@ declare type AuthApiCreateOptions = {
  */
 declare class GithubAuth implements OAuthApi, SessionApi {
     private readonly sessionManager;
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): GithubAuth;
+    static create(options: OAuthApiCreateOptions): GithubAuth;
     /**
      * @deprecated will be made private in the future. Use create method instead.
      */
@@ -208,7 +207,7 @@ declare class GithubAuth implements OAuthApi, SessionApi {
  * @public
  */
 declare class GitlabAuth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof gitlabAuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof gitlabAuthApiRef.T;
 }
 
 /**
@@ -217,7 +216,7 @@ declare class GitlabAuth {
  * @public
  */
 declare class GoogleAuth {
-    static create({ discoveryApi, oauthRequestApi, environment, provider, defaultScopes, }: OAuthApiCreateOptions): typeof googleAuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof googleAuthApiRef.T;
 }
 
 /**
@@ -249,7 +248,7 @@ declare type OAuth2CreateOptions = OAuthApiCreateOptions & {
  * @public
  */
 declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, SessionApi {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, scopeTransform, }: OAuth2CreateOptions): OAuth2;
+    static create(options: OAuth2CreateOptions): OAuth2;
     private readonly sessionManager;
     private readonly scopeTransform;
     /**
@@ -275,7 +274,7 @@ declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, Back
  * @public
  */
 declare class OktaAuth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
 }
 
 /**
@@ -296,7 +295,7 @@ declare type SamlSession = {
  */
 declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionApi {
     private readonly sessionManager;
-    static create({ discoveryApi, environment, provider, }: AuthApiCreateOptions): SamlAuth;
+    static create(options: AuthApiCreateOptions): SamlAuth;
     sessionState$(): Observable<SessionState>;
     /**
      * @deprecated will be made private in the future. Use create method instead.
@@ -312,9 +311,26 @@ declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionA
  * Implements the OAuth flow to Auth0 products.
  *
  * @public
+ * @deprecated Use {@link OAuth2} instead
+ *
+ * @example
+ *
+ * ```ts
+ * OAuth2.create({
+ *   discoveryApi,
+ *   oauthRequestApi,
+ *   provider: {
+ *     id: 'auth0',
+ *     title: 'Auth0',
+ *     icon: () => null,
+ *   },
+ *   defaultScopes: ['openid', 'email', 'profile'],
+ *   environment: configApi.getOptionalString('auth.environment'),
+ * })
+ * ```
  */
 declare class Auth0Auth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof auth0AuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof auth0AuthApiRef.T;
 }
 
 /**
@@ -323,7 +339,7 @@ declare class Auth0Auth {
  * @public
  */
 declare class MicrosoftAuth {
-    static create({ environment, provider, oauthRequestApi, discoveryApi, defaultScopes, }: OAuthApiCreateOptions): typeof microsoftAuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof microsoftAuthApiRef.T;
 }
 
 /**
@@ -334,9 +350,7 @@ declare type OneLoginAuthCreateOptions = {
     discoveryApi: DiscoveryApi;
     oauthRequestApi: OAuthRequestApi;
     environment?: string;
-    provider?: AuthProvider & {
-        id: string;
-    };
+    provider?: AuthProviderInfo;
 };
 /**
  * Implements a OneLogin OAuth flow.
@@ -344,7 +358,7 @@ declare type OneLoginAuthCreateOptions = {
  * @public
  */
 declare class OneLoginAuth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, }: OneLoginAuthCreateOptions): typeof oneloginAuthApiRef.T;
+    static create(options: OneLoginAuthCreateOptions): typeof oneloginAuthApiRef.T;
 }
 
 /**
@@ -368,7 +382,7 @@ declare type BitbucketSession = {
  * @public
  */
 declare class BitbucketAuth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof bitbucketAuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof bitbucketAuthApiRef.T;
 }
 
 /**
@@ -377,7 +391,7 @@ declare class BitbucketAuth {
  * @public
  */
 declare class AtlassianAuth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, }: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T;
+    static create(options: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T;
 }
 
 /**
@@ -431,7 +445,7 @@ declare class UrlPatternDiscovery implements DiscoveryApi {
      * interpolation done for the template is to replace instances of `{{pluginId}}`
      * with the ID of the plugin being requested.
      *
-     * Example pattern: `http://localhost:7000/api/{{ pluginId }}`
+     * Example pattern: `http://localhost:7007/api/{{ pluginId }}`
      */
     static compile(pattern: string): UrlPatternDiscovery;
     private constructor();
@@ -510,9 +524,9 @@ declare class OAuthRequestManager implements OAuthRequestApi {
     private readonly subject;
     private currentRequests;
     private handlerCount;
-    createAuthRequester<T>(options: AuthRequesterOptions<T>): AuthRequester<T>;
+    createAuthRequester<T>(options: OAuthRequesterOptions<T>): OAuthRequester<T>;
     private makeAuthRequest;
-    authRequest$(): Observable<PendingAuthRequest[]>;
+    authRequest$(): Observable<PendingOAuthRequest[]>;
 }
 
 /**
@@ -552,6 +566,7 @@ declare type BootErrorPageProps = {
  * The outcome of signing in on the sign-in page.
  *
  * @public
+ * @deprecated replaced by passing the {@link @backstage/core-plugin-api#IdentityApi} to the {@link SignInPageProps.onSignInSuccess} instead.
  */
 declare type SignInResult = {
     /**
@@ -575,9 +590,9 @@ declare type SignInResult = {
  */
 declare type SignInPageProps = {
     /**
-     * Set the sign-in result for the app. This should only be called once.
+     * Set the IdentityApi on successful sign in. This should only be called once.
      */
-    onResult(result: SignInResult): void;
+    onSignInSuccess(identityApi: IdentityApi): void;
 };
 /**
  * Props for the fallback error boundary.