Merge pull request #6 from fabriguespe/command_v1

Commands update

examples/gm/src/commands.ts

@@ -0,0 +1,13 @@
+export const commands = [
+  {
+    name: "General Commands",
+    icon: "🔧",
+    description: "Command for managing default behaviours.",
+    commands: [
+      {
+        command: "/help",
+        description: "Get help with the bot.",
+      },
+    ],
+  },
+];

packages/docs/docs/pages/commands.mdx

@@ -0,0 +1,37 @@
+# Commands
+
+Each bot can have a `commands.ts` file that contains the commands that the bot can execute. The commands are defined as an array of objects with the following keys:
+
+```tsx
+export const commands = [
+  {
+    name: "General Commands",
+    icon: "🔧",
+    description: "Command for managing default behaviours.",
+    commands: [
+      {
+        command: "/help",
+        description: "Get help with the bot.",
+      },
+    ],
+  },
+];
+```
+
+### Declare commands
+
+To declare the access command in the botkit app, you need to add the following code:
+
+```tsx
+import { commands } from "./commands.js";
+
+const newBotConfig = {
+  context: {
+    commands: commands,
+  },
+};
+
+run(async (context: HandlerContext) => {
+  //Your logic here
+}, newBotConfig);
+```

packages/docs/docs/pages/open-frames/tutorials/subscribe.mdx

