feat: multi-step cast actions

.changeset/purple-pants-eat.md

@@ -0,0 +1,8 @@
+---
+"frog": minor
+---
+
+Implemented multi-step cast actions. [See more](https://warpcast.notion.site/Frames-Multi-step-actions-f469054de8fb4ffc8b8e2649a41b6ad9?pvs=74).
+
+Breaking changes have affected `.castAction` handler definition and its response:
+- `.castAction` handler response now requires a `"type": "message" | "frame"` to be specified. Shorthands `c.message(...)` and `c.frame(...)` were added for the ease of use.

playground/src/castAction.tsx

@@ -1,7 +1,10 @@
-import { Frog } from 'frog'
-import { Button } from 'frog'
+import { Button, Frog, TextInput } from 'frog'
 
-export const app = new Frog()
+import { Box, Heading, vars } from './ui.js'
+
+export const app = new Frog({
+  ui: { vars },
+})
   .frame('/', (c) =>
     c.res({
       image: (
@@ -36,24 +39,81 @@ export const app = new Frog()
         </div>
       ),
       intents: [
-        <Button.AddCastAction action="/action">Add</Button.AddCastAction>,
+        <Button.AddCastAction action="/action-message">
+          Message
+        </Button.AddCastAction>,
+        <Button.AddCastAction action="/action-frame">
+          Frame
+        </Button.AddCastAction>,
       ],
     }),
   )
   .castAction(
-    '/action',
+    '/action-message',
     async (c) => {
       console.log(
         `Cast Action to ${JSON.stringify(c.actionData.castId)} from ${
           c.actionData.fid
         }`,
       )
       if (Math.random() > 0.5) return c.error({ message: 'Action failed :(' })
-      return c.res({ message: 'Action Succeeded' })
+      return c.message({ message: 'Action Succeeded' })
     },
     {
       name: 'Log This!',
       icon: 'log',
-      description: 'This cast action will log something!',
+      description: 'This cast action will log something and return a message!',
     },
   )
+  .castAction(
+    '/action-frame',
+    async (c) => {
+      console.log(
+        `Cast Action to ${JSON.stringify(c.actionData.castId)} from ${
+          c.actionData.fid
+        }`,
+      )
+      if (Math.random() > 0.5) return c.error({ message: 'Action failed :(' })
+
+      return c.frame({
+        path: '/action-frame-response',
+      })
+    },
+    {
+      name: 'Log This!',
+      icon: 'log',
+      description: 'This cast action will log something and invoke a frame!',
+    },
+  )
+  .frame('/action-frame-response', async (c) => {
+    const { buttonValue, inputText, status } = c
+    const fruit = inputText || buttonValue
+    return c.res({
+      action: '/action',
+      image: (
+        <Box
+          grow
+          background={
+            status === 'response'
+              ? { custom: 'linear-gradient(to right, #432889, #17101F)' }
+              : 'background'
+          }
+          alignHorizontal="center"
+          alignVertical="center"
+        >
+          <Heading style="italic">
+            {status === 'response'
+              ? `Nice choice.${fruit ? ` ${fruit.toUpperCase()}!!` : ''}`
+              : 'Cast Action Frame Response 🐸'}
+          </Heading>
+        </Box>
+      ),
+      intents: [
+        <TextInput placeholder="Enter custom fruit" />,
+        <Button value="apples">Apples</Button>,
+        <Button value="oranges">Oranges</Button>,
+        <Button value="bananas">Bananas</Button>,
+        status === 'response' && <Button.Reset>Reset</Button.Reset>,
+      ],
+    })
+  })

site/pages/concepts/cast-actions.mdx

@@ -8,7 +8,7 @@ At a glance:
 
 1. User installs Cast Action via specific deeplink or by clicking on `<Button.AddCastAction>{:jsx}` element with a specified target `.castAction` route in a Frame.
 2. When the user presses the Cast Action button in the App, the App will make a `POST` request to the `.castAction` route.
-3. Frame performs any action and returns a response to the App.
+3. Server performs any action and returns a response to the App which is shown as a toast.
 
 ## Walkthrough
 
@@ -48,7 +48,7 @@ app.castAction(
         c.actionData.fid
       }`,
     )
-    return c.res({ message: 'Action Succeeded' })
+    return c.res({ type: 'message', message: 'Action Succeeded' })
   },
   { name: "Log This!", icon: "log" })
 )
@@ -126,27 +126,65 @@ app.frame('/', (c) => {
   })
 })
 
-app.castAction(
+app.castAction( // [!code focus]
   '/log-this',  // [!code focus]
   (c) => { // [!code focus]
     console.log( // [!code focus]
       `Cast Action to ${JSON.stringify(c.actionData.castId)} from ${ // [!code focus]
         c.actionData.fid // [!code focus]
       }`, // [!code focus]
     ) // [!code focus]
-    return c.res({ message: 'Action Succeeded' }) // [!code focus]
+    return c.res({ type: 'message', message: 'Action Succeeded' }) // [!code focus]
   }, // [!code focus]
   { name: "Log This!", icon: "log" }) // [!code focus]
 ) // [!code focus]
 ```
 
 A breakdown of the `/log-this` route handler:
 
-- `c.actionData` is never nullable and is always defined since Cast Actions always do `POST` request.
 - We are responding with a `c.res` response and specifying a `message` that will appear in the success toast.
 
+### 3. Bonus: Shorthand `c.message`
+
+Instead of `c.res({ type: 'message' })`, you can use a shorthand `c.message(...)`.
+
+```tsx twoslash [src/index.tsx]
+// @noErrors
+app.castAction(
+  '/log-this',
+  (c) => {
+    console.log(
+      `Cast Action to ${JSON.stringify(c.actionData.castId)} from ${
+        c.actionData.fid
+      }`,
+    ) 
+    return c.message({ message: 'Action Succeeded' }) // [!code focus]
+  }, 
+  { name: "Log This!", icon: "log" })
+)
+```
+
+### 4. Bonus: Returning an error
+
+You can return an error response for a Client to render an error toast by using `c.error`.
+
+```tsx twoslash [src/index.tsx]
+// @noErrors
+app.castAction(
+  '/log-this',
+  (c) => {
+    console.log(
+      `Cast Action to ${JSON.stringify(c.actionData.castId)} from ${
+        c.actionData.fid
+      }`,
+    ) 
+    return c.error({ message: 'Action Failed' }) // [!code focus]
+  }, 
+  { name: "Log This!", icon: "log" })
+)
+```
 
-### 3. Bonus: Learn the API
+### 5. Bonus: Learn the API
 
 You can learn more about the transaction APIs here: