feat: add an optional link property to action response (#293)

* feat: add an optional `link` property to action response

[See more](https://docs.farcaster.xyz/reference/actions/spec#message-response-type).

* chore: changesets

* nit: tweak

* docs: update

* chore: up

---------

Co-authored-by: Tom Meagher <tom@meagher.co>

.changeset/sour-tables-happen.md

@@ -0,0 +1,6 @@
+---
+"frog": patch
+---
+
+Added `link` property to `CastActionMessageResponse` to display the toasted message as an external link to the specified URL.
+[See more](https://docs.farcaster.xyz/reference/actions/spec#message-response-type).

playground/src/castAction.tsx

@@ -57,7 +57,10 @@ export const app = new Frog({
         }`,
       )
       if (Math.random() > 0.5) return c.error({ message: 'Action failed :(' })
-      return c.message({ message: 'Action Succeeded' })
+      return c.message({
+        message: 'Action Succeeded',
+        link: 'https://frog.fm',
+      })
     },
     {
       name: 'Log This!',

site/pages/reference/frog-cast-action-response.mdx

@@ -35,7 +35,7 @@ app.castAction('/action/foo', (c) => {
       'Cache-Control': 'max-age=0', // [!code focus]
     }, // [!code focus]
     message: 'Success!',
-    statusCode: 200
+    statusCode: 200,
   })
 })
 ```
@@ -56,7 +56,35 @@ export const app = new Frog()
 app.castAction('/', (c) => {
   return c.res({
     message: 'Action Succeeded!', // [!code focus]
-    statusCode: 200
+    statusCode: 200,
+  })
+})
+```
+
+## link
+#
+:::warning
+The `link` property is valid to be added only in response with HTTP status 200.
+Thus you cannot add one in `.error()` response.
+:::
+
+- **Type:** `string | undefined`
+
+An optional URL. Must be http:// or https:// protocol.
+If present, clients must display the message as an external link to this URL.
+
+```tsx twoslash
+/** @jsxImportSource frog/jsx */
+// ---cut---
+import { Button, Frog } from 'frog'
+
+export const app = new Frog()
+
+app.castAction('/', (c) => {
+  return c.res({
+    message: 'Action Succeeded!',
+    link: 'https://frog.fm', // [!code focus]
+    statusCode: 200,
   })
 })
 ```
@@ -78,7 +106,7 @@ export const app = new Frog()
 app.castAction('/', (c) => {
   return c.res({
     message: 'Action Succeeded!',
-    statusCode: 200 // [!code focus]
+    statusCode: 200, // [!code focus]
   })
 })
 ```

src/frog-base.tsx

@@ -329,15 +329,14 @@ export class FrogBase<
       const origin = this.origin ?? url.origin
       const baseUrl = origin + parsePath(this.basePath)
 
-      if (c.req.method === 'GET') {
+      if (c.req.method === 'GET')
         return c.json({
           ...installParameters,
           postUrl: baseUrl + parsePath(path),
           action: {
             type: 'post',
           },
         })
-      }
 
       const { context } = getCastActionContext<env, string>({
         context: await requestBodyToContext(c, {
@@ -366,9 +365,8 @@ export class FrogBase<
         })
       }
 
-      const { message } = response.data
-
-      return c.json({ message, type: 'message' })
+      const { message, link } = response.data
+      return c.json({ message, link, type: 'message' })
     })
 
     return this

src/types/castAction.ts

@@ -20,6 +20,10 @@ export type CastActionMessageResponse = {
    * @example 'Action succeded!'
    */
   message: string
+  /**
+   * If present, clients must display the message as an external link to this URL.
+   */
+  link?: string | undefined
 }
 
 export type CastActionMessageResponseFn = (