@elizaos/plugin-farcaster 1.0.0-beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +150 -0
  3. package/dist/index.js +5240 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +109 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Shaw Walters and elizaOS Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,150 @@
1
+ # ElizaOS Farcaster Client
2
+
3
+ A plugin for ElizaOS that enables agent integration with the Farcaster social network.
4
+
5
+ ## Overview
6
+
7
+ The ElizaOS Farcaster Client allows AI agents to interact with the Farcaster social network by:
8
+
9
+ - Publishing original casts (posts)
10
+ - Responding to mentions and replies
11
+ - Interacting with other users' content
12
+ - Processing user engagement automatically
13
+
14
+ This client leverages the [Neynar API](https://neynar.com) to interact with Farcaster, providing a robust integration between ElizaOS agents and the Farcaster social graph.
15
+
16
+ ## Features
17
+
18
+ - **Automated Posting**: Schedule and publish regular casts with configurable intervals
19
+ - **Engagement Monitoring**: Track mentions, replies, and interactions
20
+ - **Conversation Threading**: Build and maintain conversation context for natural interactions
21
+ - **Dry Run Mode**: Test functionality without actually posting to Farcaster
22
+ - **Configurable Settings**: Customize behavior via environment variables
23
+ - **Caching**: Efficient caching of profiles and casts for improved performance
24
+
25
+ ## Installation
26
+
27
+ ```bash
28
+ npm install @elizaos-plugins/client-farcaster
29
+ ```
30
+
31
+ ## Configuration
32
+
33
+ The client requires the following configurations, which can be set via environment variables or ElizaOS runtime settings:
34
+
35
+ ### Required Settings
36
+
37
+ | Parameter | Description |
38
+ | ------------------------------ | -------------------------------------- |
39
+ | `FARCASTER_NEYNAR_API_KEY` | Neynar API key for accessing Farcaster |
40
+ | `FARCASTER_NEYNAR_SIGNER_UUID` | Signer UUID for your Farcaster account |
41
+ | `FARCASTER_FID` | Your Farcaster FID (identifier) |
42
+
43
+ ### Optional Settings
44
+
45
+ | Parameter | Description | Default |
46
+ | -------------------------- | --------------------------------------------------- | ------- |
47
+ | `FARCASTER_DRY_RUN` | Run in simulation mode without posting (true/false) | false |
48
+ | `MAX_CAST_LENGTH` | Maximum length of casts | 320 |
49
+ | `FARCASTER_POLL_INTERVAL` | Interval for checking mentions (minutes) | 2 |
50
+ | `ENABLE_POST` | Enable automatic posting (true/false) | true |
51
+ | `POST_INTERVAL_MIN` | Minimum time between posts (minutes) | 90 |
52
+ | `POST_INTERVAL_MAX` | Maximum time between posts (minutes) | 180 |
53
+ | `ENABLE_ACTION_PROCESSING` | Enable processing interactions (true/false) | false |
54
+ | `ACTION_INTERVAL` | Interval for processing actions (minutes) | 5 |
55
+ | `POST_IMMEDIATELY` | Post immediately on startup (true/false) | false |
56
+ | `MAX_ACTIONS_PROCESSING` | Maximum actions to process in one cycle | 1 |
57
+ | `ACTION_TIMELINE_TYPE` | Type of timeline to use for actions | ForYou |
58
+
59
+ ## Usage
60
+
61
+ ### Basic Integration with ElizaOS
62
+
63
+ ```typescript
64
+ import { ElizaOS } from '@elizaos/core';
65
+ import farcasterPlugin from '@elizaos-plugins/client-farcaster';
66
+
67
+ // Initialize ElizaOS
68
+ const elizaOs = new ElizaOS({
69
+ // ElizaOS configuration
70
+ });
71
+
72
+ // Register the Farcaster plugin
73
+ elizaOs.registerPlugin(farcasterPlugin);
74
+
75
+ // Start ElizaOS
76
+ elizaOs.start();
77
+ ```
78
+
79
+ ### Customizing Cast Templates
80
+
81
+ You can customize the templates used for generating casts by providing custom templates in your agent character configuration:
82
+
83
+ ```typescript
84
+ const myCharacter = {
85
+ name: 'My Agent',
86
+ bio: 'A helpful AI assistant on Farcaster',
87
+ templates: {
88
+ farcasterPostTemplate: `
89
+ # Custom post template
90
+ Write a thoughtful post about {{topic}} in the voice of {{agentName}}.
91
+ `,
92
+ farcasterMessageHandlerTemplate: `
93
+ # Custom reply template
94
+ Respond to {{currentPost}} as {{agentName}} would.
95
+ `,
96
+ farcasterShouldRespondTemplate: `
97
+ # Custom response decision template
98
+ Determine if {{agentName}} should respond to {{currentPost}}.
99
+ `,
100
+ },
101
+ };
102
+ ```
103
+
104
+ ## Development
105
+
106
+ ### Build
107
+
108
+ ```bash
109
+ npm run build
110
+ ```
111
+
112
+ ### Testing
113
+
114
+ ```bash
115
+ npm test
116
+ ```
117
+
118
+ ### Development Mode
119
+
120
+ ```bash
121
+ npm run dev
122
+ ```
123
+
124
+ ## Architecture
125
+
126
+ The client is organized into several core components:
127
+
128
+ - **FarcasterClient**: Base client for interacting with the Farcaster network via Neynar
129
+ - **FarcasterPostManager**: Manages autonomous posting schedule and generation
130
+ - **FarcasterInteractionManager**: Handles mentions, replies, and other interactions
131
+ - **Memory Management**: Stores conversation context and history
132
+
133
+ ## Dependencies
134
+
135
+ - [@neynar/nodejs-sdk](https://www.npmjs.com/package/@neynar/nodejs-sdk): Official SDK for Neynar API
136
+ - [@elizaos/core](https://www.npmjs.com/package/@elizaos/core): ElizaOS core framework
137
+
138
+ ## Testing
139
+
140
+ The client includes comprehensive tests for:
141
+
142
+ - Cast creation and management
143
+ - Interaction handling
144
+ - Timeline processing
145
+
146
+ Run the tests with:
147
+
148
+ ```bash
149
+ npm test
150
+ ```