@backstage/core-app-api 0.1.19 → 0.1.23

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # @backstage/core-app-api
 
+## 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
+
+- Reverted the `createApp` TypeScript type to match the one before version `0.1.21`, as it was an accidental breaking change.
+
+## 0.1.21
+
+### Patch Changes
+
+- 0b1de52732: Migrated to using new `ErrorApiError` and `ErrorApiErrorContext` names.
+- ecd1fcb80a: Deprecated the `BackstagePluginWithAnyOutput` type.
+- 32bfbafb0f: Start exporting and marking several types as public to address errors in the API report.
+- 014cbf8cb9: The `createApp` function from `@backstage/core-app-api` has been deprecated, with two new options being provided as a replacement.
+
+  The first and most commonly used one is `createApp` from the new `@backstage/app-defaults` package, which behaves just like the existing `createApp`. In the future this method is likely to be expanded to add more APIs and other pieces into the default setup, for example the Utility APIs from `@backstage/integration-react`.
+
+  The other option that we now provide is to use `createSpecializedApp` from `@backstage/core-app-api`. This is a more low-level API where you need to provide a full set of options, including your own `components`, `icons`, `defaultApis`, and `themes`. The `createSpecializedApp` way of creating an app is particularly useful if you are not using `@backstage/core-components` or MUI, as it allows you to avoid those dependencies completely.
+
+- 475edb5bc5: move the BehaviorSubject init into the constructor
+- Updated dependencies
+  - @backstage/core-components@0.7.4
+  - @backstage/core-plugin-api@0.2.0
+  - @backstage/app-defaults@0.1.1
+
+## 0.1.20
+
+### Patch Changes
+
+- 78c512ce8f: I have added default icons for the catalog, scaffolder, techdocs, and search.
+- 8b4284cd5c: Improve API documentation for @backstage/core-plugin-api
+- Updated dependencies
+  - @backstage/core-components@0.7.3
+  - @backstage/theme@0.2.13
+  - @backstage/core-plugin-api@0.1.13
+
 ## 0.1.19
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,11 +1,16 @@
-import { PropsWithChildren, ReactNode, ComponentType } from 'react';
+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, 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, ErrorApiError, ErrorApiErrorContext, FeatureFlagsApi, FeatureFlag, FeatureFlagsSaveOptions, AuthRequesterOptions, AuthRequester, PendingAuthRequest, StorageApi, StorageValueChange, 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';
 export { ConfigReader } from '@backstage/config';
+import { createApp as createApp$1 } from '@backstage/app-defaults';
 
+/**
+ * Prop types for the ApiProvider component.
+ * @public
+ */
 declare type ApiProviderProps = {
     apis: ApiHolder;
     children: ReactNode;
@@ -36,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;
@@ -93,6 +99,10 @@ declare class ApiResolver implements ApiHolder {
     private loadDeps;
 }
 
+/**
+ * Scope type when registering API factories.
+ * @public
+ */
 declare type ApiFactoryScope = 'default' | 'app' | 'static';
 /**
  * ApiFactoryRegistry is an ApiFactoryHolder implementation that enables
@@ -152,10 +162,18 @@ declare type SessionManager<T> = {
     sessionState$(): Observable<SessionState>;
 };
 
+/**
+ * Create options for OAuth APIs.
+ * @public
+ */
 declare type OAuthApiCreateOptions = AuthApiCreateOptions & {
     oauthRequestApi: OAuthRequestApi;
     defaultScopes?: string[];
 };
+/**
+ * Generic create options for auth APIs.
+ * @public
+ */
 declare type AuthApiCreateOptions = {
     discoveryApi: DiscoveryApi;
     environment?: string;
@@ -172,6 +190,9 @@ declare type AuthApiCreateOptions = {
 declare class GithubAuth implements OAuthApi, SessionApi {
     private readonly sessionManager;
     static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, }: OAuthApiCreateOptions): GithubAuth;
+    /**
+     * @deprecated will be made private in the future. Use create method instead.
+     */
     constructor(sessionManager: SessionManager<GithubSession>);
     signIn(): Promise<void>;
     signOut(): Promise<void>;
@@ -216,7 +237,11 @@ declare type OAuth2Session = {
     backstageIdentity: BackstageIdentity;
 };
 
-declare type CreateOptions$1 = OAuthApiCreateOptions & {
+/**
+ * OAuth2 create options.
+ * @public
+ */
+declare type OAuth2CreateOptions = OAuthApiCreateOptions & {
     scopeTransform?: (scopes: string[]) => string[];
 };
 /**
@@ -225,9 +250,12 @@ declare type CreateOptions$1 = OAuthApiCreateOptions & {
  * @public
  */
 declare class OAuth2 implements OAuthApi, OpenIdConnectApi, ProfileInfoApi, BackstageIdentityApi, SessionApi {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, scopeTransform, }: CreateOptions$1): OAuth2;
+    static create({ discoveryApi, environment, provider, oauthRequestApi, defaultScopes, scopeTransform, }: 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[];
@@ -271,6 +299,9 @@ declare class SamlAuth implements ProfileInfoApi, BackstageIdentityApi, SessionA
     private readonly sessionManager;
     static create({ discoveryApi, environment, provider, }: AuthApiCreateOptions): SamlAuth;
     sessionState$(): Observable<SessionState>;
+    /**
+     * @deprecated will be made private in the future. Use create method instead.
+     */
     constructor(sessionManager: SessionManager<SamlSession>);
     signIn(): Promise<void>;
     signOut(): Promise<void>;
@@ -296,7 +327,11 @@ declare class MicrosoftAuth {
     static create({ environment, provider, oauthRequestApi, discoveryApi, defaultScopes, }: OAuthApiCreateOptions): typeof microsoftAuthApiRef.T;
 }
 
-declare type CreateOptions = {
+/**
+ * OneLogin auth provider create options.
+ * @public
+ */
+declare type OneLoginAuthCreateOptions = {
     discoveryApi: DiscoveryApi;
     oauthRequestApi: OAuthRequestApi;
     environment?: string;
@@ -310,7 +345,7 @@ declare type CreateOptions = {
  * @public
  */
 declare class OneLoginAuth {
-    static create({ discoveryApi, environment, provider, oauthRequestApi, }: CreateOptions): typeof oneloginAuthApiRef.T;
+    static create({ discoveryApi, environment, provider, oauthRequestApi, }: OneLoginAuthCreateOptions): typeof oneloginAuthApiRef.T;
 }
 
 /**
@@ -397,7 +432,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();
@@ -414,14 +449,10 @@ declare class ErrorAlerter implements ErrorApi {
     private readonly alertApi;
     private readonly errorApi;
     constructor(alertApi: AlertApi, errorApi: ErrorApi);
-    post(error: Error, context?: ErrorContext): void;
+    post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
     error$(): _backstage_types.Observable<{
-        error: {
-            name: string;
-            message: string;
-            stack?: string | undefined;
-        };
-        context?: ErrorContext | undefined;
+        error: ErrorApiError;
+        context?: ErrorApiErrorContext | undefined;
     }>;
 }
 
@@ -432,10 +463,10 @@ declare class ErrorAlerter implements ErrorApi {
  */
 declare class ErrorApiForwarder implements ErrorApi {
     private readonly subject;
-    post(error: Error, context?: ErrorContext): void;
+    post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
     error$(): Observable<{
         error: Error;
-        context?: ErrorContext;
+        context?: ErrorApiErrorContext;
     }>;
 }
 
@@ -448,7 +479,7 @@ declare class UnhandledErrorForwarder {
     /**
      * Add event listener, such that unhandled errors can be forwarded using an given `ErrorApi` instance
      */
-    static forward(errorApi: ErrorApi, errorContext: ErrorContext): void;
+    static forward(errorApi: ErrorApi, errorContext: ErrorApiErrorContext): void;
 }
 
 /**
@@ -509,11 +540,6 @@ declare class WebStorage implements StorageApi {
     private readonly observable;
 }
 
-declare type AppIconsKey = 'brokenImage' | 'catalog' | 'chat' | 'dashboard' | 'docs' | 'email' | 'github' | 'group' | 'help' | 'kind:api' | 'kind:component' | 'kind:domain' | 'kind:group' | 'kind:location' | 'kind:system' | 'kind:user' | 'user' | 'warning';
-declare type AppIcons = {
-    [key in AppIconsKey]: IconComponent;
-};
-
 /**
  * Props for the `BootErrorPage` component of {@link AppComponents}.
  *
@@ -575,7 +601,7 @@ declare type AppComponents = {
     Progress: ComponentType<{}>;
     Router: ComponentType<{}>;
     ErrorBoundaryFallback: ComponentType<ErrorBoundaryFallbackProps>;
-    ThemeProvider: ComponentType<{}>;
+    ThemeProvider?: ComponentType<{}>;
     /**
      * An optional sign-in page that will be rendered instead of the AppRouter at startup.
      *
@@ -587,6 +613,34 @@ declare type AppComponents = {
      */
     SignInPage?: ComponentType<SignInPageProps>;
 };
+/**
+ * A set of well-known icons that should be available within an app.
+ *
+ * @public
+ */
+declare type AppIcons = {
+    'kind:api': IconComponent;
+    'kind:component': IconComponent;
+    'kind:domain': IconComponent;
+    'kind:group': IconComponent;
+    'kind:location': IconComponent;
+    'kind:system': IconComponent;
+    'kind:user': IconComponent;
+    brokenImage: IconComponent;
+    catalog: IconComponent;
+    chat: IconComponent;
+    dashboard: IconComponent;
+    docs: IconComponent;
+    email: IconComponent;
+    github: IconComponent;
+    group: IconComponent;
+    help: IconComponent;
+    scaffolder: IconComponent;
+    search: IconComponent;
+    techdocs: IconComponent;
+    user: IconComponent;
+    warning: IconComponent;
+};
 /**
  * A function that loads in the App config that will be accessible via the ConfigApi.
  *
@@ -598,6 +652,8 @@ declare type AppComponents = {
 declare type AppConfigLoader = () => Promise<AppConfig[]>;
 /**
  * Extracts a union of the keys in a map whose value extends the given type
+ *
+ * @ignore
  */
 declare type KeysWithType<Obj extends {
     [key in string]: any;
@@ -606,12 +662,16 @@ declare type KeysWithType<Obj extends {
 }[keyof Obj];
 /**
  * Takes a map Map required values and makes all keys matching Keys optional
+ *
+ * @ignore
  */
 declare type PartialKeys<Map extends {
     [name in string]: any;
 }, Keys extends keyof Map> = Partial<Pick<Map, Keys>> & Required<Omit<Map, Keys>>;
 /**
  * Creates a map of target routes with matching parameters based on a map of external routes.
+ *
+ * @ignore
  */
 declare type TargetRouteMap<ExternalRoutes extends {
     [name: string]: ExternalRouteRef;
@@ -632,6 +692,7 @@ declare type AppRouteBinder = <ExternalRoutes extends {
  *
  * @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
@@ -655,23 +716,35 @@ declare type BackstagePluginWithAnyOutput = Omit<BackstagePlugin<any, any>, 'out
 declare type AppOptions = {
     /**
      * A collection of ApiFactories to register in the application to either
-     * add add new ones, or override factories provided by default or by plugins.
+     * add new ones, or override factories provided by default or by plugins.
      */
     apis?: Iterable<AnyApiFactory>;
+    /**
+     * A collection of ApiFactories to register in the application as default APIs.
+     * Theses APIs can not be overridden by plugin factories, but can be overridden
+     * by plugin APIs provided through the
+     * A collection of ApiFactories to register in the application to either
+     * add new ones, or override factories provided by default or by plugins.
+     */
+    defaultApis?: Iterable<AnyApiFactory>;
     /**
      * Supply icons to override the default ones.
      */
-    icons?: Partial<AppIcons> & {
+    icons: AppIcons & {
         [key in string]: IconComponent;
     };
     /**
      * A list of all plugins to include in the app.
      */
-    plugins?: BackstagePluginWithAnyOutput[];
+    plugins?: (Omit<BackstagePlugin<any, any>, 'output'> & {
+        output(): (PluginOutput | {
+            type: string;
+        })[];
+    })[];
     /**
      * Supply components to the app to override the default ones.
      */
-    components?: Partial<AppComponents>;
+    components: AppComponents;
     /**
      * Themes provided as a part of the app. By default two themes are included, one
      * light variant of the default backstage theme, and one dark.
@@ -683,18 +756,26 @@ declare type AppOptions = {
      *   id: 'light',
      *   title: 'Light Theme',
      *   variant: 'light',
-     *   theme: lightTheme,
      *   icon: <LightIcon />,
+     *   Provider: ({ children }) => (
+     *     <ThemeProvider theme={lightTheme}>
+     *       <CssBaseline>{children}</CssBaseline>
+     *     </ThemeProvider>
+     *   ),
      * }, {
      *   id: 'dark',
      *   title: 'Dark Theme',
      *   variant: 'dark',
-     *   theme: darkTheme,
      *   icon: <DarkIcon />,
+     *   Provider: ({ children }) => (
+     *     <ThemeProvider theme={darkTheme}>
+     *       <CssBaseline>{children}</CssBaseline>
+     *     </ThemeProvider>
+     *   ),
      * }]
      * ```
      */
-    themes?: AppTheme[];
+    themes: (Partial<AppTheme> & Omit<AppTheme, 'theme'>)[];
     /**
      * A function that loads in App configuration that will be accessible via
      * the ConfigApi.
@@ -773,38 +854,23 @@ declare type AppContext = {
     getComponents(): AppComponents;
 };
 
-declare type FullAppOptions = {
-    apis: Iterable<AnyApiFactory>;
-    icons: NonNullable<AppOptions['icons']>;
-    plugins: BackstagePlugin<any, any>[];
-    components: AppComponents;
-    themes: AppTheme[];
-    configLoader?: AppConfigLoader;
-    defaultApis: Iterable<AnyApiFactory>;
-    bindRoutes?: AppOptions['bindRoutes'];
-};
-declare class PrivateAppImpl implements BackstageApp {
-    private apiHolder?;
-    private configApi?;
-    private readonly apis;
-    private readonly icons;
-    private readonly plugins;
-    private readonly components;
-    private readonly themes;
-    private readonly configLoader?;
-    private readonly defaultApis;
-    private readonly bindRoutes;
-    private readonly identityApi;
-    private readonly apiFactoryRegistry;
-    constructor(options: FullAppOptions);
-    getPlugins(): BackstagePlugin<any, any>[];
-    getSystemIcon(key: string): IconComponent | undefined;
-    getComponents(): AppComponents;
-    getProvider(): ComponentType<{}>;
-    getRouter(): ComponentType<{}>;
-    private getApiHolder;
-    private verifyPlugins;
-}
+/**
+ * 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
+ */
+declare function createSpecializedApp(options: AppOptions): BackstageApp;
 
 /**
  * The default config loader, which expects that config is available at compile-time
@@ -819,12 +885,6 @@ declare class PrivateAppImpl implements BackstageApp {
  * @public
  */
 declare const defaultConfigLoader: AppConfigLoader;
-/**
- * Creates a new Backstage App.
- *
- * @public
- */
-declare function createApp(options?: AppOptions): PrivateAppImpl;
 
 /**
  * Props for the {@link FlatRoutes} component.
@@ -867,4 +927,4 @@ declare type FeatureFlaggedProps = {
  */
 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, FlatRoutesProps, GithubAuth, GithubSession, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2Session, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, SignInPageProps, SignInResult, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createApp, defaultConfigLoader };
+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 };