Warn user about new stock events in the webhook event picker (#6549)

Co-authored-by: Lukasz Ostrowski <lukasz.ostrowski@saleor.io>

Author: mirekm

.changeset/bright-otters-dance.md

@@ -0,0 +1,7 @@
+---
+"saleor-dashboard": patch
+---
+
+Webhook event picker: warn admins about Saleor 3.23 channel-scoped stock events.
+
+The four `PRODUCT_VARIANT_BACK_IN_STOCK_*` / `PRODUCT_VARIANT_OUT_OF_STOCK_*` events introduced in Saleor 3.23 fire only when the shop has the legacy shipping-zone stock-availability setting disabled. They were already exposed in the picker (auto-derived from the schema), but admins on shops still in legacy mode could subscribe with no visual cue and silently never receive deliveries. Each of those four events now shows an advisory "Direct stock mode only" badge with a tooltip linking to the site-settings page where the flag is configured. Adds a regression test pinning the four events to the `PRODUCT_VARIANT` group, and a comment in `ExcludedDocumentKeys` documenting that the dry-run feature already covers them transitively via prefix matching.

locale/defaultMessages.json

@@ -2333,6 +2333,10 @@
     "context": "delete channel",
     "string": "Select channel that you wish to move existing orders to."
   },
+  "BSGid2": {
+    "context": "Advisory badge shown next to a webhook event in the picker when the event only fires while the shop has the direct (non-legacy) warehouse-channel stock-availability mode enabled.",
+    "string": "Direct stock mode only"
+  },
   "BUKMzM": {
     "string": "Variant removed"
   },
@@ -2392,6 +2396,10 @@
     "context": "header",
     "string": "Translation Collection \"{collectionName}\" - {languageCode}"
   },
