framelib example

Author: devinaconley

README.md

@@ -1,10 +1,40 @@
-# python-frames
+# framelib
 
 lightweight library for building farcaster frames using python and flask
 
+- easily render frames that conform to the farcaster specification
+- configurable frame design
+- parse frame action messages
+- verify the frame action signatures using neynar
+- query user profile info from warpcast
+
 
 ## quickstart
 
+install `framelib` from pip
 ```
 pip install framelib
 ```
+
+simple example
+```python
+from flask import Flask, url_for
+from framelib import render_frame
+
+app = Flask(__name__)
+
+@app.route('/', methods=['GET', 'POST'])
+def home():
+    return render_frame(
+        image='https://opengraph.githubassets.com/0x/devinaconley/python-frames',
+        button1='next',
+        post_url=url_for('second_page', _external=True),
+    )
+```
+
+## examples
+
+see a complete example using python + flask + vercel [here](https://github.com/devinaconley/python-frames/tree/main/examples/simple)
+
+and for a more advanced example involving multiplayer games, supabase integration, dynamic image rendering, and more,
+see [rock paper scissors](https://github.com/devinaconley/rock-paper-scissors)

examples/simple/README.md

@@ -33,4 +33,12 @@ you can run the frame debugger provided by [frames.js](https://github.com/frames
 
 ## deployment
 
-_TODO_
+make sure your project has been pushed to a github repo
+
+import your project to [vercel](https://vercel.com/) with the flask framework
+
+register with [neynar](https://neynar.com/) to get an api key
+
+define the `NEYNAR_KEY` environment variable in your vercel project settings
+
+deploy!

examples/simple/api/index.py

@@ -1,19 +1,14 @@
 """
 main entry point for example framelib flask app
 """
-import json
-import time
-from flask import Flask, render_template, url_for, request, make_response, jsonify
-from framelib.models import FrameMessage
+import os
+from flask import Flask, url_for, jsonify
+from framelib import render_frame, message, validate_message_or_mock_vercel
 
 app = Flask(__name__)
 
 
-class BadRequest(Exception):
-    pass
-
-
-@app.errorhandler(BadRequest)
+@app.errorhandler(ValueError)
 def handle_invalid_usage(e):
     response = jsonify({'status_code': 403, 'message': str(e)})
     response.status_code = 403
@@ -22,9 +17,34 @@ def handle_invalid_usage(e):
 
 @app.route('/', methods=['GET', 'POST'])
 def home():
-    return jsonify({'status_code': 200, 'message': 'hello world'})
+    # initial frame
+    return render_frame(
+        image='https://opengraph.githubassets.com/0x/devinaconley/python-frames',
+        button1='hello \U0001F44B',
+        post_url=url_for('second_page', _external=True),
+        button2='github',
+        button2_action='link',
+        button2_target='https://github.com/devinaconley/python-frames'
+    )
 
 
 @app.route('/page2', methods=['POST'])
 def second_page():
-    return jsonify({'status_code': 200, 'message': 'hello world, page 2'})
+    # parse frame message
+    msg = message()
+    print(f'received frame message, fid: {msg.untrustedData.fid}, button: {msg.untrustedData.buttonIndex}')
+
+    # validate frame message with neynar
+    api_key = os.getenv('NEYNAR_KEY')
+    msg_val = validate_message_or_mock_vercel(msg, api_key)
+    print(f'validated frame message, fid: {msg_val.interactor.fid}, button: {msg_val.tapped_button}')
+
+    return render_frame(
+        image='https://opengraph.githubassets.com/0x/devinaconley/python-frames',
+        button1='back \U0001F519',
+        post_url=url_for('home', _external=True),
+        input_text=f'hello {msg_val.interactor.username}!',
+        button2='github',
+        button2_action='link',
+        button2_target='https://github.com/devinaconley/python-frames'
+    )

examples/simple/requirements.txt

@@ -1,4 +1,4 @@
 # requirements.txt
-framelib
+framelib~=0.0.0b5
 Flask~=3.0.1
 pydantic

framelib/neynar.py

@@ -49,6 +49,7 @@ def validate_message(msg: FrameMessage, api_key: str) -> ValidatedMessage:
 def validate_message_or_mock(msg: FrameMessage, api_key: str, mock: bool = False) -> ValidatedMessage:
     if mock:
         # mock
+        # TODO option to populate with warpcast profile
         return ValidatedMessage(
             object='validated_frame_action',
             interactor=Interactor(
@@ -72,5 +73,6 @@ def validate_message_or_mock(msg: FrameMessage, api_key: str, mock: bool = False
     return validate_message(msg, api_key)
 
 
-def validate_message_or_mock_vercel(msg: FrameMessage, api_key: str) -> (bool, ValidatedMessage):
-    return validate_message_or_mock(msg, api_key, os.getenv('VERCEL_ENV') is None)
+def validate_message_or_mock_vercel(msg: FrameMessage, api_key: str) -> ValidatedMessage:
+    vercel_env = os.getenv('VERCEL_ENV')
+    return validate_message_or_mock(msg, api_key, vercel_env is None or vercel_env == 'development')

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name='framelib',
-    version='0.0.0.b4',
+    version='0.0.0.b5',
     author='Devin A. Conley',
     author_email='devinaconley@gmail.com',
     description='lightweight library for building farcaster frames using python and flask',