Add the “expirable items" infrastructure

[techanvil]

Feature Description

Add the generic “expirable items" infrastructure that will be used to manage the "New" badges.

See "New" badges in the design doc.

---

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

Acceptance criteria

• A new REST route POST:core/user/data/set-expirable-item-timers should be added to Site Kit.
  • It should receive a list of expirable items and set the expiry date for each of them. The expiry date is the date the item should expire for the current user.
  • It should be ensured that each item is automatically expired once its expiry date is reached.
  • The list of items should be passed in the request body. Each item should be an object with the following properties:
    • slug: A unique identifier for the item.
    • expiresInSeconds: The number of seconds after which this item should be expired. This can be renamed if it turns out to conflict with usage of the dismissed items infrastructure.
• The following selector and action should be added to the core/user data store:
  • isExpirableItemActive( itemSlug ): This selector should return a boolean indicating whether the given expirable item is active for the current user, i.e. it will return false if the item has expired, true otherwise.
  • setExpirableItemTimers( item [, item…] ): This action should set the expiry date of the specified items for the current user via the POST:core/user/data/start-expirable-item-timers endpoint.

Implementation Brief

Note that the infrastructure should leverage existing APIs where possible, for example it may be viable to build it on top of the dismissed items infra in conjunction with the use of WordPress transients.

• [x] Create a new Expirables directory in the includes/Core directory.

• [x] Create a new Expirable_Items class in the includes/Core/Expirables directory.

  • [x] Expirable_Items should extend the User_Setting class.
  • [x] Expirable_Items should be similar to the Dismissed_Prompts class, but with the following differences:
  • [x] The name of the DB option should be googlesitekitpersistent_expirable_items.
  • [x] The option will have the following data structure:

    array(
        'item-slug-1' => 1700000000,
        'item-slug-2' => 1690000000
    );

  • [x] get_default() method which will return an empty array.
  • [x] add method
    • [x] The method takes a slug and an expires_in_seconds parameter. It first retrieves the current list of items.
    • [x] The updated list of items is then saved back using the User_Options::set() method.
  • [x] remove method:
    • [x] It should receive an slug parameter.
    • [x] Check if the item exists in the list and remove it if found.
  • [x] get_sanitize_callback method:
    • [x] Create a callback function that iterates through each item, checking for validity of the expires and seen fields. Ensure that all timestamps and boolean values are appropriately formatted.

• [x] Create a new REST_Expirable_Items_Controller class in the includes/Core/Expirables directory.

  • [x] Constructor should accept an instance of Expirable_Items and set it to the instance variable $expirable_items.
  • [x] register method:
  • [x] Use googlesitekit_rest_routes filter the to register the route.
  • [x] Use get_rest_routes method as callback to register the route.
  • [x] get_rest_routes method:
  • [x] We will need to register two routes, namely:
    • [x] GET:core/user/data/expirable-items - Callback for this route should return the associative array of expirable items and their expiry times.
    • [x] POST:core/user/data/set-expirable-item-timers - This should accept the array objects consisting of slug (type: string) which represents the item and expiresInSeconds (type: int) represents the expiration time in seconds.
    • [x] It should return an error if request payload/parameters are not as expected.
    • [x] If the payload is looking good, use $expirable_items::add method iteratively to add items in the expirables data.
  • [x] We should ensure the GET:core/user/data/expirable-items route is preloaded using the googlesitekit_apifetch_preload_paths filter, here's an example.

• [x] Create a new Expirables class in the includes/Core/Expirables directory.

  • [x] This will be quite similar to the Dismissals class in structure:
  • [x] The dismissed_items instance variable will be replaced by expirable_items.
  • [x] The register method should call register methods from REST_Expirable_Items_Controller and Expirable_Items classes.
  • [x] There is no need for a get_expirable_items method.

Adding selector and action to core/user store

• [x] Add assets/js/googlesitekit/datastore/user/expirable-items.js
  • [x] Create a store (fetchGetExpirableItemsStore) via createFetchStore.
  • [x] baseName should be getExpirableItems
  • [x] controlCallback should use expirable-items datapoint.
  • [x] Create a store (fetchSetExpirableItemTimersStore) via createFetchStore.
  • [x] baseName should be setExpirableItemTimers
  • [x] controlCallback should use set-expirable-item-timers datapoint.
  • [x] argsToParams should return array of objects. Each object should be in following shape.

    [
        {
            "slug": "item-1",
            "expiresInSeconds": 1715155931
        },
        {
            "slug": "item-2",
            "expiresInSeconds": 1715156032
        }
    ]

  • [x] validateParams should validate slug is non-empty string and expiresInSeconds is non-negative, non-zero integer.
