Add an optional cacheTTL to ReportOptions arguments #13629

Feature Description

Add an option to set the cache time-to-live value for getReport calls. Required for Fresh Data requests, since they'll be made every five minutes instead of every hour.

The key detail is that cacheTTL must not become part of the cache key. getCacheableReportOptions() in assets/js/util/report-options.ts already strips reportID before options become a key, for exactly this reason: two callers that differ only in a label should share one request and one cache entry. cacheTTL joins that omit list and is passed to get() instead, so it changes no cache keys and cannot fragment the cache: two selectors asking for the same report with different TTLs still share a request; the lower TTL simply lets that shared entry refresh sooner.

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

Acceptance criteria

• getReport's fetchOptions options accept an optional cacheTTL, in seconds.
  • cacheTTL will not need any special handling since it won't be part of the first argument to getReport (eg. the options argument).
• When a report is requested with a cacheTTL, that value is passed through to googlesitekit/api's get() and governs how long the response is considered fresh.
• Reports requested without a cacheTTL keep the existing one-hour behaviour, and their cache keys are byte-for-byte unchanged.
• Two callers requesting the same report with different cacheTTL values still share one in-flight request and one stored report.
• No user-visible change.

Implementation Brief

• Add cacheTTL argument to fetchOptions in getReport. Make fetchOptions an explicit type and add cacheTTL to it (cacheTTL?: number).
• Ensure separateFetchOptionsFromArgs also detects cacheTTL as an argument key in the second object, same as 'signal' is handled. (see:

  site-kit-wp/assets/js/googlesitekit/data/create-fetch-store.js

  Lines 68 to 77 in 501de04

  	*/
  	function separateFetchOptionsFromArgs( args ) {
  	const lastArg = args[ args.length - 1 ];
  	if ( isPlainObject( lastArg ) && 'signal' in lastArg ) {
  	return {
  	fetchArgs: args.slice( 0, -1 ),
  	fetchOptions: lastArg,
  	};
  	}

  )
• Update all createFetchStore controlCallback's to pass cacheTTL through to the control callback along with signal. (It may be better to just pass all args through to allow for future extensibility, but unclear.)

Test Coverage

• Update assets/js/googlesitekit/data/create-fetch-store.test.js to assert a report requested with cacheTTL passes it to get() (spy on googlesitekit-api), that one without it does not, and that two selectors differing only in cacheTTL produce a single fetch.
• Update assets/js/modules/search-console/datastore/report.test.js/assets/js/modules/analytics-4/datastore/report.test.js with the equivalent assertions, as they will rely on cacheTTL.

QA Brief

• QA should simply check that on a site with Search Console and Analytics connected, a report still loads.

Changelog entry

• N/A