docs: updated Frame Kit (#138)

README.md

@@ -54,11 +54,11 @@ For documentation and guides, visit [onchainkit.xyz](https://onchainkit.xyz/).
 - [Frame Kit](https://onchainkit.xyz/framekit/introduction)
 
   - Components:
-    - [`<FrameMetadata />`](https://onchainkit.xyz/framekit/introduction#framemetadata-)
+    - [`<FrameMetadata />`](https://onchainkit.xyz/framekit/frame-metadata)
   - Utilities:
-    - [`getFrameHtmlResponse`](https://onchainkit.xyz/framekit/introduction#getframehtmlresponseframemetadata)
-    - [`getFrameMessage`](https://onchainkit.xyz/framekit/introduction#getframemessageframerequest)
-    - [`getFrameMetadata`](https://onchainkit.xyz/framekit/introduction#getframemetadataframemetadata)
+    - [`getFrameHtmlResponse`](https://onchainkit.xyz/framekit/get-frame-html-response)
+    - [`getFrameMessage`](https://onchainkit.xyz/framekit/get-frame-message)
+    - [`getFrameMetadata`](https://onchainkit.xyz/framekit/get-frame-metadata)
 
 - [Identity Kit](https://onchainkit.xyz/identitykit/introduction)
   - Components:

site/docs/pages/framekit/frame-metadata.mdx

@@ -0,0 +1,97 @@
+# `<FrameMetadata />`
+
+This component is utilized for incorporating Frame metadata elements into the React page.
+
+Note: If you are using Next.js with App routing, it is recommended to use `getFrameMetadata` instead.
+
+## Usage
+
+```tsx
+export default function HomePage() {
+  return (
+    ...
+    <FrameMetadata
+      buttons={[
+        {
+          label: 'Tell me the story',
+        },
+        {
+          action: 'link',
+          label: 'Link to Google',
+          target: 'https://www.google.com'
+        },
+        {
+          action: 'post_redirect',
+          label: 'Redirect to cute pictures',
+        },
+      ]}
+      image={{
+       src: 'https://zizzamia.xyz/park-3.png',
+       aspectRatio: '1:1'
+      }}
+      input={{
+        text: 'Tell me a boat story',
+      }}
+      postUrl="https://zizzamia.xyz/api/frame"
+    />
+    ...
+  );
+}
+```
+
+## Returns
+
+```html
+<meta name="fc:frame" content="vNext" />
+<meta name="fc:frame:button:1" content="Tell me the story" />
+<meta name="fc:frame:button:2" content="Link to Google" />
+<meta name="fc:frame:button:2:action" content="link" />
+<meta name="fc:frame:button:2:target" content="https://www.google.com" />
+<meta name="fc:frame:button:3" content="Redirect to cute pictures" />
+<meta name="fc:frame:button:3:action" content="post_redirect" />
+<meta name="fc:frame:image" content="https://zizzamia.xyz/park-3.png" />
+<meta name="fc:frame:image:aspect_ratio" content="1:1" />
+<meta name="fc:frame:input:text" content="Tell me a boat story" />
+<meta name="fc:frame:post_url" content="https://zizzamia.xyz/api/frame" />
+```
+
+## Props
+
+```ts
+type FrameButtonMetadata =
+  | {
+      action: 'link' | 'mint';
+      label: string;
+      target: string;
+    }
+  | {
+      action?: 'post' | 'post_redirect';
+      label: string;
+    };
+
+type FrameImageMetadata = {
+  src: string;
+  aspectRatio?: '1.91:1' | '1:1';
+};
+
+type FrameInputMetadata = {
+  text: string;
+};
+
+type FrameMetadataType = {
+  // A list of strings which are the label for the buttons in the frame (max 4 buttons).
+  buttons?: [FrameButtonMetadata, ...FrameButtonMetadata[]];
+  // An image which must be smaller than 10MB and should have an aspect ratio of 1.91:1 or 1:1
+  image: FrameImageMetadata;
+  // The text input to use for the Frame.
+  input?: FrameInputMetadata;
+  // A valid POST URL to send the Signature Packet to.
+  postUrl?: string;
+  // A period in seconds at which the app should expect the image to update.
+  refreshPeriod?: number;
+};
+
+type FrameMetadataReact = FrameMetadataType & {
+  wrapper?: React.ComponentType<any>;
+};
+```

site/docs/pages/framekit/get-frame-html-response.mdx

@@ -0,0 +1,78 @@
+# getFrameHtmlResponse
+
+When you need to send an HTML Frame Response, the `getFrameHtmlResponse` method is here to assist you.
+
+It generates a valid HTML string response with a frame and utilizes `FrameMetadata` types for page metadata. This eliminates the need to manually create server-side HTML strings.
+
+## Usage
+
+```ts
+// Step 1. import getFrameHtmlResponse from @coinbase/onchainkit
+import { getFrameHtmlResponse } from '@coinbase/onchainkit';
+import { NextRequest, NextResponse } from 'next/server';
+
+async function getResponse(req: NextRequest): Promise<NextResponse> {
+  // Step 2. Build your Frame logic
+  ...
+
+  return new NextResponse(
+    // Step 3. Use getFrameHtmlResponse to create a Frame response
+    getFrameHtmlResponse({
+      buttons: [
+        {
+          label: `We love BOAT`,
+        },
+      ],
+      image: 'https://build-onchain-apps.vercel.app/release/v-0-17.png',
+      postUrl: 'https://build-onchain-apps.vercel.app/api/frame',
+    }),
+  );
+}
+
+export async function POST(req: NextRequest): Promise<Response> {
+  return getResponse(req);
+}
+```
+
+## Returns
+
+```ts
+type FrameHTMLResponse = string;
+```
+
+## Parameters
+
+```ts
+type FrameButtonMetadata =
+  | {
+      action: 'link' | 'mint';
+      label: string;
+      target: string;
+    }
+  | {
+      action?: 'post' | 'post_redirect';
+      label: string;
+    };
+
+type FrameImageMetadata = {
+  src: string;
+  aspectRatio?: '1.91:1' | '1:1';
+};
+
+type FrameInputMetadata = {
+  text: string;
+};
+
+type FrameMetadataType = {
+  // A list of strings which are the label for the buttons in the frame (max 4 buttons).
+  buttons?: [FrameButtonMetadata, ...FrameButtonMetadata[]];
+  // An image which must be smaller than 10MB and should have an aspect ratio of 1.91:1 or 1:1
+  image: FrameImageMetadata;
+  // The text input to use for the Frame.
+  input?: FrameInputMetadata;
+  // A valid POST URL to send the Signature Packet to.
+  postUrl?: string;
+  // A period in seconds at which the app should expect the image to update.
+  refreshPeriod?: number;
+};
+```

site/docs/pages/framekit/get-frame-message.mdx

@@ -0,0 +1,90 @@
+# getFrameMessage
+
+When a user interacts with your Frame, you receive a JSON message called the "Frame Signature Packet". Decode and validate this message using the `getFrameMessage` function.
+
+You can also use `getFrameMessage` to access useful information such as:
+
+- button: number
+- fid: number
+- following: boolean
+- liked: boolean
+- recasted: boolean
+- verified_accounts: string[]
+
+Note that if the `message` is not valid, it will be undefined.
+
+## Usage
+
+```ts
+// Step 1. import getFrameMessage from @coinbase/onchainkit
+import { FrameRequest, getFrameMessage } from '@coinbase/onchainkit';
+import { NextRequest, NextResponse } from 'next/server';
+
+async function getResponse(req: NextRequest): Promise<NextResponse> {
+  // Step 2. Read the body from the Next Request
+  const body: FrameRequest = await req.json();
+  // Step 3. Validate the message
+  const { isValid, message } = await getFrameMessage(body , {
+    neynarApiKey: 'NEYNAR_ONCHAIN_KIT'
+  });
+
+  // Step 4. Determine the experience based on the validity of the message
+  if (isValid) {
+    // the message is valid
+  } else {
+    // sorry, the message is not valid and it will be undefined
+  }
+
+  ...
+}
+
+export async function POST(req: NextRequest): Promise<Response> {
+  return getResponse(req);
+}
+```
+
+## Returns
+
+```ts
+type Promise<FrameValidationResponse>;
+
+type FrameValidationResponse =
+  | { isValid: true; message: FrameValidationData }
+  | { isValid: false; message: undefined };
+
+interface FrameValidationData {
+  button: number; // Number of the button clicked
+  following: boolean; // Indicates if the viewer clicking the frame follows the cast author
+  input: string; // Text input from the viewer typing in the frame
+  interactor: {
+    fid: number; // Viewer Farcaster ID
+    custody_address: string; // Viewer custody address
+    verified_accounts: string[]; // Viewer account addresses
+  };
+  liked: boolean; // Indicates if the viewer clicking the frame liked the cast
+  raw: NeynarFrameValidationInternalModel;
+  recasted: boolean; // Indicates if the viewer clicking the frame recasted the cast
+  valid: boolean; // Indicates if the frame is valid
+}
+```
+
+## Parameters
+
+```ts
+// The Frame Signature Packet body
+type FrameMessage = {
+  body: FrameRequest;
+  messageOptions?: FrameMessageOptions;
+};
+
+type FrameMessageOptions =
+  | {
+      // The API key to use for validation. Default: NEYNAR_ONCHAIN_KIT
+      neynarApiKey?: string;
+      // Whether to cast the reaction context. Default: true
+      castReactionContext?: boolean;
+      // Whether to follow the context. Default: true
+      followContext?: boolean;
+    }
+  | undefined;
+```

site/docs/pages/framekit/get-frame-metadata.mdx

@@ -0,0 +1,78 @@
+# getFrameMetadata
+
+With Next.js App routing, use the `getFrameMetadata()` inside your `page.ts` to get the metadata need it for your Frame.
+
+## Usage
+
+```ts
+// Step 1. import getFrameMetadata from @coinbase/onchainkit
+import { getFrameMetadata } from '@coinbase/onchainkit';
+import type { Metadata } from 'next';
+import HomePage from './home';
+
+// Step 2. Use getFrameMetadata to shape your Frame metadata
+const frameMetadata = getFrameMetadata({
+  buttons: [
+    {
+      label: 'We love BOAT',
+    },
+  ],
+  image: 'https://build-onchain-apps.vercel.app/release/v-0-17.png',
+  postUrl: 'https://build-onchain-apps.vercel.app/api/frame',
+});
+
+// Step 3. Add your metadata in the Next.js metadata utility
+export const metadata: Metadata = {
+  manifest: '/manifest.json',
+  other: {
+    ...frameMetadata
+  },
+};
+
+export default function Page() {
+  return <HomePage />;
+}
+```
+
+## Returns
+
+```ts
+type FrameMetadataResponse = Record<string, string>;
+```
+
+## Parameters
+
+```ts
+type FrameButtonMetadata =
+  | {
+      action: 'link' | 'mint';
+      label: string;
+      target: string;
+    }
+  | {
+      action?: 'post' | 'post_redirect';
+      label: string;
+    };
+
+type FrameImageMetadata = {
+  src: string;
+  aspectRatio?: '1.91:1' | '1:1';
+};
+
+type FrameInputMetadata = {
+  text: string;
+};
+
+type FrameMetadataType = {
+  // A list of strings which are the label for the buttons in the frame (max 4 buttons).
+  buttons?: [FrameButtonMetadata, ...FrameButtonMetadata[]];
+  // An image which must be smaller than 10MB and should have an aspect ratio of 1.91:1
+  image: FrameImageMetadata;
+  // The text input to use for the Frame.
+  input?: FrameInputMetadata;
+  // A valid POST URL to send the Signature Packet to.
+  postUrl?: string;
+  // A period in seconds at which the app should expect the image to update.
+  refreshPeriod?: number;
+};
+```