@@ -0,0 +1,320 @@
+# Subscribe in Open Frames
+
+### Sections:
+
+1. **How to render a subscribe Open Frame**: Learn the steps to display subscribe frames within your application.
+2. **Building a subscribe frame**: Implement the method to construct and manage subscribe frames.
+
+---
+
+## Support a subscribe Open Frame in an app built with XMTP
+
+In this guide, we will walk through the process of supporting subscribe Open Frames in your application using XMTP. Each section provides step-by-step instructions to integrate this functionality.
+
+### Determine if an Open Frame is a subscribe frame
+
+Subscriptions via a frame are triggered using button-click events and are a type of transactional frame. Therefore, the best way to determine if an Open Frame is a subscribe frame begins with the same first step as a typical transactional frame: looking for a button `action` set to `tx` in the frame metadata. For example:
+
+```jsx
+import { OpenFramesProxy } from "@xmtp/frames-client";
+
+const proxy = new OpenFramesProxy();
+const frameMetadata = proxy.readMetadata("url_of_frame");
+
+// Get correct button index from click handler
+const button = frameMetadata.frameInfo.buttons[`${buttonIndex}`];
+
+const isTransactionFrame = button.action === "tx";
+```
+
+### Determine the transaction target and post URL
+
+If the button action indicates the Frame is transactional, get the `target` and `postUrl` from the button. To learn more, see Frame Metadata [Optional Properties](https://www.openframes.xyz/#optional-properties).
+
+```jsx
+if (isTransactionFrame) {
+  const { target, postUrl } = button;
+
+  // Rest of logic in this guide
+}
+```
+
+### Post to the target URL to fetch data
+
+This next step is also the same as a regular transaction frame: make a POST request to the `target` URL to fetch transaction data. The difference is that the payload that gets returned will return an eth_personalSign method if in the subscribe flow, and this is how you know you're dealing with a subscription frame.
+
+Make this request from the Frame with a signed Frame action payload in the POST body. In the `address` field, include the address of the connected wallet.
+
+```jsx
+import { FramesClient } from "@xmtp/frames-client";
+
+const framesClient = new FramesClient(client);
+
+ const payload = await framesClient.signFrameAction({
+			// Same payload as for other frames, + an address field
+			// Address should be the 0x address of the connected account
+      address,
+    });
+
+const transactionInfo: {
+	chainId: string;
+	method: 'eth_personalSign';
+	params: {
+		abi: [];
+		to: `0x${string}`;
+		value?: string; // In the case of a subscribe frame, this will be the message that the user will consent to
+	};
+} = await framesClient.proxy.postTransaction(
+        target,
+        payload,
+      );
+```
+
+### Process transaction data and receive a signature
+
+Pull the consent message from the value of the returned transaction data and use this to get a signature using your preferred tools, such as Viem. Documenting this step in detail is out of the scope of this tutorial.
+
+```jsx
+const value = transactionInfo.params.value;
+
+// Pass the value and account to your preferred tools and receive a signature
+const signature = <<returned_signature>>
+```
+
+### Pass this signature to the signFrameAction
+
+Prepare a new payload with the signature passed as transactionId to pass to the final step.
+
+```jsx
+const payload = await framesClient.signFrameAction({
+  ...prevPayload,
+  transactionId: signature,
+});
+```
+
+### Complete the subscription and show success screen
+
+Pass the postUrl from the button as well as the payload with the signature from the previous step to complete the subscription flow and return metadata of a new success frame.
+
+```jsx
+const completeTransaction = await framesClient.proxy.post(
+  buttonPostUrl,
+  payloadWithTxId,
+);
+// Finally, set the current frame state to this new metadata/success screen
+```
+
+### Try an example subscribe Open Frame
+
+Use the example [Open Frames Subscribe Frame](https://subscribe-boilerplate-frame.vercel.app/) to try these steps out in your app. Or check the code of the [open source repo](https://github.com/xmtp-labs/subscribe-boilerplate-frame).
+
+This example Frame uses a randomly generated wallet in the XMTP dev network to automatically send a "Thank you for subscribing!" message to your main inbox upon subscribing.
+
+---
+
+## Build a subscribe Open Frame
+
+Follow these steps to build a subscribe Open Frame that can be displayed in an app built with XMTP.
+
+**To build a subscribe Open Frame:**
+
+1. Create a boilerplate Next.js app.
+
+```bash
+npx create-next-app my-next-app
+```
+
+2. Install `@coinbase/onchainkit` as a dependency.
+
+```bash
+npm install @coinbase/onchainkit
+```
+
+3. Add the base URL in `.env.local` as a `NEXT_PUBLIC_BASE_URL` environment variable.
+4. In `app/page.tsx`, replace the boilerplate with the following code — this is what will be rendered as the initial frame:
+
+```jsx
+import { getFrameMetadata } from "@coinbase/onchainkit/frame";
+import { Metadata } from "next";
+
+const frameMetadata = getFrameMetadata({
+  // Accepts and isOpenFrame keys are required for Open Frame compatibility
+  accepts: { xmtp: "2024-02-09" },
+  isOpenFrame: true,
+
+  buttons: [
+    {
+      // Whatever label you want your first button to have
+      label: "Subscribe to receive messages from this user!",
+      // Required 'tx' action for a transaction frame
+      action: "tx",
+      // Below buttons are 2 route urls that will be added in the next steps.
+      // Target will send back info about the subscribe frame
+      target: `${process.env.NEXT_PUBLIC_BASE_URL}/api/transaction`,
+      // postUrl will send back a subscription success screen
+      postUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/api/transaction-success`,
+    },
+  ],
+
+  // This is the image shown on the default screen
+  // Add whatever path is needed for your starting image
+  // In this case, using an Open Graph image
+  image: `${process.env.NEXT_PUBLIC_BASE_URL}/api/og?subscribed=false`,
+});
+
+export const metadata: Metadata = {
+  title: "Subscribe Frame",
+  description: "A frame to demonstrate subscribing from a frame",
+  other: {
+    ...frameMetadata,
+  },
+};
+
+export default function Home() {
+  return (
+    <>
+      <h1>Open Frames Subscribe Frame</h1>
+    </>
+  );
+}
+```
+
+5. Add the route to `/api/transaction/route.tsx`. The route is used to get information about the frame that is sent to the target URL.
+
+```jsx
+import { NextRequest, NextResponse } from "next/server";
+import { parseEther, encodeFunctionData } from "viem";
+import type { FrameTransactionResponse } from "@coinbase/onchainkit/frame";
+import { getXmtpFrameMessage } from "@coinbase/onchainkit/xmtp";
+
+async function getResponse(req: NextRequest): Promise<NextResponse | Response> {
+  const body = await req.json();
+  const { isValid } = await getXmtpFrameMessage(body);
+  if (!isValid) {
+    return new NextResponse("Message not valid", { status: 500 });
+  }
+
+  const xmtpClient = // Your client instance; in the boilerplate frame, we're using a randomly generated wallet
+  const walletAddress = xmtpClient?.address || "";
+  const timestamp = Date.now();
+  // Store the timestamp however you'd like, in this case as an env variable, to cross-check at a later step.
+  process.env.TIMESTAMP = JSON.stringify(timestamp);
+  // Create the original consent message.
+  const message = createConsentMessage(walletAddress, timestamp);
+
+  const txData = {
+    // Sepolia or whichever chain id
+    chainId: `eip155:11155111`,
+    method: "eth_personalSign",
+    params: {
+      // This is the message the user will consent to, generated above
+      value: message
+      // These are required fields, but aren't utilized in this flow
+      abi: [],
+      to: walletAddress as `0x${string}`,
+    },
+  };
+  return NextResponse.json(txData);
+}
+
+export async function POST(req: NextRequest): Promise<Response> {
+  return getResponse(req);
+}
+```
+
+6. Get the confirmation frame screen HTML via the `@coinbase/onchainkit` helper to the success image and the success button action — in this case a redirect outside of the frame. (The redirect logic is outside the scope of this tutorial.) We recommend having a separate confirmation screen for users who subscribe and are not activated on XMTP, as they won't yet be able to receive messages.
+
+```jsx
+const confirmationFrameHtmlWithXmtp = getFrameHtmlResponse({
+  accepts: {
+    xmtp: "2024-02-09",
+  },
+  isOpenFrame: true,
+  buttons: [
+    {
+      action: "post_redirect",
+      label: "Subscribed! Read more about Subscribe Frames",
+    },
+  ],
+  postUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/api/end`,
+  image: `${process.env.NEXT_PUBLIC_BASE_URL}/api/og?subscribed=true&hasXmtp=true`,
+});
+
+const confirmationFrameHtmlNoXmtp = getFrameHtmlResponse({
+  accepts: {
+    xmtp: "2024-02-09",
+  },
+  isOpenFrame: true,
+  buttons: [
+    {
+      action: "post_redirect",
+      label: "Activate on XMTP to Receive Messages",
+    },
+  ],
+  postUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/api/endWithoutXmtp`,
+  image: `${process.env.NEXT_PUBLIC_BASE_URL}/api/og?subscribed=true&hasXmtp=false`,
+});
+```
+
+7. Add the route to return the success frame HTML with the new meta tags at `api/transaction-success/route.ts`.
+
+```jsx
+import { confirmationFrameHtml } from "@/app/page";
+import { getXmtpFrameMessage } from "@coinbase/onchainkit/xmtp";
+import { NextRequest, NextResponse } from "next/server";
+import { createConsentProofPayload } from "@xmtp/consent-proof-signature";
+
+async function getResponse(req: NextRequest): Promise<NextResponse> {
+  const body = await req.json();
+  const { isValid } = await getXmtpFrameMessage(body);
+
+if (!isValid) {
+  return new NextResponse("Message not valid", { status: 500 });
+}
+
+const xmtpClient = // Your client
+const signature = body.untrustedData.transactionId;
+
+// Create the consent proof payload
+const payloadBytes = createConsentProofPayload(signature, Date.now());
+const consentProof = invitation.ConsentProofPayload.decode(
+  consentProofUint8Array
+);
+
+  const payloadWithTimestamp = {
+    ...consentProof,
+    timestamp: new Long(
+      consentProof?.timestamp?.low,
+      consentProof?.timestamp?.high,
+      consentProof?.timestamp?.unsigned
+    ),
+  };
+
+  // Do whatever you want with the payload, in the below case we're immediately starting a new conversation
+    const newConvo = await xmtpClient?.conversations.newConversation(
+    body.untrustedData.address,
+    undefined,
+    payloadWithTimestamp
+  );
+  await newConvo?.send("Thank you for being a subscriber!");
+
+  // Determine if user is on XMTP or not and return the corresponding frame
+  const hasXmtp = await xmtpClient?.canMessage(body.untrustedData.address);
+
+  return new NextResponse(
+    hasXmtp ? confirmationFrameHtmlWithXmtp : confirmationFrameHtmlNoXmtp
+  );
+}
+export async function POST(req: NextRequest): Promise<Response> {
+  return getResponse(req);
+}
+```
+
+8. Send your subscription Frame in an XMTP message and try interacting with it!
+
+### Resources
+
+If you need an XMTP messaging app to use, try one of these:
+
+- https://app-preview.converse.xyz/
+- https://dev-dev-inbox.vercel.app/