Merge pull request #5 from fabriguespe/access

Add access section

examples/gm/.env.example

@@ -0,0 +1,2 @@
+KEY= # 0x... the private key of the bot (with the 0x prefix)
+XMTP_ENV=production # or `dev`

examples/gm/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 XMTP (xmtp.org)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/gm/README.md

@@ -0,0 +1,40 @@
+# Gm Bot
+
+Simple Gm bot
+
+## Usage
+
+```jsx
+import "dotenv/config";
+import { xmtpClient, run, HandlerContext } from "@xmtp/botkit";
+
+run(async (context: HandlerContext) => {
+ const { content, senderAddress } = context.message;
+
+ await context.reply(`gm`);
+});
+```
+
+## Running the bot
+
+> ⚠️ Bot kit is not compatible with `bun`. Use `npm` or `yarn`
+
+```bash
+# install dependencies
+yarn install
+
+# running the bot
+yarn build
+yarn start
+
+# to run with hot-reload
+yarn build:watch
+yarn start:watch
+```
+
+## Variables
+
+```bash
+KEY= # 0x... the private key of the bot (with the 0x prefix)
+XMTP_ENV=production # or `dev`
+```

examples/gm/package.json

@@ -0,0 +1,32 @@
+{
+ "name": "gm-bot",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "main": "dist/index.js",
+ "module": "dist/index.js",
+ "types": "dist/index.d.ts",
+ "scripts": {
+ "build": "tsc",
+ "build:watch": "tsc -w",
+ "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+ "start": "node dist/index.js",
+ "start:watch": "nodemon dist/index.js",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@xmtp/botkit": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^20.12.7",
+ "nodemon": "^3.1.0",
+ "prettier": "^3.2.5",
+ "typescript": "^5.4.3"
+ }
+}

examples/gm/src/index.ts

@@ -0,0 +1,10 @@
+import "dotenv/config";
+import { run, HandlerContext } from "@xmtp/botkit";
+
+run(async (context: HandlerContext) => {
+ // Get the message and the address from the sender
+ const { content, senderAddress } = context.message;
+
+ // To reply, just call `reply` on the HandlerContext.
+ await context.reply(`gm`);
+});

examples/gm/tsconfig.json

@@ -0,0 +1,7 @@
+{
+ "extends": "@xmtp/tsconfig/base.json",
+ "include": ["src/**/*"],
+ "compilerOptions": {
+ "outDir": "./dist"
+ }
+}

examples/group/src/commands.ts

@@ -69,4 +69,8 @@ export const commands = [
  { command: "/help", description: "Show available commands." },
  ],
  },
+ {
+ name: "/access",
+ description: "Command for managing the access of users to the bot.",
+ },
 ];

examples/group/src/index.ts

