@backstage/core-app-api 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @backstage/core-app-api
 
+## 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
+
+- 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

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, 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, 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, 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: {
@@ -146,22 +107,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
@@ -177,9 +122,7 @@ declare type OAuthApiCreateOptions = AuthApiCreateOptions & {
 declare type AuthApiCreateOptions = {
     discoveryApi: DiscoveryApi;
     environment?: string;
-    provider?: AuthProvider & {
-        id: string;
-    };
+    provider?: AuthProviderInfo;
 };
 
 /**
@@ -190,10 +133,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>;
@@ -221,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
@@ -253,13 +177,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>;
@@ -271,24 +189,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.
@@ -299,20 +222,46 @@ 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
+ * @deprecated This type is internal and will be removed
+ */
+declare type ExportedSamlSession = {
+    userId: string;
+    profile: ProfileInfo;
+    backstageIdentity: BackstageIdentity;
+};
+
 /**
  * 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(options: OAuthApiCreateOptions): typeof auth0AuthApiRef.T;
@@ -335,9 +284,7 @@ declare type OneLoginAuthCreateOptions = {
     discoveryApi: DiscoveryApi;
     oauthRequestApi: OAuthRequestApi;
     environment?: string;
-    provider?: AuthProvider & {
-        id: string;
-    };
+    provider?: AuthProviderInfo;
 };
 /**
  * Implements a OneLogin OAuth flow.
@@ -498,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.
  *
@@ -511,9 +539,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[]>;
 }
 
 /**
@@ -530,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;
@@ -681,7 +710,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
  */
@@ -689,28 +718,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
  */
@@ -737,11 +745,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.
      */
@@ -810,7 +821,7 @@ declare type AppOptions = {
     }): void;
 };
 /**
- * The public API of the output of {@link createApp}.
+ * The public API of the output of {@link createSpecializedApp}.
  *
  * @public
  */
@@ -855,21 +866,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;
 
@@ -928,4 +937,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, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };