From c415e83bb35ceb87f1d49a3c01ee82a51c0b7b45 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sun, 5 Sep 2021 14:15:15 +0200
Subject: [PATCH] integration-react: docs and API report fixups

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/integration-react/api-report.md      | 32 ++++++++++++-------
 packages/integration-react/src/api/ScmAuth.ts | 24 ++++++++++++++
 .../integration-react/src/api/ScmAuthApi.ts   |  9 ++++++
 3 files changed, 53 insertions(+), 12 deletions(-)

diff --git a/packages/integration-react/api-report.md b/packages/integration-react/api-report.md
index 8b7b3717a3..b7feb6b6a9 100644
--- a/packages/integration-react/api-report.md
+++ b/packages/integration-react/api-report.md
@@ -5,16 +5,32 @@
 ```ts
 /// <reference types="react" />
 
+import { ApiFactory } from '@backstage/core-plugin-api';
 import { ApiRef } from '@backstage/core-plugin-api';
 import { AuthRequestOptions } from '@backstage/core-plugin-api';
+import { BackstageIdentityApi } from '@backstage/core-plugin-api';
 import { Config } from '@backstage/config';
 import { OAuthApi } from '@backstage/core-plugin-api';
+import { OpenIdConnectApi } from '@backstage/core-plugin-api';
+import { ProfileInfoApi } from '@backstage/core-plugin-api';
 import { ScmIntegrationRegistry } from '@backstage/integration';
+import { SessionApi } from '@backstage/core-plugin-api';
 
-// Warning: (ae-missing-release-tag) "ScmAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class ScmAuth implements ScmAuthApi {
+  static createDefaultApiFactory(): ApiFactory<
+    ScmAuthApi,
+    ScmAuthApi,
+    {
+      github: OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi;
+      gitlab: OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi;
+      azure: OAuthApi &
+        OpenIdConnectApi &
+        ProfileInfoApi &
+        BackstageIdentityApi &
+        SessionApi;
+    }
+  >;
   static forAuthApi(
     authApi: OAuthApi,
     options: {
@@ -26,7 +42,7 @@ export class ScmAuth implements ScmAuthApi {
     },
   ): ScmAuth;
   static forAzure(
-    microsoftAuthApiRef: OAuthApi,
+    microsoftAuthApi: OAuthApi,
     options?: {
       host?: string;
     },
@@ -55,20 +71,14 @@ export class ScmAuth implements ScmAuthApi {
   static merge(...providers: ScmAuth[]): ScmAuthApi;
 }
 
-// Warning: (ae-missing-release-tag) "ScmAuthApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export interface ScmAuthApi {
   getCredentials(options: ScmAuthTokenOptions): Promise<ScmAuthTokenResponse>;
 }
 
-// Warning: (ae-missing-release-tag) "scmAuthApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const scmAuthApiRef: ApiRef<ScmAuthApi>;
 
-// Warning: (ae-missing-release-tag) "ScmAuthTokenOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export interface ScmAuthTokenOptions extends AuthRequestOptions {
   additionalScope?: {
@@ -77,8 +87,6 @@ export interface ScmAuthTokenOptions extends AuthRequestOptions {
   url: string;
 }
 
-// Warning: (ae-missing-release-tag) "ScmAuthTokenResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public (undocumented)
 export interface ScmAuthTokenResponse {
   headers: {
diff --git a/packages/integration-react/src/api/ScmAuth.ts b/packages/integration-react/src/api/ScmAuth.ts
index a2b7da3785..beb66222d7 100644
--- a/packages/integration-react/src/api/ScmAuth.ts
+++ b/packages/integration-react/src/api/ScmAuth.ts
@@ -60,8 +60,32 @@ class ScmAuthMux implements ScmAuthApi {
 /**
  * An implementation of the ScmAuthApi that merges together OAuthApi instances
  * to form a single instance that can handles authentication for multiple providers.
+ *
+ * @public
+ *
+ * @example
+ * ```
+ * // Supports authentication towards both public GitHub and GHE:
+ * createApiFactory({
+ *   api: scmAuthApiRef,
+ *   deps: {
+ *     gheAuthApi: gheAuthApiRef,
+ *     githubAuthApi: githubAuthApiRef,
+ *   },
+ *   factory: ({ githubAuthApi, gheAuthApi }) =>
+ *     ScmAuth.merge(
+ *       ScmAuth.forGithub(githubAuthApi),
+ *       ScmAuth.forGithub(gheAuthApi, {
+ *         host: 'ghe.example.com',
+ *       }),
+ *     )
+ * })
+ * ```
  */
 export class ScmAuth implements ScmAuthApi {
+  /**
+   * Creates an API factory that enables auth for each of the default SCM providers.
+   */
   static createDefaultApiFactory() {
     return createApiFactory({
       api: scmAuthApiRef,
diff --git a/packages/integration-react/src/api/ScmAuthApi.ts b/packages/integration-react/src/api/ScmAuthApi.ts
index c526d4502f..ddb9922a19 100644
--- a/packages/integration-react/src/api/ScmAuthApi.ts
+++ b/packages/integration-react/src/api/ScmAuthApi.ts
@@ -20,6 +20,7 @@ import {
   AuthRequestOptions,
 } from '@backstage/core-plugin-api';
 
+/** @public */
 export interface ScmAuthTokenOptions extends AuthRequestOptions {
   /**
    * The URL of the SCM resource to be accessed.
@@ -42,6 +43,7 @@ export interface ScmAuthTokenOptions extends AuthRequestOptions {
   };
 }
 
+/** @public */
 export interface ScmAuthTokenResponse {
   /**
    * An authorization token that can be used to authenticate requests.
@@ -59,6 +61,8 @@ export interface ScmAuthTokenResponse {
  *
  * As opposed to using the using the GitHub, GitLab and other auth APIs
  * directly, this API allows for more generic access to SCM services.
+ *
+ * @public
  */
 export interface ScmAuthApi {
   /**
@@ -67,6 +71,11 @@ export interface ScmAuthApi {
   getCredentials(options: ScmAuthTokenOptions): Promise<ScmAuthTokenResponse>;
 }
 
+/**
+ * The ApiRef for the ScmAuthApi.
+ *
+ * @public
+ */
 export const scmAuthApiRef: ApiRef<ScmAuthApi> = createApiRef({
   id: 'core.scmauth',
 });