@@ -21,14 +21,13 @@ run(async (context: HandlerContext) => {
  const { typeId } = contentType;
 
  populateFakeUsers(context);
- console.log("message", content, contentType, senderAddress, typeId);
  if (typeId == "reaction") {
  const { action, content: emoji } = content;
  if (emoji == "degen" && action == "added") await degenHandler(context);
  } else if (typeId == "reply") {
  const { receiver, content: reply } = content;
  if (receiver && reply.includes("degen")) await degenHandler(context);
- } else if (content == "/access" && typeId == "silent") {
+ } else if (content.content == "/access" && typeId == "silent") {
  if (senderAddress) {
  /*here put the token gated logic*/
  context.grant_access();

packages/botkit/src/content-types/Bot.ts

@@ -14,13 +14,13 @@ export class BotMessageCodec {
  }
 
  encode(message) {
- const { sender, receivers, content, context, reference } = message; // Include receivers in the destructuring
+ const { sender, receivers, content, metadata, reference } = message; // Include receivers in the destructuring
 
  return {
  type: ContentTypeBotMessage,
  parameters: {},
  content: new TextEncoder().encode(
- JSON.stringify({ sender, receivers, content, context, reference }), // Include receivers in the JSON string
+ JSON.stringify({ sender, receivers, content, metadata, reference }), // Include receivers in the JSON string
  ),
  };
  }
@@ -30,15 +30,15 @@ export class BotMessageCodec {
 
  try {
  const message = JSON.parse(decodedContent);
- const { sender, receivers, content, context, reference } = message; // Include receivers in the destructuring
- return { sender, receivers, content, context, reference }; // Return receivers along with other properties
+ const { sender, receivers, content, metadata, reference } = message; // Include receivers in the destructuring
+ return { sender, receivers, content, metadata, reference }; // Return receivers along with other properties
  } catch (e) {
  const parameters = encodedContent.parameters;
  return {
  sender: parameters.sender,
  receivers: parameters.receivers, // Fallback to receivers in parameters if JSON parsing fails
  content: decodedContent,
- context: parameters.context,
+ metadata: parameters.metadata,
  reference: parameters.reference,
  };
  }

packages/botkit/src/lib/handler-context.ts

@@ -50,11 +50,13 @@ export default class HandlerContext {
  receivers: string[] = [],
  messageId: string = "",
  ) {
+ const { typeId } = this.message.contentType;
+ if (typeId == "silent") return;
  const botMessage = {
  sender: this.message.senderAddress,
  receivers: receivers,
  content: message,
- ...this.context,
+ metadata: { ...this.context },
  reference: messageId,
  };
 

packages/docs/docs/pages/access.mdx

@@ -0,0 +1,96 @@
+# Access
+
+For declaring that the bot will handle access we need to add the access command to the commands file
+
+```tsx [src/commands.ts]
+export const commands = [
+ {
+ name: "General Commands",
+ icon: "🔧",
+ description: "Command for managing default behaviours.",
+ commands: [
+ /* Declare access command*/
+ {
+ command: "/access",
+ description: "Grant access to a user to the bot.",
+ },
+ /* Other commands */
+ ],
+ },
+];
+```
+
+### 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);
+```
+
+For allowing access to a new user botkit receives a `silent` request with this structure
+
+```tsx
+{
+ content: "/access",
+ metadata: {}
+}
+```
+
+### Receive an access request
+
+To accept an access request in your app, you can use the following code:
+
+```jsx
+if (typeId == "silent") {
+ const { content: command } = content;
+ // Do something with the command
+ if (command == "/access")
+ if (senderAddress) {
+ /*here put the token gated logic*/
+ // accept the access request
+ context.grant_access();
+ }
+}
+```
+
+### Full example
+
+```jsx [src/index.ts]
+import "dotenv/config";
+import { run, HandlerContext } from "@xmtp/botkit";
+import { commands } from "./commands.js";
+
+const newBotConfig = {
+ context: {
+ commands: commands,
+ },
+};
+
+run(async (context: HandlerContext) => {
+ const { content, contentType, senderAddress } = context.message;
+ const { typeId } = contentType;
+
+ if (typeId == "silent") {
+ const { content: command } = content;
+ // Do something with the command
+ if (command == "/access")
+ if (senderAddress) {
+ /*here put the token gated logic*/
+ // accept the access request
+ context.grant_access();
+ }
+ }
+ context.reply("gm!");
+}, newBotConfig);
+```

packages/docs/docs/pages/content-types/silent.mdx

@@ -0,0 +1,24 @@
+# Silent
+
+For special uses cases where the app needs to send commands to a bot without being displayed in the app, botkit receives a `silent` request with this structure
+
+```tsx
+{
+ content: "command",
+ metadata: {}
+}
+```
+
+### Receive an silent message
+
+This example shows how recieve a silent message and grant access to a user
+
+```jsx
+const { content, contentType, senderAddress } = context.message;
+const { typeId } = contentType;
+
+if (typeId == "silent") {
+ const { content: command } = content;
+ // Do something with the command
+}
+```

packages/docs/docs/pages/installation.mdx

@@ -1,37 +1,5 @@
 # Installation
 
-## Environment
-
-For developing you will need the playground and the docs running in the monorepo. This is only relevant in this phase of development.
-
-To run the playground run:
-
-```bash
-// First install yarn inside folder
-cd packages/playground
-yarn install
-
-// Run from the folder
-yarn dev
-
-// Run from the root
-yarn start:playground
-```
-
-To run the docs run:
-
-```bash
-// First install yarn inside folder
-cd packages/docs
-yarn install
-
-// Run from the folder
-yarn dev
-
-// Run from the root
-yarn start:docs
-```
-
 ## CLI Quickstart
 
 You can use the `create-xmtp-bot` CLI tool, which simplifies the creation and configuration of new bots.