@backstage/core-app-api 0.2.1 → 0.5.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @backstage/core-app-api
 
+## 0.5.0-next.0
+
+### Minor Changes
+
+- ceebe25391: Removed deprecated `SignInResult` type, which was replaced with the new `onSignInSuccess` callback.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-plugin-api@0.6.0-next.0
+  - @backstage/config@0.1.13-next.0
+
+## 0.4.0
+
+### Minor Changes
+
+- e2eb92c109: Removed previously deprecated `ApiRegistry` export.
+
+### Patch Changes
+
+- 34442cd5cf: Fixed an issue where valid SAML and GitHub sessions would be considered invalid and not be stored.
+
+  Deprecated the `SamlSession` and `GithubSession` types.
+
+- 784d8078ab: Removed direct and transitive MUI dependencies.
+- Updated dependencies
+  - @backstage/config@0.1.12
+  - @backstage/core-plugin-api@0.5.0
+
+## 0.3.1
+
+### Patch Changes
+
+- 4ce51ab0f1: Internal refactor of the `react-use` imports to use `react-use/lib/*` instead.
+- Updated dependencies
+  - @backstage/core-plugin-api@0.4.1
+  - @backstage/core-components@0.8.3
+
+## 0.3.0
+
+### Minor Changes
+
+- a195284c7b: Updated `WebStorageApi` to reflect the `StorageApi` changes in `@backstage/core-plugin-api`.
+- b3605da81c: - Removed deprecated definition `createApp` from `@backstage/core-app-api` which has been replaced by `@backstage/app-defaults#createApp`
+  - Removed deprecated type `BackstagePluginWithAnyOutput`
+  - Removed deprecated constructors for `GithubAuth`, `OAuth2`, and `SamlAuth` as the `create` method should be used instead
+- 68f8b10ccd: - Removed deprecation configuration option `theme` from `AppTheme` of the `AppThemeApi`
+  - Removed reference to `theme` in the `app-defaults` default `AppTheme`
+  - Removed logic in `AppThemeProvider` that creates `ThemeProvider` from `appTheme.theme`
+
+### Patch Changes
+
+- 7927005152: Add `FetchApi` and related `fetchApiRef` which implement fetch, with an added Backstage token header when available.
+- 518ddc00bc: Schema-validate local storage cached session info on load
+- Updated dependencies
+  - @backstage/app-defaults@0.1.3
+  - @backstage/core-plugin-api@0.4.0
+  - @backstage/core-components@0.8.2
+
 ## 0.2.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 import { ReactNode, PropsWithChildren, ComponentType } from 'react';
 import PropTypes from 'prop-types';
-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 { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentityResponse, OAuthRequestApi, DiscoveryApi, AuthProviderInfo, OAuthApi, SessionApi, SessionState, AuthRequestOptions, gitlabAuthApiRef, googleAuthApiRef, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, oktaAuthApiRef, auth0AuthApiRef, microsoftAuthApiRef, oneloginAuthApiRef, bitbucketAuthApiRef, atlassianAuthApiRef, AlertApi, AlertMessage, AnalyticsApi, AnalyticsEvent, AppThemeApi, AppTheme, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, FetchApi, IdentityApi, OAuthRequesterOptions, OAuthRequester, PendingOAuthRequest, StorageApi, StorageValueSnapshot, BackstagePlugin, IconComponent, ExternalRouteRef, 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';
+import { Observable, JsonValue } from '@backstage/types';
+import { Config, AppConfig } from '@backstage/config';
 export { ConfigReader } from '@backstage/config';
-import { createApp as createApp$1 } from '@backstage/app-defaults';
 
 /**
  * Prop types for the ApiProvider component.
@@ -31,45 +30,6 @@ declare const ApiProvider: {
     };
 };
 
-declare type ApiImpl<T = unknown> = readonly [ApiRef<T>, T];
-declare class ApiRegistryBuilder {
-    private apis;
-    add<T, I extends T>(api: ApiRef<T>, impl: I): I;
-    build(): ApiRegistry;
-}
-/**
- * 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;
-    static builder(): ApiRegistryBuilder;
-    /**
-     * Creates a new ApiRegistry with a list of API implementations.
-     *
-     * @param apis - A list of pairs mapping an ApiRef to its respective implementation
-     */
-    static from(apis: ApiImpl[]): ApiRegistry;
-    /**
-     * Creates a new ApiRegistry with a single API implementation.
-     *
-     * @param api - ApiRef for the API to add
-     * @param impl - Implementation of the API to add
-     */
-    static with<T>(api: ApiRef<T>, impl: T): ApiRegistry;
-    constructor(apis: Map<string, unknown>);
-    /**
-     * Returns a new ApiRegistry with the provided API added to the existing ones.
-     *
-     * @param api - ApiRef for the API to add
-     * @param impl - Implementation of the API to add
-     */
-    with<T>(api: ApiRef<T>, impl: T): ApiRegistry;
-    get<T>(api: ApiRef<T>): T | undefined;
-}
-
 /**
  * @public
  */
