updated with API proposal guidence

spec/common/providers/identity.spec.ts

@@ -27,6 +27,8 @@ import * as identity from "../../../src/common/providers/identity";
 const EVENT = "EVENT_TYPE";
 const now = new Date();
 const TEST_NAME = "John Doe";
+const ALLOW = "ALLOW";
+const BLOCK = "BLOCK";
 
 describe("identity", () => {
   describe("userRecordConstructor", () => {
@@ -771,24 +773,24 @@ describe("identity", () => {
     });
   });
 
-  describe("generateRequestPayload", () => {
+  describe("generateResponsePayload", () => {
     const DISPLAY_NAME_FIELD = "displayName";
     const TEST_RESPONSE = {
       displayName: TEST_NAME,
-      recaptchaPassed: false,
+      recaptchaActionOverride: BLOCK,
     } as identity.BeforeCreateResponse;
 
     const EXPECT_PAYLOAD = {
       userRecord: { displayName: TEST_NAME, updateMask: DISPLAY_NAME_FIELD },
-      recaptchaPassed: false,
+      recaptchaActionOverride: BLOCK,
     };
 
-    const TEST_RESPONSE_RECAPTCHA_TRUE = {
-      recaptchaPassed: true,
+    const TEST_RESPONSE_RECAPTCHA_ALLOW = {
+      recaptchaActionOverride: ALLOW,
     } as identity.BeforeCreateResponse;
 
-    const EXPECT_PAYLOAD_RECAPTCHA_TRUE = {
-      recaptchaPassed: true,
+    const EXPECT_PAYLOAD_RECAPTCHA_ALLOW = {
+      recaptchaActionOverride: ALLOW,
     };
 
     const TEST_RESPONSE_RECAPTCHA_UNDEFINED = {
@@ -802,19 +804,19 @@ describe("identity", () => {
       expect(identity.generateResponsePayload()).to.eql({});
     });
 
-    it("should exclude recaptchaPass field from updateMask", () => {
+    it("should exclude recaptchaActionOverride field from updateMask", () => {
       expect(identity.generateResponsePayload(TEST_RESPONSE)).to.deep.equal(EXPECT_PAYLOAD);
     });
 
-    it("should return recaptchaPass when it is true on response", () => {
-      expect(identity.generateResponsePayload(TEST_RESPONSE_RECAPTCHA_TRUE)).to.deep.equal(
-        EXPECT_PAYLOAD_RECAPTCHA_TRUE
+    it("should return recaptchaActionOverride when it is true on response", () => {
+      expect(identity.generateResponsePayload(TEST_RESPONSE_RECAPTCHA_ALLOW)).to.deep.equal(
+        EXPECT_PAYLOAD_RECAPTCHA_ALLOW
       );
     });
 
-    it("should not return recaptchaPass if undefined", () => {
+    it("should not return recaptchaActionOverride if undefined", () => {
       const payload = identity.generateResponsePayload(TEST_RESPONSE_RECAPTCHA_UNDEFINED);
-      expect(payload.hasOwnProperty("recaptchaPassed")).to.be.false;
+      expect(payload.hasOwnProperty("recaptchaActionOverride")).to.be.false;
       expect(payload).to.deep.equal(EXPECT_PAYLOAD_UNDEFINED);
     });
   });

src/common/providers/identity.ts

@@ -339,18 +339,19 @@ export interface AuthBlockingEvent extends AuthEventContext {
   data: AuthUserRecord;
 }
 
-/** The base handler response type for beforeCreate and beforeSignIn blocking events*/
-export interface BlockingFunctionResponse {
-  recaptchaPassed?: boolean;
-}
+/**
+ * The reCACPTCHA action options.
+ */
+export type RecatpchaActionOptions = "ALLOW" | "BLOCK";
 
 /** The handler response type for beforeCreate blocking events */
-export interface BeforeCreateResponse extends BlockingFunctionResponse {
+export interface BeforeCreateResponse {
   displayName?: string;
   disabled?: boolean;
   emailVerified?: boolean;
   photoURL?: string;
   customClaims?: object;
+  recaptchaActionOverride?: RecatpchaActionOptions;
 }
 
 /** The handler response type for beforeSignIn blocking events */
@@ -433,14 +434,18 @@ export interface DecodedPayload {
   [key: string]: any;
 }
 
-/** @internal */
+/**
+ * This interface defines the payload to send back to GCIP.
+ * The nesting structure different than what customers returned.
+ * @internal */
 export interface ResponsePayload {
   userRecord?: UserRecordResponsePayload;
-  recaptchaPassed?: boolean;
+  recaptchaActionOverride?: RecatpchaActionOptions;
 }
 
 /** @internal */
-export interface UserRecordResponsePayload extends Omit<BeforeSignInResponse, "recaptchaPassed"> {
+export interface UserRecordResponsePayload
+  extends Omit<BeforeSignInResponse, "recaptchaActionOverride"> {
   updateMask?: string;
 }
 
@@ -673,7 +678,8 @@ export function generateResponsePayload(
     return {};
   }
 
-  const { recaptchaPassed, ...formattedAuthResponse } = authResponse;
+  const { recaptchaActionOverride: recaptchaActionOverride, ...formattedAuthResponse } =
+    authResponse;
   const result = {} as ResponsePayload;
   const updateMask = getUpdateMask(formattedAuthResponse);
 
@@ -684,8 +690,8 @@ export function generateResponsePayload(
     };
   }
 
-  if (recaptchaPassed !== undefined) {
-    result.recaptchaPassed = recaptchaPassed;
+  if (recaptchaActionOverride !== undefined) {
+    result.recaptchaActionOverride = recaptchaActionOverride;
   }
 
   return result;