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

package/README.md

@@ -1,108 +1,75 @@
 # @elizaos/plugin-farcaster
 
-A multi-language Farcaster plugin for elizaOS, providing full integration with the Farcaster decentralized social network via the Neynar API.
+Farcaster client plugin for [elizaOS](https://github.com/elizaOS/eliza). Gives an Eliza agent the ability to publish casts, reply to mentions, read its feed, and react to casts on the Farcaster decentralized social network via the [Neynar API](https://neynar.com).
 
-## Languages
+## Capabilities
 
-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
+- **Cast publishing** — send new casts and thread replies; auto-truncates to 320 characters using the agent's language model when needed.
+- **Feed reading** — fetch and search the authenticated account's recent timeline.
+- **Mentions & interactions** — monitor mentions and respond in polling mode or via real-time webhook.
+- **Reactions** — like, unlike, recast, and remove recasts.
+- **Thread traversal** — walk a cast thread back to its root.
+- **Profile provider** — injects the agent's Farcaster profile (FID, username, display name) as context for social-posting and messaging tasks.
+- **Webhook handler** — `POST /webhook` route processes Neynar webhook events in real time.
+- **Multi-account** — one agent can manage multiple Farcaster accounts via namespaced env vars.
 
 ## 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
+## Configuration
 
-### TypeScript
+The plugin is auto-enabled when a `farcaster` connector block is present in the agent config. Register it manually if needed:
 
 ```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:
+### Environment variables
 
-- `POST operation=send` publishes a cast through the Farcaster PostConnector.
-- `POST operation=read` reads recent casts through the Farcaster PostConnector.
+| Variable                   | Required | Default            | Description |
+|----------------------------|----------|--------------------|-------------|
+| `FARCASTER_NEYNAR_API_KEY` | yes      | —                  | Neynar API key |
+| `FARCASTER_FID`            | yes      | —                  | Farcaster user ID (integer) |
+| `FARCASTER_SIGNER_UUID`    | yes      | —                  | Neynar signer UUID |
+| `FARCASTER_MODE`           | no       | `polling`          | `polling` or `webhook` |
+| `FARCASTER_HUB_URL`        | no       | `hub.pinata.cloud` | Farcaster hub base URL |
+| `FARCASTER_POLL_INTERVAL`  | no       | `120`              | Seconds between polling cycles |
+| `FARCASTER_DRY_RUN`        | no       | `false`            | Simulate without publishing |
+| `MAX_CAST_LENGTH`          | no       | `320`              | Max cast characters |
+| `ENABLE_CAST`              | no       | `true`             | Enable autonomous cast loop |
+| `CAST_INTERVAL_MIN`        | no       | `90`               | Min minutes between autonomous casts |
+| `CAST_INTERVAL_MAX`        | no       | `180`              | Max minutes between autonomous casts |
+| `CAST_IMMEDIATELY`         | no       | `false`            | Post first cast immediately on start |
+| `ENABLE_ACTION_PROCESSING` | no       | `false`            | Process mentions automatically |
+| `ACTION_INTERVAL`          | no       | `5`                | Minutes between action-processing cycles |
+| `MAX_ACTIONS_PROCESSING`   | no       | `1`                | Max interactions processed per cycle |
 
-Farcaster search is not advertised until the local Neynar client exposes a
-search primitive.
+For multi-account setups, prefix any variable with `FARCASTER_<ACCOUNT_ID>_` (e.g. `FARCASTER_MYACCT_FID`).
 
-## Providers
+### Webhook mode
 
-### farcaster_profile
+Set `FARCASTER_MODE=webhook` and configure your Neynar app to send webhook events to `POST /webhook` on your agent's public URL. The handler validates the `NeynarWebhookData` payload shape before processing.
 
-Provides the agent's Farcaster profile information for context.
+## Providers
 
-### farcaster_thread
+### `farcasterProfile`
 
-Provides thread context for understanding conversation flow.
+Injects the agent's current Farcaster profile (FID, username, display name) into the context for turns in the `social_posting`, `messaging`, and `connectors` contexts.
 
 ## 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
+bun run --cwd plugins/plugin-farcaster build       # build node + browser bundles
+bun run --cwd plugins/plugin-farcaster dev         # watch mode
+bun run --cwd plugins/plugin-farcaster test        # run all tests
+bun run --cwd plugins/plugin-farcaster typecheck   # type-check only
+bun run --cwd plugins/plugin-farcaster lint        # biome check + fix
 ```
-
-### Linting
-
-```bash
-# TypeScript
-bun run lint

package/auto-enable.ts

@@ -8,7 +8,7 @@ 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)
+  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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-farcaster",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.11-beta.7",
   "type": "module",
   "main": "dist/node/index.node.js",
   "module": "dist/node/index.node.js",
@@ -30,6 +30,12 @@
         "default": "./dist/node/index.node.js"
       },
       "default": "./dist/node/index.node.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
@@ -46,7 +52,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/core": "2.0.11-beta.7",
     "@neynar/nodejs-sdk": "^3.34.0",
     "lru-cache": "^11.1.0",
     "zod": "^4.4.3"
@@ -63,9 +69,9 @@
     "clean": "rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo",
     "format": "bunx @biomejs/biome format --write .",
     "format:check": "bunx @biomejs/biome format .",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "npx -y vitest@4.0.18 run --passWithNoTests",
-    "test:unit": "npx -y vitest@4.0.18 run __tests__ --passWithNoTests",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test": "npx -y vitest@4.0.18 run",
+    "test:unit": "npx -y vitest@4.0.18 run __tests__",
     "test:integration": "echo 'No integration tests'",
     "test:watch": "vitest",
     "lint": "bunx @biomejs/biome check --write --unsafe .",
@@ -183,7 +189,7 @@
       }
     }
   },
-  "gitHead": "646c632924826e2b75c2304a75ee56959fe4a460",
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e",
   "eliza": {
     "platforms": [
       "browser",

package/dist/actions/index.d.ts

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

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

@@ -1 +0,0 @@
-{"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

@@ -1,4 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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.browser.js

@@ -1,16 +0,0 @@
-// index.browser.ts
-import { logger } from "@elizaos/core";
-var farcasterPlugin = {
-  name: "farcaster",
-  description: "Farcaster client plugin (browser: stub, use a server proxy)",
-  async init(_config, _runtime) {
-    logger.warn("[plugin-farcaster] This plugin is not supported directly in browsers. Use a server proxy.");
-  }
-};
-var index_browser_default = farcasterPlugin;
-export {
-  farcasterPlugin,
-  index_browser_default as default
-};
-
-//# debugId=24315B60950B4B5564756E2164756E21

package/dist/browser/index.browser.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../index.browser.ts"],
-  "sourcesContent": [
-    "import type { IAgentRuntime, Plugin } from \"@elizaos/core\";\nimport { logger } from \"@elizaos/core\";\n\nexport type {\n  Cast,\n  CastEmbed,\n  CastId,\n  FarcasterConfig,\n  FarcasterEventTypes,\n  FarcasterMessageType,\n  FidRequest,\n  Profile,\n} from \"./types\";\n\n/**\n * Browser-safe stub.\n *\n * The full Farcaster integration depends on server-side credentials and the Neynar SDK.\n * In browsers, import should succeed, but usage should be disabled (use a server proxy).\n */\nexport const farcasterPlugin: Plugin = {\n  name: \"farcaster\",\n  description: \"Farcaster client plugin (browser: stub, use a server proxy)\",\n  async init(_config, _runtime: IAgentRuntime): Promise<void> {\n    logger.warn(\n      \"[plugin-farcaster] This plugin is not supported directly in browsers. Use a server proxy.\"\n    );\n  },\n};\n\nexport default farcasterPlugin;\n"
-  ],
-  "mappings": ";AACA;AAmBO,IAAM,kBAA0B;AAAA,EACrC,MAAM;AAAA,EACN,aAAa;AAAA,OACP,KAAI,CAAC,SAAS,UAAwC;AAAA,IAC1D,OAAO,KACL,2FACF;AAAA;AAEJ;AAEA,IAAe;",
-  "debugId": "24315B60950B4B5564756E2164756E21",
-  "names": []
-}

package/dist/browser/index.d.ts

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

package/dist/cjs/index.d.ts

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