@backstage/core-app-api 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @backstage/core-app-api
 
+## 0.1.19
+
+### Patch Changes
+
+- 10615525f3: Switch to use the json and observable types from `@backstage/types`
+- 41c49884d2: Start using the new `@backstage/types` package. Initially, this means using the `Observable` and `Json*` types from there. The types also remain in their old places but deprecated, and will be removed in a future release.
+- 925a967f36: Replace usage of test-utils-core with test-utils
+- 6b615e92c8: Api cleanup, adding `@public` where necessary and tweaking some comments
+- Updated dependencies
+  - @backstage/config@0.1.11
+  - @backstage/theme@0.2.12
+  - @backstage/core-components@0.7.2
+  - @backstage/core-plugin-api@0.1.12
+
 ## 0.1.18
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { PropsWithChildren, ReactNode, ComponentType } from 'react';
 import PropTypes from 'prop-types';
-import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
-import { ApiHolder, ApiRef, ApiFactory, AnyApiRef, ProfileInfo, BackstageIdentity, Observable, 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, ErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, AuthRequesterOptions, AuthRequester, PendingAuthRequest, StorageApi, StorageValueChange, IconComponent, BackstagePlugin, ExternalRouteRef, PluginOutput, AnyApiFactory, RouteRef, SubRouteRef } from '@backstage/core-plugin-api';
+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, ErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, AuthRequesterOptions, AuthRequester, PendingAuthRequest, StorageApi, StorageValueChange, IconComponent, BackstagePlugin, 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';
 export { ConfigReader } from '@backstage/config';
 
@@ -9,8 +10,14 @@ declare type ApiProviderProps = {
     apis: ApiHolder;
     children: ReactNode;
 };
