feat: composer action metadata (#431)

* feat: composer action metadata * chore: changesets * docs: up * nit: lint
wevm · Jul 22, 2024 · c1f5be4 · c1f5be4
1 parent 302bef8
commit c1f5be4
Show file tree

Hide file tree

Showing 9 changed files with 212 additions and 42 deletions.
diff --git a/.changeset/mighty-pears-collect.md b/.changeset/mighty-pears-collect.md
@@ -0,0 +1,26 @@
+---
+"frog": minor
+---
+
+**Breaking Change**. Composer Action Handlers now require a third argument to define metadata.
+
+```diff
+export const app = new Frog({
+  title: 'Composer Action',
+}).composerAction(
+  '/',
+  async (c) => {
+    if (Math.random() > 0.5) return c.error({ message: 'Action failed :(' })
+    return c.res({
+      title: 'Some Composer Action',
+      url: 'https://example.com',
+    })
+  },
++ {
++   name: 'Some Composer Action',
++   description: 'Cool Composer Action',
++   icon: 'image',
++   imageUrl: 'https://frog.fm/logo-light.svg',
++ },
+)
+```
diff --git a/playground/src/composerAction.tsx b/playground/src/composerAction.tsx
@@ -5,15 +5,19 @@ import { vars } from './ui.js'
 export const app = new Frog({
   ui: { vars },
   title: 'Composer Action',
-}).composerAction('/', async (c) => {
-  console.log(
-    `Composer Action call ${JSON.stringify(c.actionData, null, 2)} from ${
-      c.actionData.fid
-    }`,
-  )
-  // if (Math.random() > 0.5) return c.error({ message: 'Action failed :(' })
-  return c.res({
-    title: 'Some Composer Action',
-    url: 'https://example.com',
-  })
-})
+}).composerAction(
+  '/',
+  async (c) => {
+    if (Math.random() > 0.5) return c.error({ message: 'Action failed :(' })
+    return c.res({
+      title: 'Some Composer Action',
+      url: 'https://example.com',
+    })
+  },
+  {
+    name: 'Some Composer Action',
+    description: 'Cool Composer Action',
+    icon: 'image',
+    imageUrl: 'https://frog.fm/logo-light.svg',
+  },
+)
diff --git a/site/pages/concepts/composer-actions.mdx b/site/pages/concepts/composer-actions.mdx
@@ -39,6 +39,14 @@ app.composerAction(
       title: 'My Composer Action',
       url: 'https://example.com' 
     })
+  },
+  {
+    /* Name of the action – 14 characters max. */
+    name: 'Some Composer Action',
+    /* Description of the action – 20 characters max. */
+    description: 'Cool Composer Action',
+    icon: 'image',
+    imageUrl: 'https://frog.fm/logo-light.svg',
   }
 )
 ```

diff --git a/site/pages/reference/frog-composer-action-response.mdx b/site/pages/reference/frog-composer-action-response.mdx
@@ -13,6 +13,7 @@ app.composerAction('/', (c) => {
       // ... // [!code focus]
     }) // [!code focus]
   },
+  { /* options */ }
 )
 ```
 
@@ -35,6 +36,7 @@ app.composerAction('/', (c) => {
       url: 'https://example.com'
     })
   },
+  { /* options */ }
 )
 ```
 
@@ -57,5 +59,6 @@ app.composerAction('/', (c) => {
       url: 'https://example.com' // [!code focus]
     })
   },
+  { /* options */ }
 )
 ```
diff --git a/site/pages/reference/frog-composer-action.mdx b/site/pages/reference/frog-composer-action.mdx
@@ -15,12 +15,21 @@ import { Frog } from 'frog'
 
 const app = new Frog({ title: 'Frog Frame' })
 
-app.composerAction('/', (c) => { // [!code focus]
-  return c.res({
-    title: 'My Composr Action', // [!code focus]
-    url: 'https://example.com' // [!code focus]
-  }) // [!code focus]
-}) // [!code focus]
+app.composerAction( // [!code focus]
+  '/', // [!code focus]
+  (c) => { // [!code focus]
+    return c.res({
+      title: 'My Composr Action', // [!code focus]
+      url: 'https://example.com' // [!code focus]
+    }) // [!code focus]
+  }, // [!code focus]
+  { // [!code focus]
+    name: 'Some Composer Action', // [!code focus]
+    description: 'Cool Composer Action', // [!code focus]
+    icon: 'image', // [!code focus]
+    imageUrl: 'https://frog.fm/logo-light.svg', // [!code focus]
+  } // [!code focus]
+) // [!code focus]
 ```
 
 ## Parameters
@@ -47,6 +56,12 @@ app.composerAction(
       title: 'My Composr Action',
       url: 'https://example.com'
     })
+  },
+  {
+    name: 'Some Composer Action',
+    description: 'Cool Composer Action',
+    icon: 'image',
+    imageUrl: 'https://frog.fm/logo-light.svg',
   }
 )
 ```
