Request the new RRM scopes for the express setup #13004

Feature Description

The new Reader Revenue Manager Express Setup flow uses the webcontentpublisher API, which needs its own OAuth scopes rather than the subscribewithgoogle read-only scope the module requires today. Request https://www.googleapis.com/auth/webcontentpublisher.publications.readonly and https://www.googleapis.com/auth/webcontentpublisher.publications.manage when the user enters the express setup flow, and require the read-only scope for new setups, so that they grant it up front while existing users are not prompted.

For reference, see the Infrastructure section in the design doc.

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• The Reader Revenue Manager module requires https://www.googleapis.com/auth/webcontentpublisher.publications.readonly for users setting up the module, and for users who have already granted it, so that new setups grant it up front and existing users holding only subscribewithgoogle.publications.readonly are not prompted.
• The module requires https://www.googleapis.com/auth/webcontentpublisher.publications.manage for users who have already granted it
• The express setup requests, on entry, any of the following scopes the user has not already granted:
  • https://www.googleapis.com/auth/webcontentpublisher.publications.readonly
  • https://www.googleapis.com/auth/webcontentpublisher.publications.manage
  • Any scopes required by the specific express setup flow.
• The scopes are requested when the user activates the flow from an entry point, and by the express setup screen when the flow is entered directly.
• When the user denies the OAuth consent screen, they are returned to the Site Kit dashboard with the standard OAuth error.
• When the user completes consent without granting a requested scope, the express setup does not request it again automatically, avoiding a loop.
• A request to an express setup write datapoint made without the manage scope returns a recognizable insufficient-scopes error, so that the publisher is prompted to grant it at the point of use.
• With rrmExpressSetup off, the module's required scopes and the standard Reader Revenue Manager setup are unchanged.

Implementation Brief

• includes/Modules/Reader_Revenue_Manager.php

  • Add class constants for the two webcontentpublisher scopes.
  • Under the rrmExpressSetup flag, filter googlesitekit_auth_scopes to refine the requested scopes per user, mirroring Analytics_4::get_refined_scopes(). get_scopes() itself is unchanged, so neither scope is required of the module unconditionally.
  • Add the webcontentpublisher read-only scope when the user is not yet authenticated, when the module is not yet connected, or when they have already granted it, so that new setups grant it up front and existing users holding only subscribewithgoogle.publications.readonly are not prompted.
  • Add the manage scope only when the user has already granted it, so that it is preserved across subsequent authorizations without the standard module setup asking for it.
  • Declare the manage scope on the write datapoints, as Analytics_4 does for its edit scope, so that a call made without it throws Insufficient_Scopes_Exception. googlesitekit/api dispatches setPermissionScopeError for that error code automatically, which prompts the publisher to grant it. Leave the read datapoints alone: the old read-only scope still authorizes the API during the migration period, and declaring the new one would reject calls that succeed.

• assets/js/modules/reader-revenue-manager/datastore/constants.ts

  • Add READONLY_SCOPE and MANAGE_SCOPE constants for the two RRM OAuth scope strings.

• assets/js/modules/reader-revenue-manager/components/setup/SetupMainExpress/constants.ts

  • Add EXPRESS_SETUP_SCOPES, the scopes every express setup flow requires, so that the hook and the entry points share one list.

• assets/js/hooks/useActivateModuleCallback.js

  • Optionally accept additionalScopes as an array of strings in ActivateModuleOptions.

• assets/js/googlesitekit/modules/datastore/modules.js

  • Extend activateModule( slug, options ) action to destructure additionalScopes from options and include them in the SELECT_MODULE_REAUTH_URL control payload.
  • Update SELECT_MODULE_REAUTH_URL control to forward additionalScopes into the module's getAdminReauthURL selector call.

• assets/js/googlesitekit/modules/create-info-store.js

  • Extend getAdminReauthURL to accept additionalScopes alongside the existing reAuth option.
  • Compute unsatisfiedAdditionalScopes by filtering additionalScopes through CORE_USER.hasScope.
  • Resolve to connect URL when needsReauthentication is true or unsatisfiedAdditionalScopes.length > 0, passing unsatisfiedAdditionalScopes into CORE_USER.getConnectURL.

• assets/js/modules/reader-revenue-manager/components/setup/SetupMainExpress/hooks.ts

  • Add a useExpressSetupScopes( additionalScopes ) hook that requests EXPRESS_SETUP_SCOPES plus anything passed to it, so that each flow declares only what it adds.
  • Filter to scopes the user has not granted using CORE_USER.hasScope, and request them in a single setPermissionScopeError call with skipModal: true and redirectURL: location.href, following the same immediate-OAuth-redirect pattern used in useEnableAudienceGroup.js. This ensures AuthenticatedPermissionsModal redirects to OAuth without presenting a confirmation dialog.
  • Do not pass errorRedirectURL. Leaving it unset sends the user to the Site Kit dashboard with the standard OAuth error when they deny the consent screen.
  • Do not request a scope again when returning from a completed authorization without it, which notification=authentication_success in the URL identifies. Deselecting a scope through Google's granular consent is not an OAuth error, so the publisher returns to redirectURL rather than to the dashboard, and re-requesting would loop.

• In ExpressSetupDefault.tsx and cta-setups/SetupCTANewsletterSignup/index.tsx:

  • Call useExpressSetupScopes(). Neither requires additional scopes.