+/**
+ * Provides an {@link @backstage/core-plugin-api#ApiHolder} for consumption in
+ * the React tree.
+ *
+ * @public
+ */
 declare const ApiProvider: {
-    ({ apis, children, }: PropsWithChildren<ApiProviderProps>): JSX.Element;
+    (props: PropsWithChildren<ApiProviderProps>): JSX.Element;
     propTypes: {
         apis: PropTypes.Validator<PropTypes.InferProps<{
             get: PropTypes.Validator<(...args: any[]) => any>;
@@ -25,34 +32,53 @@ declare class ApiRegistryBuilder {
     add<T, I extends T>(api: ApiRef<T>, impl: I): I;
     build(): ApiRegistry;
 }
+/**
+ * A registry for utility APIs.
+ *
+ * @public
+ */
 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
+     * @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
+     * @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
+ */
 declare type ApiFactoryHolder = {
     get<T>(api: ApiRef<T>): ApiFactory<T, T, {
         [key in string]: unknown;
     }> | undefined;
 };
 
+/**
+ * Handles the actual on-demand instantiation and memoization of APIs out of
+ * an {@link ApiFactoryHolder}.
+ *
+ * @public
+ */
 declare class ApiResolver implements ApiHolder {
     private readonly factories;
     /**
@@ -74,6 +100,8 @@ declare type ApiFactoryScope = 'default' | 'app' | 'static';
  *
  * Each scope has an assigned priority, where factories registered with
  * higher priority scopes override ones with lower priority.
+ *
+ * @public
  */
 declare class ApiFactoryRegistry implements ApiFactoryHolder {
     private readonly factories;
@@ -93,6 +121,11 @@ declare class ApiFactoryRegistry implements ApiFactoryHolder {
     getAllApis(): Set<AnyApiRef>;
 }
 
+/**
+ * Session information for GitHub auth.
+ *
+ * @public
+ */
 declare type GithubSession = {
     providerInfo: {
         accessToken: string;
@@ -131,6 +164,11 @@ declare type AuthApiCreateOptions = {
     };
 };
 
+/**
+ * Implements the OAuth flow to GitHub products.
+ *
+ * @public
+ */
 declare class GithubAuth implements OAuthApi, SessionApi {
     private readonly sessionManager;
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): GithubAuth;
@@ -144,14 +182,29 @@ declare class GithubAuth implements OAuthApi, SessionApi {
     static normalizeScope(scope?: string): Set<string>;
 }
 
+/**
+ * Implements the OAuth flow to GitLab products.
+ *
+ * @public
+ */
 declare class GitlabAuth {
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof gitlabAuthApiRef.T;
 }
 
+/**
+ * Implements the OAuth flow to Google products.
+ *
+ * @public
+ */
 declare class GoogleAuth {
     static create({ discoveryApi, oauthRequestApi, environment, provider, defaultScopes, }: OAuthApiCreateOptions): typeof googleAuthApiRef.T;
 }
 
+/**
+ * Session information for generic OAuth2 auth.
+ *
+ * @public
+ */
 declare type OAuth2Session = {
     providerInfo: {
         idToken: string;
@@ -163,18 +216,22 @@ declare type OAuth2Session = {
     backstageIdentity: BackstageIdentity;
 };
 
-declare type Options = {
-    sessionManager: SessionManager<OAuth2Session>;
-    scopeTransform: (scopes: string[]) => string[];
-};
 declare type CreateOptions$1 = OAuthApiCreateOptions & {
     scopeTransform?: (scopes: string[]) => string[];
 };
+/**
+ * Implements a generic OAuth2 flow for auth.
+ *
+ * @public
+ */
 declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, SessionApi {
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, scopeTransform, }: CreateOptions$1): OAuth2;
     private readonly sessionManager;
     private readonly scopeTransform;
-    constructor(options: Options);
+    constructor(options: {
+        sessionManager: SessionManager<OAuth2Session>;
+        scopeTransform: (scopes: string[]) => string[];
+    });
     signIn(): Promise<void>;
     signOut(): Promise<void>;
     sessionState$(): Observable<SessionState>;
@@ -185,16 +242,31 @@ declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, Back
     private static normalizeScopes;
 }
 
+/**
+ * Implements the OAuth flow to Okta products.
+ *
+ * @public
+ */
 declare class OktaAuth {
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof oktaAuthApiRef.T;
 }
 
+/**
+ * Session information for SAML auth.
+ *
+ * @public
+ */
 declare type SamlSession = {
     userId: string;
     profile: ProfileInfo;
     backstageIdentity: BackstageIdentity;
 };
 
+/**
+ * Implements a general SAML based auth flow.
+ *
+ * @public
+ */
 declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionApi {
     private readonly sessionManager;
     static create({ discoveryApi, environment, provider, }: AuthApiCreateOptions): SamlAuth;
@@ -206,10 +278,20 @@ declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionA
     getProfile(options?: AuthRequestOptions): Promise<ProfileInfo | undefined>;
 }
 
+/**
+ * Implements the OAuth flow to Auth0 products.
+ *
+ * @public
+ */
 declare class Auth0Auth {
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof auth0AuthApiRef.T;
 }
 
+/**
+ * Implements the OAuth flow to Microsoft products.
+ *
+ * @public
+ */
 declare class MicrosoftAuth {
     static create({ environment, provider, oauthRequestApi, discoveryApi, defaultScopes, }: OAuthApiCreateOptions): typeof microsoftAuthApiRef.T;
 }
@@ -222,10 +304,20 @@ declare type CreateOptions = {
         id: string;
     };
 };
+/**
+ * Implements a OneLogin OAuth flow.
+ *
+ * @public
+ */
 declare class OneLoginAuth {
     static create({ discoveryApi, environment, provider, oauthRequestApi, }: CreateOptions): typeof oneloginAuthApiRef.T;
 }
 
+/**
+ * Session information for Bitbucket auth.
+ *
+ * @public
+ */
 declare type BitbucketSession = {
     providerInfo: {
         accessToken: string;
@@ -236,16 +328,28 @@ declare type BitbucketSession = {
     backstageIdentity: BackstageIdentity;
 };
 
+/**
+ * Implements the OAuth flow to Bitbucket products.
+ *
+ * @public
+ */
 declare class BitbucketAuth {
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): typeof bitbucketAuthApiRef.T;
 }
 
+/**
+ * Implements the OAuth flow to Atlassian products.
+ *
+ * @public
+ */
 declare class AtlassianAuth {
     static create({ discoveryApi, environment, provider, oauthRequestApi, }: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T;
 }
 
 /**
  * Base implementation for the AlertApi that simply forwards alerts to consumers.
+ *
+ * @public
  */
 declare class AlertApiForwarder implements AlertApi {
     private readonly subject;
@@ -255,11 +359,19 @@ declare class AlertApiForwarder implements AlertApi {
 
 /**
  * Base implementation for the AnalyticsApi that does nothing.
+ *
+ * @public
  */
 declare class NoOpAnalyticsApi implements AnalyticsApi {
     captureEvent(_event: AnalyticsEvent): void;
 }
 
+/**
+ * Exposes the themes installed in the app, and permits switching the currently
+ * active theme.
+ *
+ * @public
+ */
 declare class AppThemeSelector implements AppThemeApi {
     private readonly themes;
     static createWithStorage(themes: AppTheme[]): AppThemeSelector;
@@ -275,6 +387,8 @@ declare class AppThemeSelector implements AppThemeApi {
 /**
  * UrlPatternDiscovery is a lightweight DiscoveryApi implementation.
  * It uses a single template string to construct URLs for each plugin.
+ *
+ * @public
  */
 declare class UrlPatternDiscovery implements DiscoveryApi {
     private readonly parts;
@@ -293,13 +407,15 @@ declare class UrlPatternDiscovery implements DiscoveryApi {
 /**
  * Decorates an ErrorApi by also forwarding error messages
  * to the alertApi with an 'error' severity.
+ *
+ * @public
  */
 declare class ErrorAlerter implements ErrorApi {
     private readonly alertApi;
     private readonly errorApi;
     constructor(alertApi: AlertApi, errorApi: ErrorApi);
     post(error: Error, context?: ErrorContext): void;
-    error$(): _backstage_core_plugin_api.Observable<{
+    error$(): _backstage_types.Observable<{
         error: {
             name: string;
             message: string;
@@ -311,6 +427,8 @@ declare class ErrorAlerter implements ErrorApi {
 
 /**
  * Base implementation for the ErrorApi that simply forwards errors to consumers.
+ *
+ * @public
  */
 declare class ErrorApiForwarder implements ErrorApi {
     private readonly subject;
@@ -321,6 +439,11 @@ declare class ErrorApiForwarder implements ErrorApi {
     }>;
 }
 
+/**
+ * Utility class that helps with error forwarding.
+ *
+ * @public
+ */
 declare class UnhandledErrorForwarder {
     /**
      * Add event listener, such that unhandled errors can be forwarded using an given `ErrorApi` instance
@@ -329,7 +452,10 @@ declare class UnhandledErrorForwarder {
 }
 
 /**
- * Create the FeatureFlags implementation based on the API.
+ * A feature flags implementation that stores the flags in the browser's local
+ * storage.
+ *
+ * @public
  */
 declare class LocalStorageFeatureFlags implements FeatureFlagsApi {
     private registeredFeatureFlags;
@@ -347,6 +473,8 @@ declare class LocalStorageFeatureFlags implements FeatureFlagsApi {
  * The purpose of this class and the API is to read a stream of incoming requests
  * of OAuth access tokens from different providers with varying scope, and funnel
  * them all together into a single request for each OAuth provider.
+ *
+ * @public
  */
 declare class OAuthRequestManager implements OAuthRequestApi {
     private readonly subject;
@@ -357,15 +485,19 @@ declare class OAuthRequestManager implements OAuthRequestApi {
     authRequest$(): Observable<PendingAuthRequest[]>;
 }
 
-declare type CreateStorageApiOptions = {
-    errorApi: ErrorApi;
-    namespace?: string;
-};
+/**
+ * An implementation of the storage API, that uses the browser's local storage.
+ *
+ * @public
+ */
 declare class WebStorage implements StorageApi {
     private readonly namespace;
     private readonly errorApi;
     constructor(namespace: string, errorApi: ErrorApi);
-    static create(options: CreateStorageApiOptions): WebStorage;
+    static create(options: {
+        errorApi: ErrorApi;
+        namespace?: string;
+    }): WebStorage;
     get<T>(key: string): T | undefined;
     forBucket(name: string): WebStorage;
     set<T>(key: string, data: T): Promise<void>;
@@ -382,10 +514,20 @@ declare type AppIcons = {
     [key in AppIconsKey]: IconComponent;
 };
 
+/**
+ * Props for the `BootErrorPage` component of {@link AppComponents}.
+ *
+ * @public
+ */
 declare type BootErrorPageProps = {
     step: 'load-config' | 'load-chunk';
     error: Error;
 };
+/**
+ * The outcome of signing in on the sign-in page.
+ *
+ * @public
+ */
 declare type SignInResult = {
     /**
      * User ID that will be returned by the IdentityApi
@@ -401,17 +543,32 @@ declare type SignInResult = {
      */
     signOut?: () => Promise<void>;
 };
+/**
+ * Props for the `SignInPage` component of {@link AppComponents}.
+ *
+ * @public
+ */
 declare type SignInPageProps = {
     /**
      * Set the sign-in result for the app. This should only be called once.
      */
     onResult(result: SignInResult): void;
 };
+/**
+ * Props for the fallback error boundary.
+ *
+ * @public
+ */
 declare type ErrorBoundaryFallbackProps = {
     plugin?: BackstagePlugin;
     error: Error;
     resetError: () => void;
 };
+/**
+ * A set of replaceable core components that are part of every Backstage app.
+ *
+ * @public
+ */
 declare type AppComponents = {
     NotFoundErrorPage: ComponentType<{}>;
     BootErrorPage: ComponentType<BootErrorPageProps>;
@@ -435,6 +592,8 @@ declare type AppComponents = {
  *
  * If multiple config objects are returned in the array, values in the earlier configs
  * will override later ones.
+ *
+ * @public
  */
 declare type AppConfigLoader = () => Promise<AppConfig[]>;
 /**
@@ -459,15 +618,40 @@ declare type TargetRouteMap<ExternalRoutes extends {
 }> = {
     [name in keyof ExternalRoutes]: ExternalRoutes[name] extends ExternalRouteRef<infer Params, any> ? RouteRef<Params> | SubRouteRef<Params> : never;
 };
+/**
+ * A function that can bind from external routes of a given plugin, to concrete
+ * routes of other plugins. See {@link createApp}.
+ *
+ * @public
+ */
 declare type AppRouteBinder = <ExternalRoutes extends {
     [name: string]: ExternalRouteRef;
 }>(externalRoutes: ExternalRoutes, targetRoutes: PartialKeys<TargetRouteMap<ExternalRoutes>, KeysWithType<ExternalRoutes, ExternalRouteRef<any, true>>>) => void;
-declare type UnknownPluginOutput = {
-    type: string;
-};
+/**
+ * Internal helper type that represents a plugin with any type of output.
+ *
+ * @public
+ * @remarks
+ *
+ * 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 | UnknownPluginOutput)[];
+    output(): (PluginOutput | {
+        type: string;
+    })[];
 };
+/**
+ * The options accepted by {@link createApp}.
+ *
+ * @public
+ */
 declare type AppOptions = {
     /**
      * A collection of ApiFactories to register in the application to either
@@ -543,6 +727,11 @@ declare type AppOptions = {
         bind: AppRouteBinder;
     }): void;
 };
+/**
+ * The public API of the output of {@link createApp}.
+ *
+ * @public
+ */
 declare type BackstageApp = {
     /**
      * Returns all plugins registered for the app.
@@ -563,6 +752,12 @@ declare type BackstageApp = {
      */
     getRouter(): ComponentType<{}>;
 };
+/**
+ * The central context providing runtime app specific state that plugin views
+ * want to consume.
+ *
+ * @public
+ */
 declare type AppContext = {
     /**
      * Get a list of all plugins that are installed in the app.
@@ -620,18 +815,43 @@ declare class PrivateAppImpl implements BackstageApp {
  * which can be rewritten at runtime to contain an additional JSON config object.
  * If runtime config is present, it will be placed first in the config array, overriding
  * other config values.
+ *
+ * @public
  */
 declare const defaultConfigLoader: AppConfigLoader;
 /**
  * Creates a new Backstage App.
+ *
+ * @public
  */
 declare function createApp(options?: AppOptions): PrivateAppImpl;
 
+/**
+ * Props for the {@link FlatRoutes} component.
+ *
+ * @public
+ */
 declare type FlatRoutesProps = {
     children: ReactNode;
 };
+/**
+ * A wrapper around a set of routes.
+ *
+ * @remarks
+ *
+ * The root of the routing hierarchy in your app should use this component,
+ * instead of the one from `react-router-dom`. This ensures that all of the
+ * plugin route and utility API wiring happens under the hood.
+ *
+ * @public
+ */
 declare const FlatRoutes: (props: FlatRoutesProps) => JSX.Element | null;
 
+/**
+ * Props for the {@link FeatureFlagged} component.
+ *
+ * @public
+ */
 declare type FeatureFlaggedProps = {
     children: ReactNode;
 } & ({
@@ -639,6 +859,12 @@ declare type FeatureFlaggedProps = {
 } | {
     without: string;
 });
+/**
+ * Enables or disables rendering of its children based on the state of a given
+ * feature flag.
+ *
+ * @public
+ */
 declare const FeatureFlagged: (props: FeatureFlaggedProps) => JSX.Element;
 
-export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiProvider, ApiRegistry, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, Auth0Auth, BackstageApp, BackstagePluginWithAnyOutput, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FlatRoutes, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2Session, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createApp, defaultConfigLoader };
+export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiProvider, ApiRegistry, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, Auth0Auth, BackstageApp, BackstagePluginWithAnyOutput, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FlatRoutes, FlatRoutesProps, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2Session, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createApp, defaultConfigLoader };

package/dist/index.esm.js

@@ -49,11 +49,9 @@ class ApiAggregator {
 }
 
 const ApiContext = createVersionedContext("api-context");
-const ApiProvider = ({
-  apis,
-  children
-}) => {
+const ApiProvider = (props) => {
   var _a;
+  const {apis, children} = props;
   const parentHolder = (_a = useContext(ApiContext)) == null ? void 0 : _a.atVersion(1);
   const holder = parentHolder ? new ApiAggregator(apis, parentHolder) : apis;
   return /* @__PURE__ */ React.createElement(ApiContext.Provider, {