From 6c9b338ad5926e17083cb60bef90cb98193b4fd1 Mon Sep 17 00:00:00 2001
From: Sacha Al Himdani <sacha@getprobo.com>
Date: Tue, 17 Mar 2026 16:33:37 +0100
Subject: [PATCH] Deprecate useMutationWithToasts and promisifyMutation

Update relay agent rules to mark both helpers as deprecated.
Replace examples with the preferred pattern: useMutation with
onCompleted/onError callbacks and useToast.

Signed-off-by: Sacha Al Himdani <sacha@getprobo.com>
---
 contrib/claude/relay.md | 74 ++++++++++++++++++++++++++---------------
 1 file changed, 48 insertions(+), 26 deletions(-)

diff --git a/contrib/claude/relay.md b/contrib/claude/relay.md
index fa21dc4aa..2b6cac7f0 100644
--- a/contrib/claude/relay.md
+++ b/contrib/claude/relay.md
@@ -137,34 +137,47 @@ The `@connection(key: "...", filters: [...])` directive on the fragment tells Re
 Direct Relay hook for simple cases:
 
 ```tsx
-const [mutate] = useMutation<VendorGraphDeleteMutation>(deleteVendorMutation);
+const [deleteVendor] = useMutation<VendorGraphDeleteMutation>(deleteVendorMutation);
 ```
 
-### `useMutationWithToasts`
-
-Custom wrapper that adds toast notifications on success/error:
+For mutations with user feedback, combine with `useToast` and use `onCompleted`/`onError` callbacks:
 
 ```tsx
-const [createContact, isLoading] = useMutationWithToasts(
-  createContactMutation,
-  {
-    successMessage: __("Contact created successfully."),
-    errorMessage: __("Failed to create contact"),
-  },
-);
+const { toast } = useToast();
+const [createObligation, isCreating] = useMutation<CreateObligationMutation>(createObligationMutation);
 
-await createContact({
-  variables: {
-    input: { vendorId, ...cleanData },
-    connections: [connectionId],
-  },
-  onSuccess: () => {
-    dialogRef.current?.close();
-    reset();
-  },
-});
+const onSubmit = (formData: FormData) => {
+  createObligation({
+    variables: {
+      input: { ...formData },
+      connections: [connectionId],
+    },
+    onCompleted() {
+      toast({
+        title: __("Success"),
+        description: __("Obligation created successfully"),
+        variant: "success",
+      });
+    },
+    onError(error) {
+      toast({
+        title: __("Error"),
+        description: formatError(__("Failed to create obligation"), error as GraphQLError),
+        variant: "error",
+      });
+    },
+  });
+};
 ```
 
+### `useMutationWithToasts` (deprecated)
+
+**Do not use.** Use `useMutation` combined with `useToast` instead.
+
+### `promisifyMutation` (deprecated)
+
+**Do not use.** Use `useMutation` with `onCompleted`/`onError` callbacks instead of wrapping in a promise.
+
 ### Store update directives
 
 Relay directives handle connection updates automatically — no manual store manipulation needed:
@@ -213,15 +226,24 @@ Destructive mutations (delete) are wrapped with a confirmation dialog:
 
 ```tsx
 const confirm = useConfirm();
+const [deleteVendor] = useMutation<DeleteVendorMutation>(deleteVendorMutation);
 
 return () => {
   confirm(
     () =>
-      promisifyMutation(mutate)({
-        variables: {
-          input: { vendorId: vendor.id! },
-          connections: [connectionId],
-        },
+      new Promise<void>((resolve) => {
+        deleteVendor({
+          variables: {
+            input: { vendorId: vendor.id! },
+            connections: [connectionId],
+          },
+          onCompleted() {
+            resolve();
+          },
+          onError() {
+            resolve();
+          },
+        });
       }),
     { message: "Confirm deletion..." },
   );