+  "BrRGIJ": {
+    "context": "Tooltip body for the direct-stock-mode-only badge in the webhook event picker. Quotes the exact label of the toggle on the site-settings page so the admin recognizes it when they click through.",
+    "string": "Fires only while \"Use legacy shipping zone stock availability\" is disabled in site settings. Otherwise the subscription produces no deliveries."
+  },
   "BtsJ+e": {
     "context": "empty state message when no login method is available",
     "string": "Password login is disabled. Contact your administrator to configure an external authentication method or enable password login."
@@ -10710,6 +10718,10 @@
   "vfG+nh": {
     "string": "Confirm Password"
   },
+  "vh9a5S": {
+    "context": "Tooltip CTA on the direct-stock-mode-only badge in the webhook event picker. Links to the page where the legacy stock-availability flag can be toggled.",
+    "string": "Open shop settings"
+  },
   "viFkCw": {
     "context": "site settings section name",
     "string": "Site Settings"

src/components/DryRunItemsList/utils.ts

@@ -219,6 +219,14 @@ export const DocumentMap: Record<string, Document> = {
 
 // Documents which require parent object or can't be handled ATM
 //
+// Note: matching is done via `event.startsWith(object)` in
+// `src/components/DryRun/utils.ts`, so prefix entries also cover their
+// channel-scoped descendants — e.g. `PRODUCT_VARIANT_BACK_IN_STOCK` covers the
+// Saleor 3.23+ events `PRODUCT_VARIANT_BACK_IN_STOCK_FOR_CLICK_AND_COLLECT`
+// and `PRODUCT_VARIANT_BACK_IN_STOCK_IN_CHANNEL`, and `PRODUCT_VARIANT_OUT_OF_STOCK`
+// covers the corresponding `_FOR_CLICK_AND_COLLECT` / `_IN_CHANNEL` variants.
+// If you ever switch the matcher to exact-equality, expand these prefixes to
+// list the concrete event names individually.
 export const ExcludedDocumentKeys = [
   // USER ID REQUIRED
   "ADDRESS",

src/extensions/components/WebhookDetailsPage/components/WebhookEvents/WebhookEvents.tsx

@@ -1,9 +1,11 @@
 import { DashboardCard } from "@dashboard/components/Card";
 import Grid from "@dashboard/components/Grid";
 import Hr from "@dashboard/components/Hr";
+import { Link } from "@dashboard/components/Link";
 import { type WebhookEventTypeAsyncEnum, type WebhookEventTypeSyncEnum } from "@dashboard/graphql";
 import { type ChangeEvent } from "@dashboard/hooks/useForm";
 import { capitalize } from "@dashboard/misc";
+import { siteSettingsUrl } from "@dashboard/siteSettings/urls";
 import {
   List,
   ListBody,
@@ -12,13 +14,13 @@ import {
   ListItemCell,
   useListWidths,
 } from "@saleor/macaw-ui";
-import { Box, Checkbox, Chip, Switch, Text } from "@saleor/macaw-ui-next";
+import { Box, Checkbox, Chip, Switch, Text, Tooltip } from "@saleor/macaw-ui-next";
 import { type Dispatch, type SetStateAction, useState } from "react";
 import { FormattedMessage, useIntl } from "react-intl";
 
 import { messages } from "./messages";
 import { useStyles } from "./styles";
-import { EventTypes, getEventName } from "./utils";
+import { EventTypes, getEventName, isDirectStockModeOnlyEvent } from "./utils";
 
 interface WebhookEventsProps {
   data: {
@@ -147,36 +149,75 @@ export const WebhookEvents = ({
               <ListBody className={classes.listBody}>
                 {object &&
                   EventTypes[tab][object] &&
-                  EventTypes[tab][object].map((event, idx) => (
-                    <ListItem className={classes.eventListItem} key={event}>
-                      <ListItemCell className={classes.eventListItemCell}>
-                        <Checkbox
-                          data-test-id="events-checkbox"
-                          name={`${tab}Events`}
-                          checked={(data[`${tab}Events`] as WebhookEventTypeSyncEnum[]).includes(
-                            getEventName(object, event),
-                          )}
-                          value={getEventName(object, event)}
-                          onCheckedChange={checked =>
-                            handleEventChange({
-                              target: {
-                                name: `${tab}Events`,
-                                value: getEventName(object, event),
-                                // @ts-expect-error incorrect useForm types - cannot set required checked property
-                                checked,
-                              },
-                            })
-                          }
-                          id={`event-checkbox-${idx}`}
-                          paddingX={1.5}
-                          paddingY={3.5}
-                          fontWeight="bold"
-                        >
-                          {capitalize(event.toLowerCase().replaceAll("_", " "))}
-                        </Checkbox>
-                      </ListItemCell>
-                    </ListItem>
-                  ))}
+                  EventTypes[tab][object].map((event, idx) => {
+                    const eventName = getEventName(object, event);
+                    const showDirectStockModeBadge = isDirectStockModeOnlyEvent(eventName);
+
+                    return (
+                      <ListItem className={classes.eventListItem} key={event}>
+                        <ListItemCell className={classes.eventListItemCell}>
+                          <Box display="flex" alignItems="center" gap={2}>
+                            <Checkbox
+                              data-test-id="events-checkbox"
+                              name={`${tab}Events`}
+                              checked={(
+                                data[`${tab}Events`] as WebhookEventTypeSyncEnum[]
+                              ).includes(eventName)}
+                              value={eventName}
+                              onCheckedChange={checked =>
+                                handleEventChange({
+                                  target: {
+                                    name: `${tab}Events`,
+                                    value: eventName,
+                                    // @ts-expect-error incorrect useForm types - cannot set required checked property
+                                    checked,
+                                  },
+                                })
+                              }
+                              id={`event-checkbox-${idx}`}
+                              paddingX={1.5}
+                              paddingY={3.5}
+                              fontWeight="bold"
+                            >
+                              {capitalize(event.toLowerCase().replaceAll("_", " "))}
+                            </Checkbox>
+                            {showDirectStockModeBadge && (
+                              <Tooltip>
+                                <Tooltip.Trigger>
+                                  <Chip
+                                    data-test-id="direct-stock-mode-badge"
+                                    backgroundColor="warning1"
+                                    borderColor="warning1"
+                                    color="warning1"
+                                    size="small"
+                                    __cursor="help"
+                                  >
+                                    {intl.formatMessage(messages.directStockModeBadge)}
+                                  </Chip>
+                                </Tooltip.Trigger>
+                                <Tooltip.Content side="top">
+                                  <Tooltip.Arrow />
+                                  <Box
+                                    __maxWidth="320px"
+                                    display="flex"
+                                    flexDirection="column"
+                                    gap={2}
+                                  >
+                                    <Text size={2}>
+                                      <FormattedMessage {...messages.directStockModeTooltipBody} />
+                                    </Text>
+                                    <Link href={siteSettingsUrl()} underline>
+                                      <FormattedMessage {...messages.directStockModeTooltipLink} />
+                                    </Link>
+                                  </Box>
+                                </Tooltip.Content>
+                              </Tooltip>
+                            )}
+                          </Box>
+                        </ListItemCell>
+                      </ListItem>
+                    );
+                  })}
               </ListBody>
             </List>
           </div>

src/extensions/components/WebhookDetailsPage/components/WebhookEvents/messages.ts

@@ -37,4 +37,23 @@ export const messages = defineMessages({
     defaultMessage: "Webhook events",
     description: "Webhook events header",
   },
+  directStockModeBadge: {
+    id: "BSGid2",
+    defaultMessage: "Direct stock mode only",
+    description:
+      "Advisory badge shown next to a webhook event in the picker when the event only fires while the shop has the direct (non-legacy) warehouse-channel stock-availability mode enabled.",
+  },
+  directStockModeTooltipBody: {
+    id: "BrRGIJ",
+    defaultMessage:
+      'Fires only while "Use legacy shipping zone stock availability" is disabled in site settings. Otherwise the subscription produces no deliveries.',
+    description:
+      "Tooltip body for the direct-stock-mode-only badge in the webhook event picker. Quotes the exact label of the toggle on the site-settings page so the admin recognizes it when they click through.",
+  },
+  directStockModeTooltipLink: {
+    id: "vh9a5S",
+    defaultMessage: "Open shop settings",
+    description:
+      "Tooltip CTA on the direct-stock-mode-only badge in the webhook event picker. Links to the page where the legacy stock-availability flag can be toggled.",
+  },
 });

src/extensions/components/WebhookDetailsPage/components/WebhookEvents/utils.test.ts

@@ -1,4 +1,10 @@
-import { getWebhookTypes } from "./utils";
+import { WebhookEventTypeAsyncEnum } from "@dashboard/graphql";
+
+import {
+  DIRECT_STOCK_MODE_ONLY_EVENTS,
+  getWebhookTypes,
+  isDirectStockModeOnlyEvent,
+} from "./utils";
 
 const TestKeys = [
   "DRAFT_ORDER_CREATED",
@@ -17,4 +23,63 @@ describe("getWebhookTypes", () => {
     expect(TestWebhookTypes.PRODUCT).toEqual(["CREATED", "UPDATED"]);
     expect(TestWebhookTypes.PRODUCT_VARIANT).toEqual(["UPDATED"]);
   });
+
+  // Regression guard for Saleor 3.23+ channel-scoped variant stock events.
+  // These four events must remain grouped under PRODUCT_VARIANT in the picker
+  // so admins can find them. If the schema removes any of them, or the keyword
+  // grouping logic changes, this test fails loudly instead of silently dropping
+  // the events from the UI.
+  it("groups the Saleor 3.23 channel-scoped stock events under PRODUCT_VARIANT", () => {
+    const types = getWebhookTypes(Object.keys(WebhookEventTypeAsyncEnum));
+
+    expect(types.PRODUCT_VARIANT).toEqual(
+      expect.arrayContaining([
+        "BACK_IN_STOCK_FOR_CLICK_AND_COLLECT",
+        "BACK_IN_STOCK_IN_CHANNEL",
+        "OUT_OF_STOCK_FOR_CLICK_AND_COLLECT",
+        "OUT_OF_STOCK_IN_CHANNEL",
+      ]),
+    );
+  });
+});
+
+describe("isDirectStockModeOnlyEvent", () => {
+  it("returns true for each of the four channel-scoped stock events", () => {
+    expect(
+      isDirectStockModeOnlyEvent(
+        WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_BACK_IN_STOCK_FOR_CLICK_AND_COLLECT,
+      ),
+    ).toBe(true);
+    expect(
+      isDirectStockModeOnlyEvent(
+        WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_BACK_IN_STOCK_IN_CHANNEL,
+      ),
+    ).toBe(true);
+    expect(
+      isDirectStockModeOnlyEvent(
+        WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_OUT_OF_STOCK_FOR_CLICK_AND_COLLECT,
+      ),
+    ).toBe(true);
+    expect(
+      isDirectStockModeOnlyEvent(WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_OUT_OF_STOCK_IN_CHANNEL),
+    ).toBe(true);
+  });
+
+  it("returns false for the legacy (non-channel-scoped) stock events", () => {
+    expect(
+      isDirectStockModeOnlyEvent(WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_BACK_IN_STOCK),
+    ).toBe(false);
+    expect(isDirectStockModeOnlyEvent(WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_OUT_OF_STOCK)).toBe(
+      false,
+    );
+  });
+
+  it("returns false for unrelated events and arbitrary strings", () => {
+    expect(isDirectStockModeOnlyEvent(WebhookEventTypeAsyncEnum.PRODUCT_CREATED)).toBe(false);
+    expect(isDirectStockModeOnlyEvent("NOT_A_REAL_EVENT")).toBe(false);
+  });
+
+  it("exports a set whose size matches the documented count", () => {
+    expect(DIRECT_STOCK_MODE_ONLY_EVENTS.size).toBe(4);
+  });
 });

src/extensions/components/WebhookDetailsPage/components/WebhookEvents/utils.ts

@@ -2,6 +2,28 @@ import { WebhookEventTypeAsyncEnum, WebhookEventTypeSyncEnum } from "@dashboard/
 
 type Actions = string[];
 
+/**
+ * Saleor 3.23 introduced four channel-scoped variant stock-availability events
+ * that fire only when `Shop.useLegacyShippingZoneStockAvailability` is `false`
+ * (i.e. the new direct warehouse-channel stock-availability mode is enabled).
+ * Subscribing to them on a shop still in legacy mode is a silent footgun — the
+ * webhook is saved, but no deliveries are ever produced.
+ *
+ * The picker surfaces a small advisory badge next to each of these events so
+ * admins see the prerequisite at the moment of subscription, regardless of
+ * the shop's current mode. Keep this list in sync with the schema if Saleor
+ * adds further events with the same precondition.
+ */
+export const DIRECT_STOCK_MODE_ONLY_EVENTS: ReadonlySet<WebhookEventTypeAsyncEnum> = new Set([
+  WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_BACK_IN_STOCK_FOR_CLICK_AND_COLLECT,
+  WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_BACK_IN_STOCK_IN_CHANNEL,
+  WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_OUT_OF_STOCK_FOR_CLICK_AND_COLLECT,
+  WebhookEventTypeAsyncEnum.PRODUCT_VARIANT_OUT_OF_STOCK_IN_CHANNEL,
+]);
+
+export const isDirectStockModeOnlyEvent = (eventName: string): boolean =>
+  DIRECT_STOCK_MODE_ONLY_EVENTS.has(eventName as WebhookEventTypeAsyncEnum);
+
 export const getWebhookTypes = (webhookEvents: string[]) => {
   const multiWords = ["DRAFT_ORDER", "GIFT_CARD", "ANY_EVENTS", "PRODUCT_VARIANT"];