Work Sample 2: Developer Documentation

Work Sample 2: Developer Documentation

Project: Poap Invites Tool - API

Context: I built a tool at Devcon 2024 that allows community owners on Farcaster to discover the holders of their POAPs on Farcaster and invite them to join their Farcaster channel. I wrote the Readme document for the project repository that describes in technical detail how other developers can use it to give access to their own Farcaster communities from POAPs.

Achievements: Learned how to build in comments to the codebase that can be leveraged by others moving forward to build developer documentation and showcase logic flow with mermaid sequence diagrams.

Readme: https://github.com/iSpeakNerd/poap-invites-frame/blob/main/README.md reproduced below:

---

POAP Invites Frame

Create an invite frame to add users to a channel on Farcaster from a POAP event.

This project uses frog.fm in Nextjs to create and host the frame server, fetches POAP data from poap.tech, and finds Farcaster users using Neynar SDK. Created at Devcon 2024.

Uses cast-intent as WarpcastUrlBuilder to create frame cast in Farcaster channel.

---

---

Using this repository

Follow app logic in main.ts

Environment Variables

4 env vars to add to your .env.local file:

1. POAP_EVENT_ID - the event id of the POAP
2. NEYNAR_API_KEY - API key from Neynar
3. POAP_API_KEY - API key from poap.tech
4. WC_INVITE_LINK - channel invite link from Warpcast, must be generated by a user with moderator permissions for the channel, generate and add manually

How to setup your own Frame

1. Clone repository to local

2. Install dependencies using your preferred package manager - I use pnpm

    npm install  
    # or  
    pnpm install  
    # or  
    yarn install  
   

3. Set up poap.tech and Neynar API keys

   • Obtain API credentials for POAP.tech to query POAP wallet holders
   • Obtain API credentials for Neynar to map wallet addresses to Farcaster IDs
   • Add credentials to .env.local file

4. Replace POAP event ID and run main.ts script, it will:

   • Fetch POAP wallets via poap.tech API - GET event/{id}/poaps
     • Use the poap.tech API to retrieve array of wallet addresses holding a specific POAP
     • Implemented in lib/poap-wallets.ts as @getPoapWallets
   • Resolve Farcaster IDs using POAP wallets via Neynar SDK - GET /v2/farcaster/user/bulk-by-address
     • Use the Neynar SDK/API to map the fetched wallets to Farcaster user profiles
     • Implemented in lib/get-fids.ts as @getFids

5. Create and Deliver Invites

   • Build the invite flow using the repository’s utilities and APIs:
     • Generate an Allowlist: Compile Farcaster IDs eligible for channel invites.
       • Implemented in lib/get-fids.ts as @processForFids
     • Deliver Invites: Use Farcaster frames or direct messages to send invites to Farcaster users.

6. Customize Farcaster Frame

   • Customize the frame at app/api/[[...routes]]/route.tsx - Uses frog.fm as framework for frames

   • Run dev server

       npm run dev
       # or
       pnpm dev
     

   • Visit http://localhost:3000/api/dev to inspect frame using frog.fm devtools
   • Customize and repeat until satisfied
7. Customize the Announcement Cast in cast.ts
   • Replace the options properties in the @WarpcastUrlBuilder.composerUrl method call
   • options.text - the text of the cast delivering the frame invites
   • options.embeds - url of the live frame server api route
   • options.channelKey - the name of the channel to cast the frame in

    // example
      const url = warpcastUrlBuilder.composerUrl({
        text: `Welcome new frens! If you played a game and got a /poap from me at /devcon love to hear from you in /tabletop! 
           
        Click Start to get your channel invite!`,
        embeds: ['https://poap-invites-frame.vercel.app/api'],
        channelKey: 'tabletop',
      });
    // https://warpcast.com/~/compose?text=Welcome%2520new%2520frens%21%2520If%2520you%2520played%2520a%2520game%2520and%2520got%2520a%2520%252Fpoap%2520from%2520me%2520at%2520%252Fdevcon%2520love%2520to%2520hear%2520from%2520you%2520in%2520%252Ftabletop%21%2520%250A%2520%2520%2520%2520%250A%2520%2520%2520%2520Click%2520Start%2520to%2520get%2520your%2520channel%2520invite%21&embeds%5B%5D=https%3A%2F%2Fpoap-invites-frame.vercel.app%2Fapi&channelKey=tabletop
   

8. Deliver Invites via Frame Cast in Farcaster Channel

   • Run cast.ts to create the composer URL - @composerUrl
   • Click the composer URL in the console to cast the frame!

---

The simplest way I’ve found to run single typescript files in Node is with ts-node dev dependency and the following command:

node --loader ts-node/esm file.ts

Note: Requires "allowImportingTsExtensions": true and "noEmit": true in tsconfig.json