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

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,75 @@
+# @elizaos/plugin-farcaster
+
+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).
+
+## Capabilities
+
+- **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
+
+```bash
+bun add @elizaos/plugin-farcaster
+```
+
+## Configuration
+
+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";
+
+const agent = new AgentRuntime({
+  plugins: [farcasterPlugin],
+  // ...
+});
+```
+
+### Environment variables
+
+| 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 |
+
+For multi-account setups, prefix any variable with `FARCASTER_<ACCOUNT_ID>_` (e.g. `FARCASTER_MYACCT_FID`).
+
+### Webhook mode
+
+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.
+
+## Providers
+
+### `farcasterProfile`
+
+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
+
+```bash
+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
+```

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-farcaster",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.11-beta.7",
   "type": "module",
   "main": "dist/node/index.node.js",
   "module": "dist/node/index.node.js",
@@ -13,6 +13,7 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.node.js",
       "browser": {
         "types": "./dist/browser/index.d.ts",
         "import": "./dist/browser/index.browser.js",
@@ -25,36 +26,52 @@
       },
       "bun": {
         "types": "./dist/node/index.d.ts",
+        "import": "./dist/node/index.node.js",
         "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": [
-    "dist"
+    "dist",
+    "auto-enable.ts"
   ],
+  "elizaos": {
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "social-posting"
+      ]
+    }
+  },
   "sideEffects": false,
   "dependencies": {
-    "@elizaos/core": "2.0.0-alpha.3",
+    "@elizaos/core": "2.0.11-beta.7",
     "@neynar/nodejs-sdk": "^3.34.0",
     "lru-cache": "^11.1.0",
-    "typescript": "^5.9.3",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
+    "@biomejs/biome": "^2.4.14",
     "@types/node": "^25.0.3",
-    "esbuild": "^0.25.0",
+    "esbuild": "^0.28.0",
+    "typescript": "^6.0.3",
     "vitest": "^4.0.0"
   },
   "scripts": {
     "dev": "bun run build.ts --watch",
-    "clean": "rm -rf dist .turbo node_modules .turbo-tsconfig.json tsconfig.tsbuildinfo",
+    "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 .",
@@ -172,8 +189,8 @@
       }
     }
   },
-  "gitHead": "646c632924826e2b75c2304a75ee56959fe4a460",
-  "milady": {
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e",
+  "eliza": {
     "platforms": [
       "browser",
       "node"

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";