• [x] baseInitialState should be {expirableItems: undefined}
• [x] baseActions should have setExpirableItemTimers selector which would call the fetchSetExpirableItemTimersStore.actions.fetchSetExpirableItemTimers.
• [x] baseSelectors should have getExpirableItems, which would have equivalent *getExpirableItems resolver which would call fetchGetExpirableItemsStore.actions.fetchGetExpirableItems.
  • [x] baseSelectors should have isExpirableItemActive which would internally call getExpirableItems selector to check if item exists, and its expiry date is in the past.
  • [x] baseSelectors should have hasExpirableItem which would accept the slug of the item and check if it exists in the list of expirable items. It returns true if item exists, else false.

Note: Take a reference of assets/js/googlesitekit/datastore/user/dismiss-items.js to create the store.

Test Coverage

• Add tests for expirable-items.js in assets/js/googlesitekit/datastore/user/expirable-items.test.js.
• Add tests for REST_Expirable_Items_Controller and Expirable_Items classes.

QA Brief

Adding the expirable items

1. Run following command in browser console.

   googlesitekit.data.dispatch('core/user').setExpirableItemTimers([
   {
       slug: 'foo',
       expiresInSeconds: 100,
   },
   {
       slug: 'bar',
       expiresInSeconds: 200,
   },
   ]);

2. This should trigger a request in network tab of the browser to core/user/data/set-expirable-item-timers endpoint. Ensure that the request is successfully executed with response 200.

Fetching the expirable items

1. Run following command in browser console.

googlesitekit.data.select('core/user').getExpirableItems();

2. This will return the object like following. Note that we are preloading the expirable items, so this should not send a separate network request.

{
    "foo": 1715622594,
    "bar": 1715622694
}

Note that timestamp may be different which is object value like 1715622594.

Checking whether the expirable item is active

1. Create an item which should expire after 10 seconds with the help of following command.

googlesitekit.data.dispatch('core/user').setExpirableItemTimers([
    {
        slug: 'shortSpan',
        expiresInSeconds: 10,
    },
]);

2. Refresh the page after 15-20 seconds and run following command.

googlesitekit.data.select('core/user').isExpirableItemActive('shortSpan');

this should return the value false as the item must have expired.

Checking whether the expirable item is exists

1. Run the following command in browser console.

googlesitekit.data.select('core/user').hasExpirableItem('foo');

2. This should return true as we have created foo item above.

3. Run another command in browser console.

googlesitekit.data.select('core/user').hasExpirableItem('baz');

4. This should return false as we have never created baz as expirable item.

Changelog entry

• Add a new API/infrastructure for managing “expirable items".

[techanvil]

Note that I've moved this back to the Backlog pending the outcome of this discussion on the design doc regarding the shape of the API.

[techanvil]

Said discussion is now resolved and this issue is ready for AC.

[eugene-manuilov]

AC ✔️

[techanvil]

I've moved this back to AC pending an update once we've confirmed changes to the infrastructure underpinning the "New" badges, as discussed on Slack.

[techanvil]

Update: I've moved this to the Backlog instead to make it clearer which issues are waiting for a change or approval to the design doc (see this comment on the doc).

[techanvil]

The related design doc discussion has been resolved and this is ready for IB.

[zutigrm]

Unassigning myself as this is squad 2 related

[techanvil]

Hi @ankitrox! Thanks for drafting this IB, nice work so far. A few points:

• [ ] The option will have the following data structure:

     array(
         'item-slug-1' => array(
             "expires" => 1700000000
         ),
         'item-slug-2' => array(
             "expires" => 1690000000
         ),
     );

Arguably, we don't need a nested array structure here, if we only have the one subkey expires. We could follow the example of the Dismissed_Items setting, i.e.:

array(
    'item-slug-1' => 1700000000,
    'item-slug-2' => 1690000000
);