• Express setup entry point banner (Implement the RRM express setup dashboard entry point #12947) and RRM setup CTA banner (Update RRM setup CTA banner for express setup #12946)

  • Wire the RRM express setup CTA activation call via useActivateModuleCallback with:
    • redirectQueryArgs: { expressSetup: true, cta: 'newsletter-signup' }
    • additionalScopes: EXPRESS_SETUP_SCOPES
  • A CTA that needs more than these defines them in its own constants.ts, passed both here and to useExpressSetupScopes, so that a banner and its flow never request different sets.

Test Coverage

• Update create-info-store selector tests.
• Update core/modules activation tests.
• Update tests for the setup CTA and entry point banners as per the changes.
• Add tests for useExpressSetupScopes covering the default scopes, additional scopes passed by a flow, a user who has already granted them, and a return from a completed authorization still missing a scope, asserting it is not requested again.
• Add tests asserting the flows render the scope error in place of their steps when scopes are missing, and re-enter OAuth from its action.
• Add tests for the googlesitekit_auth_scopes filter covering an unauthenticated user, a connected user holding only the old read-only scope, a user who has granted the new read-only scope, a user who has granted the manage scope, and the flag off.
• Add tests asserting the write datapoints throw Insufficient_Scopes_Exception without the manage scope.

QA Brief

NOTE While we wait for re-approval of the OAuth app for the new scopes, a "This app is blocked" error will appear when authenticating, with no way to proceed. Until the approval is granted this issue can be tested by using the staging proxy.

Between each of the following tests, go to https://myaccount.google.com/ > Linked apps > Site Kit and Delete all.

RRM setup without Express Setup enabled

1. Set up Site Kit without rrmExpressSetup enabled.
2. Set up Reader Revenue Manager from Settings > Connect more services.
3. You will be redirected to authenticate and prompted to grant access to See and review your publication data (there won't be a checkbox because it's a single permission).
4. Setup should proceed as normal.

RRM setup with Express Setup enabled

1. Set up Site Kit with rrmExpressSetup enabled.
2. Set up Reader Revenue Manager from Settings > Connect more services.
3. You will need to authenticate and you should be prompted to grant access to:
   • See information on newsletter sign-up forms.
   • See and review your publication data.
4. Grant them and setup should proceed as normal.

RRM setup with Express Setup enabled, without granting permissions

1. Set up Site Kit with rrmExpressSetup enabled.
2. Set up Reader Revenue Manager from Settings > Connect more services.
3. You will need to authenticate and you should be prompted to grant access to:
   • See information on newsletter sign-up forms.
   • See and review your publication data.
4. Clicking Cancel, or Continue without granting both permissions should redirect to the dashboard where a Site Kit can’t access necessary data notice will be shown.
5. Clicking Redo setup should return to the authentication step. Granting both permissions should return you to the Reader Revenue Manager setup where you'll be prompted to select a publication.

RRM setup initiated with Express Setup

1. Set up Site Kit with rrmExpressSetup enabled.
2. From the dashboard, in the Collect reader emails directly on your site widget, click Set up a sign-up form.
3. You will need to authenticate and you should be prompted to grant access to:
   • Read and edit information on newsletter sign-up forms.
   • See information on newsletter sign-up forms.
   • See and review your publication data.
4. Granting all permissions should return to Express Setup, which should proceed as normal.

RRM setup initiated with Express Setup, without granting permissions

1. Set up Site Kit with rrmExpressSetup enabled.
2. From the dashboard, in the Collect reader emails directly on your site widget, click Set up a sign-up form.
3. You will need to authenticate and you should be prompted to grant access to:
   • Read and edit information on newsletter sign-up forms.
   • See information on newsletter sign-up forms.
   • See and review your publication data.
4. Clicking Cancel, or Continue without granting all permissions should redirect to the dashboard where a Site Kit can’t access necessary data notice will be shown.
5. Clicking Redo setup should return to the authentication step where you should be prompted for the same 3 permissions. Granting all of them should return to Express Setup, which should proceed as normal.

Express Setup after RRM setup

1. Set up Site Kit with rrmExpressSetup enabled.
2. Set up Reader Revenue Manager from Settings > Connect more services.
3. You will need to authenticate and you should be prompted to grant access to:
   • See information on newsletter sign-up forms.
   • See and review your publication data.
4. Grant them and setup should proceed as normal.
5. Navigate directly to /wp-admin/admin.php?page=googlesitekit-dashboard&slug=reader-revenue-manager&reAuth=true&expressSetup=true&cta=newsletter-signup.
6. You will be redirected to authenticate and prompted to grant access to Read and edit information on newsletter sign-up forms (there won't be a checkbox because it's a single permission).
7. Clicking continue should return to Express Setup, which should proceed as normal.

Express Setup after RRM setup, without granting permissions

1. Set up Site Kit with rrmExpressSetup enabled.
2. Set up Reader Revenue Manager from Settings > Connect more services.
3. You will need to authenticate and you should be prompted to grant access to:
   • See information on newsletter sign-up forms.
   • See and review your publication data.
4. Grant them and setup should proceed as normal.
5. Navigate directly to /wp-admin/admin.php?page=googlesitekit-dashboard&slug=reader-revenue-manager&reAuth=true&expressSetup=true&cta=newsletter-signup.
6. You will be redirected to authenticate and prompted to grant access to Read and edit information on newsletter sign-up forms (there won't be a checkbox because it's a single permission).
7. Clicking Cancel should redirect to the dashboard where a Site Kit can’t access necessary data notice will be shown.
8. Clicking Redo setup should return to the authentication step where you should be prompted for the same Read and edit information on newsletter sign-up forms permission. Granting all of them should return to Express Setup, which should proceed as normal.

Repeat each test without removing Site Kit from Linked apps. At each step where you were previously prompted to grant specific permissions you should instead be shown an "X already has some access" message with "See the Y services that X has some access to." Clicking Y services should show a list of permissions that includes the permissions that you were prompted to grant when they had not already been granted.

Changelog entry

• N/A.