@backstage/core-app-api 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @backstage/core-app-api
 
+## 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, BackstageIdentity, 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, PluginOutput, 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.
@@ -146,22 +145,6 @@ declare type GithubSession = {
     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>;
-};
-
 /**
  * Create options for OAuth APIs.
  * @public
@@ -188,10 +171,7 @@ 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>;
@@ -219,22 +199,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,13 +215,7 @@ 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>;
@@ -269,24 +227,29 @@ declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, Back
 }
 
 /**
- * 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: BackstageIdentity;
+};
 
 /**
- * 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 +260,24 @@ 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>;
     getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
 }
 
+/**
+ * Session information for SAML auth.
+ *
+ * @public
+ */
+declare type SamlSession = {
+    userId: string;
+    profile: ProfileInfo;
+    backstageIdentity: BackstageIdentity;
+};
+
 /**
  * Implements the OAuth flow to Auth0 products.
  *
@@ -511,6 +482,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 +595,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;
@@ -694,7 +747,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 +755,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
  */
@@ -823,7 +855,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 +900,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 +971,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, ApiRegistry, 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, SamlSession, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };