From f289b7acc5078df7599d83e09b754d3dc79c4a6a Mon Sep 17 00:00:00 2001 From: Leonardo Zizzamia Date: Fri, 23 Feb 2024 17:21:02 -0800 Subject: [PATCH 1/2] docs: polish getFrameMessage types --- site/docs/pages/frame/get-frame-message.mdx | 107 ++++++++------------ site/docs/pages/frame/types.mdx | 42 ++++++++ 2 files changed, 85 insertions(+), 64 deletions(-) diff --git a/site/docs/pages/frame/get-frame-message.mdx b/site/docs/pages/frame/get-frame-message.mdx index 8eed5956d0..713c98df0d 100644 --- a/site/docs/pages/frame/get-frame-message.mdx +++ b/site/docs/pages/frame/get-frame-message.mdx @@ -1,90 +1,69 @@ # 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[] +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. 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/frame'; +import { FrameRequest, getFrameMessage } from '@coinbase/onchainkit/frame'; // [!code focus] import { NextRequest, NextResponse } from 'next/server'; async function getResponse(req: NextRequest): Promise { - // 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 + const frameRequest: FrameRequest = await req.json(); + const { isValid, message } = await getFrameMessage(frameRequest); // [!code focus] + 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 { - return getResponse(req); -} ``` ## Returns +[`Promise`](/frame/types#framevalidationresponse) + +## Parameters + +### FrameRequest + +- [`FrameRequest`](/frame/types#framerequest) + +### options.neynarApiKey + +- **Type:** `string` + +Default to OnchainKit's default key. + ```ts -type Promise; - -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 -} +const { isValid, message } = await getFrameMessage(frameRequest, { + neynarApiKey: 'MY_NEYNAR_API_KEY', // [!code focus] +}); ``` -## Parameters +### options.castReactionContext + +- **Type:** `boolean` + +Whether to cast the reaction context. Default: true + +```ts +const { isValid, message } = await getFrameMessage(frameRequest, { + castReactionContext: true, // [!code focus] +}); +``` + +### options.followContext + +- **Type:** `boolean` + +// Whether to follow the context. Default: true ```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; +const { isValid, message } = await getFrameMessage(frameRequest, { + followContext: true, // [!code focus] +}); ``` diff --git a/site/docs/pages/frame/types.mdx b/site/docs/pages/frame/types.mdx index 24d3bee79c..48d2561767 100644 --- a/site/docs/pages/frame/types.mdx +++ b/site/docs/pages/frame/types.mdx @@ -70,3 +70,45 @@ type FrameMetadataType = { refreshPeriod?: number; }; ``` + +## `FrameRequest` + +```ts +interface FrameRequest { + untrustedData: FrameData; + trustedData: { + messageBytes: string; + }; +} +``` + +## `FrameValidationData` + +```ts +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 + verified_addresses: { + eth_addresses: string[] | null; + sol_addresses: string[] | null; + }; + }; + 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 +} +``` + +## `FrameValidationResponse` + +```ts +type FrameValidationResponse = + | { isValid: true; message: FrameValidationData } + | { isValid: false; message: undefined }; +``` From 63c140382274bc7d4196df1ee94087fba3f79955 Mon Sep 17 00:00:00 2001 From: Leonardo Zizzamia Date: Fri, 23 Feb 2024 17:22:33 -0800 Subject: [PATCH 2/2] dope --- site/docs/pages/frame/get-frame-message.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/pages/frame/get-frame-message.mdx b/site/docs/pages/frame/get-frame-message.mdx index 713c98df0d..986b798d8b 100644 --- a/site/docs/pages/frame/get-frame-message.mdx +++ b/site/docs/pages/frame/get-frame-message.mdx @@ -60,7 +60,7 @@ const { isValid, message } = await getFrameMessage(frameRequest, { - **Type:** `boolean` -// Whether to follow the context. Default: true +Whether to follow the context. Default: true ```ts const { isValid, message } = await getFrameMessage(frameRequest, {