The nested approach is a bit more self documenting and extensible, which I do like. However, there's something to be said for consistency. Seeing as it's essentially the same conceptual shape maybe we should go for that (the simple, non-nested array) in the first iteration at least. This would also have a marginal benefit to the page weight as we'll be including the serialized value on the page as a result of preloading the path (as discussed further below). WDYT?

---

• [ ] get_active_items method:
  • I don't think we actually need this method. We want to provide the full value of the setting to the client, and leave the logic for checking if an item has been seen/set before, and if it's active/expired to the client. This way the client can determine whether a request needs to be made to set the timer for the item.

---

• [ ] If an item with the given slug already exists, only its expires time is updated, preserving other attributes like seen. If the item is new, it is added with a default seen status of false.
  • What's the reference to "seen" here? Did you intend to add another key to the nested structure above? I'm not sure we'd need a seen though (although I do think we need an extra selector where we can determine if something has been seen, as per below, but we can derive the "seen" status from whether the item has ever been set). Anyhow, please do clarify this one.

---

• [ ] GET:core/user/data/expirable-items - Callback for this route should return the items which has expired. That means the timestamp for the expiration time has been passed when we compare it with the current time.
  • As discussed above, we should ensure the full value of the setting is returned from this route, and leave additional logic to the client side.

---

• [ ] POST:core/user/set-expirable-item-timers - This should accept the object consisting of slug (type: string) which represents the item and expiresInSeconds (type: int) represents the expiration time in seconds.
  • As per the AC, this route should support multiple items so we can keep the number of requests to a minimum.

---

• [ ] If expiration time is not passed, set it to 0 that means it will never expire.
  • This is not a requirement here, we should always expect an expirable item to have an expiry date.

---

• [ ] get_expirable_items method:
  • We won't need this method, at least not that we currently know of. So, there's no need to include it - we can add it if/when we do need it.

---

• [ ] Create a store (fetchExpireItemStore) off createFetchStore.
  • As discussed above, the related endpoint should handle multiple items in a single request, so the args should be updated accordingly.
  • Also, super minor but the backticks are missing around fetchExpireItemStore, and it would be more grammatically correct to say "via createFetchStore", or "from a call to createFetchStore".
  • Please review the IB for any other backticks that have been missed in its formatting.

---

• We should ensure the GET:core/user/data/expirable-items route is preloaded using the googlesitekit_apifetch_preload_paths filter, here's an example.
• A minor oversight, the POST route should be core/user/data/set-expirable-item-timers not core/user/set-expirable-item-timers.
• Although not covered in the AC, I think we need an additional selector, hasExpirableItem(), so we can tell if the user's already seen/set the item. This can return a boolean, true if the item slug exists in the set of expirable items, false if not. Please can you include this in the IB?

[ankitrox]

Thanks for reviewing this @techanvil .

Regarding the seen option, earlier I was writing IB based on the seen property, but later I thought that it may not be required. Setting an item in expirable items itself should be sufficient to know that it has been seen. That one point remained in IB by mistake which I've removed now.

Rest of the points I have addressed as per your suggestion.

Assigning this to you for your re-review.

Thank you.

[techanvil]

Thanks @ankitrox, that makes sense.

I've made a few amendments to the IB - some points were missed, and a couple of naming and grammatical tweaks were needed.

Please review the changes and if you're happy, feel free to move this to the EB.

IB :white_check_mark:

[ankitrox]

Looks everything good now. Thank you @techanvil .

Moving this to EB.

[techanvil]

Hi @ankitrox, regarding the QAB here - rather than using fetchExpirableItems() in the test, I would suggest rewriting it to use (and therefore test) setExpirableItemTimers().

Please can you also include instructions for testing hasExpirableItem()?

[ankitrox]

Hi @techanvil ,

Thanks for the CR. I have addressed the comments in the PR and also updated the QAB to include setExpirableItemTimers action instead of fetchExpirableItems.

Assigning this to you for review again.

Thanks

[techanvil]

Thanks @ankitrox! The QAB is looking good, I've left a few more comments on the PR.

[kelvinballoo]

QA Update ✅

Tested per the QAB and results were as expected:

• First script about setting expirable timers triggered a request in network tab of the browser to core/user/data/set-expirable-item-timers endpoint succesfully with response 200.

  

• Getting the expirable items were successful too:

  

• All the other scrips were as expected as well :

  

Moving ticket to Approval.