@@ -135,6 +95,7 @@ declare class ApiFactoryRegistry implements ApiFactoryHolder {
  * Session information for GitHub auth.
  *
  * @public
+ * @deprecated This type is internal and will be removed
  */
 declare type GithubSession = {
     providerInfo: {
@@ -143,23 +104,7 @@ declare type GithubSession = {
         expiresAt?: Date;
     };
     profile: ProfileInfo;
-    backstageIdentity: BackstageIdentity;
-};
-
-declare type GetSessionOptions = {
-    optional?: boolean;
-    instantPopup?: boolean;
-    scopes?: Set<string>;
-};
-/**
- * A sessions manager keeps track of the current session and makes sure that
- * multiple simultaneous requests for sessions with different scope are handled
- * in a correct way.
- */
-declare type SessionManager<T> = {
-    getSession(options: GetSessionOptions): Promise<T | undefined>;
-    removeSession(): Promise<void>;
-    sessionState$(): Observable<SessionState>;
+    backstageIdentity: BackstageIdentityResponse;
 };
 
 /**
@@ -188,15 +133,12 @@ declare type AuthApiCreateOptions = {
 declare class GithubAuth implements OAuthApi, SessionApi {
     private readonly sessionManager;
     static create(options: OAuthApiCreateOptions): GithubAuth;
-    /**
-     * @deprecated will be made private in the future. Use create method instead.
-     */
-    constructor(sessionManager: SessionManager<GithubSession>);
+    private constructor();
     signIn(): Promise<void>;
     signOut(): Promise<void>;
     sessionState$(): Observable<SessionState>;
     getAccessToken(scope?: string, options?: AuthRequestOptions): Promise<string>;
-    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentity | undefined>;
+    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentityResponse | undefined>;
     getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
     static normalizeScope(scope?: string): Set<string>;
 }
@@ -219,22 +161,6 @@ declare class GoogleAuth {
     static create(options: OAuthApiCreateOptions): typeof googleAuthApiRef.T;
 }
 
-/**
- * Session information for generic OAuth2 auth.
- *
- * @public
- */
-declare type OAuth2Session = {
-    providerInfo: {
-        idToken: string;
-        accessToken: string;
-        scopes: Set<string>;
-        expiresAt: Date;
-    };
-    profile: ProfileInfo;
-    backstageIdentity: BackstageIdentity;
-};
-
 /**
  * OAuth2 create options.
  * @public
@@ -251,42 +177,41 @@ declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, Back
     static create(options: OAuth2CreateOptions): OAuth2;
     private readonly sessionManager;
     private readonly scopeTransform;
-    /**
-     * @deprecated will be made private in the future. Use create method instead.
-     */
-    constructor(options: {
-        sessionManager: SessionManager<OAuth2Session>;
-        scopeTransform: (scopes: string[]) => string[];
-    });
+    private constructor();
     signIn(): Promise<void>;
     signOut(): Promise<void>;
     sessionState$(): Observable<SessionState>;
     getAccessToken(scope?: string | string[], options?: AuthRequestOptions): Promise<string>;
     getIdToken(options?: AuthRequestOptions): Promise<string>;
-    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentity | undefined>;
+    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentityResponse | undefined>;
     getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
     private static normalizeScopes;
 }
 
 /**
- * Implements the OAuth flow to Okta products.
+ * Session information for generic OAuth2 auth.
  *
  * @public
  */
