@elizaos/plugin-farcaster 2.0.0-alpha.7 → 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shaw Walters and elizaOS Contributors
+
+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.

package/README.md

@@ -0,0 +1,108 @@
+# @elizaos/plugin-farcaster
+
+A multi-language Farcaster plugin for elizaOS, providing full integration with the Farcaster decentralized social network via the Neynar API.
+
+## Languages
+
+This plugin is implemented in three languages with full feature parity:
+
+- **TypeScript** - Primary implementation for Node.js and browser
+- **Python** - Python implementation for ML/AI pipelines
+- **Rust** - High-performance implementation with WASM support
+
+## Features
+
+- **Cast Management**: Send casts, reply to casts, and manage your timeline
+- **Profile Management**: Fetch and cache user profiles
+- **Mentions & Notifications**: Monitor and respond to mentions
+- **Timeline Provider**: Access your Farcaster feed
+- **Thread Support**: Navigate and respond within cast threads
+- **Embed Processing**: Handle images, videos, and embedded casts
+- **Webhook Support**: Real-time updates via webhooks
+- **Polling Mode**: Periodic fetching for simple deployments
+
+## Installation
+
+### TypeScript/Node.js
+
+```bash
+npm install @elizaos/plugin-farcaster
+# or
+bun add @elizaos/plugin-farcaster
+```
+## Configuration
+
+The plugin requires the following environment variables:
+
+| Variable                   | Required | Description                                               |
+| -------------------------- | -------- | --------------------------------------------------------- |
+| `FARCASTER_FID`            | Yes      | Your Farcaster ID (FID)                                   |
+| `FARCASTER_SIGNER_UUID`    | Yes      | Neynar signer UUID for signing casts                      |
+| `FARCASTER_NEYNAR_API_KEY` | Yes      | Neynar API key for API access                             |
+| `FARCASTER_DRY_RUN`        | No       | Enable dry run mode (default: false)                      |
+| `FARCASTER_MODE`           | No       | Operation mode: 'polling' or 'webhook' (default: polling) |
+| `MAX_CAST_LENGTH`          | No       | Maximum cast length (default: 320)                        |
+| `FARCASTER_POLL_INTERVAL`  | No       | Polling interval in seconds (default: 120)                |
+| `ENABLE_CAST`              | No       | Enable auto-casting (default: true)                       |
+| `CAST_INTERVAL_MIN`        | No       | Min cast interval in minutes (default: 90)                |
+| `CAST_INTERVAL_MAX`        | No       | Max cast interval in minutes (default: 180)               |
+
+## Usage
+
+### TypeScript
+
+```typescript
+import farcasterPlugin from "@elizaos/plugin-farcaster";
+
+// Register with agent runtime
+const agent = new AgentRuntime({
+  plugins: [farcasterPlugin],
+  // ... other config
+});
+```
+
+## Actions
+
+Farcaster public posts are exposed through the primary `POST` action:
+
+- `POST operation=send` publishes a cast through the Farcaster PostConnector.
+- `POST operation=read` reads recent casts through the Farcaster PostConnector.
+
+Farcaster search is not advertised until the local Neynar client exposes a
+search primitive.
+
+## Providers
+
+### farcaster_profile
+
+Provides the agent's Farcaster profile information for context.
+
+### farcaster_thread
+
+Provides thread context for understanding conversation flow.
+
+## Development
+
+### Building
+
+```bash
+# TypeScript
+bun run build
+# All languages
+bun run test
+
+# TypeScript only
+bun run test:ts
+
+# Python only
+bun run test:python
+
+# Rust only
+bun run test:rust
+```
+
+### Linting
+
+```bash
+# TypeScript
+bun run lint

package/auto-enable.ts

@@ -0,0 +1,21 @@
+// Auto-enable check for @elizaos/plugin-farcaster.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+/** Enable when a `farcaster` connector block is present and not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  const c = (ctx.config?.connectors as Record<string, unknown> | undefined)
+    ?.farcaster;
+  if (!c || typeof c !== "object") return false;
+  const config = c as Record<string, unknown>;
+  if (config.enabled === false) return false;
+  // The full per-connector field check (Neynar API key / signer / FID) lives
+  // in the central engine's isConnectorConfigured. We delegate to a simple
+  // "block present + not explicitly disabled" check here; the central
+  // engine's stricter check remains as a fallback during migration.
+  return true;
+}

package/dist/actions/index.d.ts

@@ -0,0 +1,2 @@
+export declare const farcasterActions: any[];
+//# sourceMappingURL=index.d.ts.map

package/dist/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../actions/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,OAAK,CAAC"}

package/dist/auto-enable.d.ts

@@ -0,0 +1,4 @@
+import type { PluginAutoEnableContext } from "@elizaos/core";
+/** Enable when a `farcaster` connector block is present and not explicitly disabled. */
+export declare function shouldEnable(ctx: PluginAutoEnableContext): boolean;
+//# sourceMappingURL=auto-enable.d.ts.map

package/dist/auto-enable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-enable.d.ts","sourceRoot":"","sources":["../auto-enable.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAWlE"}

package/dist/browser/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./index.browser";
-export { default } from "./index.browser";
+export * from "../index.browser";
+export { default } from "../index.browser";

package/dist/cjs/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./index.node";
-export { default } from "./index.node";
+export * from "../index.node";
+export { default } from "../index.node";