@@ -71,6 +86,42 @@ app.composerAction(
       title: 'My Composr Action', // [!code focus]
       url: 'https://example.com' // [!code focus]
     }) // [!code focus]
+  }, // [!code focus]
+  {
+    name: 'Some Composer Action',
+    description: 'Cool Composer Action',
+    icon: 'image',
+    imageUrl: 'https://frog.fm/logo-light.svg',
+  }
+)
+```
+
+### options
+
+- **Type:** `RouteOptions<'composerAction'>`
+
+Options for Composer Action
+
+```tsx twoslash
+/** @jsxImportSource frog/jsx */
+// ---cut---
+import { Frog } from 'frog'
+
+const app = new Frog({ title: 'Frog Frame' })
+
+app.composerAction(
+  '/',
+  (c) => {
+    return c.res({
+      title: 'My Composr Action',
+      url: 'https://example.com'
+    })
+  },
+  { // [!code focus]
+    name: 'Some Composer Action', // [!code focus]
+    description: 'Cool Composer Action', // [!code focus]
+    icon: 'image', // [!code focus]
+    imageUrl: 'https://frog.fm/logo-light.svg', // [!code focus]
   } // [!code focus]
 )
 ```

diff --git a/src/frog-base.tsx b/src/frog-base.tsx
@@ -12,6 +12,7 @@ import lz from 'lz-string'
 import { default as p } from 'path-browserify'
 
 import type { CastActionOptions } from './types/castAction.js'
+import type { ComposerActionOptions } from './types/composerAction.js'
 import type { Env } from './types/env.js'
 import type {
   FrameImageAspectRatio,
@@ -209,7 +210,19 @@ export type RouteOptions<
                 c: Context<E, P, I>,
               ) => Promise<CastActionOptions> | CastActionOptions
             }
-      : {})
+      : method extends 'composerAction'
+        ?
+            | ComposerActionOptions
+            | {
+                /**
+                 * Custom handler for Composer Action `GET` response.
+                 * One can use that if something needs to be derived from the `Context`.
+                 */
+                handler: (
+                  c: Context<E, P, I>,
+                ) => Promise<ComposerActionOptions> | ComposerActionOptions
+              }
+        : {})
 
 /**
  * A Frog instance.
@@ -436,14 +449,47 @@ export class FrogBase<
   composerAction: HandlerInterface<env, 'composerAction', schema, basePath> = (
     ...parameters: any[]
   ) => {
-    const [path, middlewares, handler, options = {}] = getRouteParameters<
+    const [path, middlewares, handler, options] = getRouteParameters<
       env,
       ComposerActionHandler<env>,
       'composerAction'
     >(...parameters)
 
     const { verify = this.verify } = options
 
+    // Composer Action Route (implements GET).
+    if ('handler' in options) {
+      this.hono.get(parseHonoPath(path), ...middlewares, async (c) => {
+        const { aboutUrl, name, description, icon, imageUrl } =
+          await options.handler(c)
+        return c.json({
+          aboutUrl,
+          action: {
+            type: 'post',
+          },
+          description,
+          icon,
+          imageUrl,
+          name,
+        })
+      })
+    } else {
+      const { aboutUrl, name, description, icon, imageUrl } = options
+
+      this.hono.get(parseHonoPath(path), ...middlewares, async (c) => {
+        return c.json({
+          aboutUrl,
+          action: {
+            type: 'post',
+          },
+          description,
+          icon,
+          imageUrl,
+          name,
+        })
+      })
+    }
+
     // Composer Action Route (implements POST).
     this.hono.post(parseHonoPath(path), ...middlewares, async (c) => {
       const { context } = getComposerActionContext<env, string>({

diff --git a/src/types/composerAction.ts b/src/types/composerAction.ts
@@ -1,5 +1,37 @@
+import type { CastActionOptions } from './castAction.js'
 import type { TypedResponse } from './response.js'
 
+export type ComposerActionOptions = {
+  /**
+   * Optional external link to an "about" page.
+   * You should only include this if you can't fully describe your
+   * action using the `description` field.
+   * Must be http or https protocol.
+   *
+   * @example `'https://somewhere.com'`
+   */
+  aboutUrl?: CastActionOptions['aboutUrl']
+  /**
+   * A short description up to 20 characters.
+   *
+   * @example `'My awesome action description.'`
+   */
+  description: NonNullable<CastActionOptions['description']>
+  icon: CastActionOptions['icon']
+  /**
+   * Remote image URL.
+   *
+   * @example `'https://somewhere.com/image.png'`
+   */
+  imageUrl: string
+  /**
+   * An action name up to 14 characters.
+   *
+   * @example `'My action.'`
+   */
+  name: CastActionOptions['name']
+}
+
 export type ComposerActionResponse = {
   /**
    * Title of the action.