-declare class OktaAuth {
-    static create(options: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
-}
+declare type OAuth2Session = {
+    providerInfo: {
+        idToken: string;
+        accessToken: string;
+        scopes: Set<string>;
+        expiresAt: Date;
+    };
+    profile: ProfileInfo;
+    backstageIdentity: BackstageIdentityResponse;
+};
 
 /**
- * Session information for SAML auth.
+ * Implements the OAuth flow to Okta products.
  *
  * @public
  */
-declare type SamlSession = {
-    userId: string;
-    profile: ProfileInfo;
-    backstageIdentity: BackstageIdentity;
-};
+declare class OktaAuth {
+    static create(options: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
+}
 
 /**
  * Implements a general SAML based auth flow.
@@ -297,16 +222,25 @@ declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionA
     private readonly sessionManager;
     static create(options: AuthApiCreateOptions): SamlAuth;
     sessionState$(): Observable<SessionState>;
-    /**
-     * @deprecated will be made private in the future. Use create method instead.
-     */
-    constructor(sessionManager: SessionManager<SamlSession>);
+    private constructor();
     signIn(): Promise<void>;
     signOut(): Promise<void>;
-    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentity | undefined>;
+    getBackstageIdentity(options?: AuthRequestOptions): Promise<BackstageIdentityResponse | undefined>;
     getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
 }
 
+/**
+ * Session information for SAML auth.
+ *
+ * @public
+ * @deprecated This type is internal and will be removed
+ */
+declare type ExportedSamlSession = {
+    userId: string;
+    profile: ProfileInfo;
+    backstageIdentity: BackstageIdentityResponse;
+};
+
 /**
  * Implements the OAuth flow to Auth0 products.
  *
@@ -373,7 +307,7 @@ declare type BitbucketSession = {
         expiresAt?: Date;
     };
     profile: ProfileInfo;
-    backstageIdentity: BackstageIdentity;
+    backstageIdentity: BackstageIdentityResponse;
 };
 
 /**
@@ -511,6 +445,87 @@ declare class LocalStorageFeatureFlags implements FeatureFlagsApi {
     private load;
 }
 
+/**
+ * A middleware that modifies the behavior of an ongoing fetch.
+ *
+ * @public
+ */
+interface FetchMiddleware {
+    /**
+     * Applies this middleware to an inner implementation.
+     *
+     * @param next - The next, inner, implementation, that this middleware shall
+     *               call out to as part of the request cycle.
+     */
+    apply(next: typeof fetch): typeof fetch;
+}
+
+/**
+ * Builds a fetch API, based on the builtin fetch wrapped by a set of optional
+ * middleware implementations that add behaviors.
+ *
+ * @remarks
+ *
+ * The middleware are applied in reverse order, i.e. the last one will be
+ * "closest" to the base implementation. Passing in `[M1, M2, M3]` effectively
+ * leads to `M1(M2(M3(baseImplementation)))`.
+ *
+ * @public
+ */
+declare function createFetchApi(options: {
+    baseImplementation?: typeof fetch | undefined;
+    middleware?: FetchMiddleware | FetchMiddleware[] | undefined;
+}): FetchApi;
+
+/**
+ * A collection of common middlewares for the FetchApi.
+ *
+ * @public
+ */
+declare class FetchMiddlewares {
+    /**
+     * Handles translation from `plugin://` URLs to concrete http(s) URLs based on
+     * the discovery API.
+     *
+     * @remarks
+     *
+     * If the request is for `plugin://catalog/entities?filter=x=y`, the discovery
+     * API will be queried for `'catalog'`. If it returned
+     * `https://backstage.example.net/api/catalog`, the resulting query would be
+     * `https://backstage.example.net/api/catalog/entities?filter=x=y`.
+     *
+     * If the incoming URL protocol was not `plugin`, the request is just passed
+     * through verbatim to the underlying implementation.
+     */
+    static resolvePluginProtocol(options: {
+        discoveryApi: DiscoveryApi;
+    }): FetchMiddleware;
+    /**
+     * Injects a Backstage token header when the user is signed in.
+     *
+     * @remarks
+     *
+     * Per default, an `Authorization: Bearer <token>` is generated. This can be
+     * customized using the `header` option.
+     *
+     * The header injection only happens on allowlisted URLs. Per default, if the
+     * `config` option is passed in, the `backend.baseUrl` is allowlisted, unless
+     * the `urlPrefixAllowlist` option is passed in, in which case it takes
+     * precedence. If you pass in neither config nor an allowlist, the middleware
+     * will have no effect.
+     */
+    static injectIdentityAuth(options: {
+        identityApi: IdentityApi;
+        config?: Config;
+        urlPrefixAllowlist?: string[];
+        header?: {
+            name: string;
+            value: (backstageToken: string) => string;
+        };
+    }): FetchMiddleware;
+    private constructor();
+}
+
 /**
  * The OAuthRequestManager is an implementation of the OAuthRequestApi.
  *
@@ -543,10 +558,11 @@ declare class WebStorage implements StorageApi {
         namespace?: string;
     }): WebStorage;
     get<T>(key: string): T | undefined;
+    snapshot<T extends JsonValue>(key: string): StorageValueSnapshot<T>;
     forBucket(name: string): WebStorage;
     set<T>(key: string, data: T): Promise<void>;
     remove(key: string): Promise<void>;
-    observe$<T>(key: string): Observable<StorageValueChange<T>>;
+    observe$<T>(key: string): Observable<StorageValueSnapshot<T>>;
     private getKeyName;
     private notifyChanges;
     private subscribers;
@@ -562,27 +578,6 @@ declare type BootErrorPageProps = {
     step: 'load-config' | 'load-chunk';
     error: Error;
 };
-/**
- * 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 = {
-    /**
-     * User ID that will be returned by the IdentityApi
-     */
-    userId: string;
-    profile: ProfileInfo;
-    /**
-     * Function used to retrieve an ID token for the signed in user.
-     */
-    getIdToken?: () => Promise<string>;
-    /**
-     * Sign out handler that will be called if the user requests to sign out.
-     */
-    signOut?: () => Promise<void>;
-};
 /**
  * Props for the `SignInPage` component of {@link AppComponents}.
  *
@@ -694,7 +689,7 @@ declare type TargetRouteMap<ExternalRoutes extends {
 };
 /**
  * A function that can bind from external routes of a given plugin, to concrete
- * routes of other plugins. See {@link createApp}.
+ * routes of other plugins. See {@link createSpecializedApp}.
  *
  * @public
  */
@@ -702,28 +697,7 @@ declare type AppRouteBinder = <ExternalRoutes extends {
     [name: string]: ExternalRouteRef;
 }>(externalRoutes: ExternalRoutes, targetRoutes: PartialKeys<TargetRouteMap<ExternalRoutes>, KeysWithType<ExternalRoutes, ExternalRouteRef<any, true>>>) => void;
 /**
- * Internal helper type that represents a plugin with any type of output.
- *
- * @public
- * @remarks
- * @deprecated Will be removed
- *
- * The `type: string` type is there to handle output from newer or older plugin
- * API versions that might not be supported by this version of the app API, but
- * we don't want to break at the type checking level. We only use this more
- * permissive type for the `createApp` options, as we otherwise want to stick
- * to using the type for the outputs that we know about in this version of the
- * app api.
- *
- * TODO(freben): This should be marked internal but that's not supported by the api report generation tools yet
- */
-declare type BackstagePluginWithAnyOutput = Omit<BackstagePlugin<any, any>, 'output'> & {
-    output(): (PluginOutput | {
-        type: string;
-    })[];
-};
-/**
- * The options accepted by {@link createApp}.
+ * The options accepted by {@link createSpecializedApp}.
  *
  * @public
  */
@@ -750,11 +724,14 @@ declare type AppOptions = {
     /**
      * A list of all plugins to include in the app.
      */
-    plugins?: (Omit<BackstagePlugin<any, any>, 'output'> & {
-        output(): (PluginOutput | {
+    plugins?: Array<BackstagePlugin<any, any> & {
+        output?(): Array<{
+            type: 'feature-flag';
+            name: string;
+        } | {
             type: string;
-        })[];
-    })[];
+        }>;
+    }>;
     /**
      * Supply components to the app to override the default ones.
      */
@@ -823,7 +800,7 @@ declare type AppOptions = {
     }): void;
 };
 /**
- * The public API of the output of {@link createApp}.
+ * The public API of the output of {@link createSpecializedApp}.
  *
  * @public
  */
@@ -868,21 +845,19 @@ declare type AppContext = {
     getComponents(): AppComponents;
 };
 
-/**
- * Creates a new Backstage App.
- *
- * @deprecated Use {@link @backstage/app-defaults#createApp} from `@backstage/app-defaults` instead
- * @param options - A set of options for creating the app
- * @public
- */
-declare function createApp(options?: Parameters<typeof createApp$1>[0]): BackstageApp & AppContext;
-
 /**
  * Creates a new Backstage App where the full set of options are required.
  *
  * @public
  * @param options - A set of options for creating the app
  * @returns
+ * @remarks
+ *
+ * You will most likely want to use {@link @backstage/app-defaults#createApp},
+ * however, this low-level API allows you to provide a full set of options,
+ * including your own `components`, `icons`, `defaultApis`, and `themes`. This
+ * is particularly useful if you are not using `@backstage/core-components` or
+ * MUI, as it allows you to avoid those dependencies completely.
  */
 declare function createSpecializedApp(options: AppOptions): BackstageApp;
 
@@ -941,4 +916,4 @@ declare type FeatureFlaggedProps = {
  */
 declare const FeatureFlagged: (props: FeatureFlaggedProps) => JSX.Element;
 
-export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiFactoryScope, ApiProvider, ApiProviderProps, ApiRegistry, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppIcons, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, Auth0Auth, AuthApiCreateOptions, BackstageApp, BackstagePluginWithAnyOutput, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FlatRoutes, FlatRoutesProps, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2CreateOptions, OAuth2Session, OAuthApiCreateOptions, OAuthRequestManager, OktaAuth, OneLoginAuth, OneLoginAuthCreateOptions, SamlAuth, SamlSession, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createApp, createSpecializedApp, defaultConfigLoader };
+export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiFactoryScope, ApiProvider, ApiProviderProps, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppIcons, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, Auth0Auth, AuthApiCreateOptions, BackstageApp, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FetchMiddleware, FetchMiddlewares, FlatRoutes, FlatRoutesProps, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2CreateOptions, OAuth2Session, OAuthApiCreateOptions, OAuthRequestManager, OktaAuth, OneLoginAuth, OneLoginAuthCreateOptions, SamlAuth, ExportedSamlSession as SamlSession, SignInPageProps, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };