bereach-openclaw 0.2.7 → 0.2.10

package/README.md

@@ -8,29 +8,111 @@ LinkedIn outreach automation via [BeReach](https://berea.ch). Registers 33 in-pr
 openclaw plugins install bereach-openclaw
 ```
 
+## Upgrade
+
+`openclaw plugins update bereach` can leave `node_modules` and `extensions/` out of sync (version mismatch → trim/crash errors). **Use uninstall + reinstall** instead:
+
+```bash
+openclaw plugins uninstall bereach
+openclaw plugins install bereach-openclaw
+```
+
+Then restart the Gateway. Verify versions match:
+```bash
+cat /data/.openclaw/node_modules/bereach-openclaw/package.json | grep version
+cat /data/.openclaw/extensions/bereach/package.json | grep version
+```
+
 ## Setup
 
-Set your API key in OpenClaw config (`~/.openclaw/openclaw.json`):
+The API key can be set in 3 ways (in order of precedence):
+
+**1. OpenClaw config** (recommended) — `~/.openclaw/openclaw.json` or `/data/.openclaw/openclaw.json`:
 
-```json5
+```json
 {
-  plugins: {
-    entries: {
-      bereach: {
-        enabled: true,
-        config: {
-          BEREACH_API_KEY: "brc_your_token_here"
+  "plugins": {
+    "allow": ["bereach"],
+    "entries": {
+      "bereach": {
+        "enabled": true,
+        "config": {
+          "BEREACH_API_KEY": "brc_your_token_here"
         }
       }
     }
+  },
+  "tools": {
+    "allow": ["bereach"]
+  }
+}
+```
+
+> **Note:** `plugins.allow` loads the plugin; `tools.allow` enables the tools (they are registered with `optional: true`).
+
+**Skills + model (optional)** — `skills.entries` has no `model` field; model is set at the agent level. To use Sonnet for BeReach:
+
+```json
+{
+  "skills": {
+    "entries": {
+      "bereach": { "enabled": true }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": { "primary": "anthropic/claude-sonnet-4-5" },
+      "models": {
+        "anthropic/claude-sonnet-4-5": { "alias": "sonnet" }
+      }
+    }
   }
 }
 ```
 
-Or pass it via Docker environment: `docker run -e BEREACH_API_KEY=brc_xxx ...`
+**2. Environment variable** — `BEREACH_API_KEY=brc_xxx` in your shell or `export BEREACH_API_KEY="brc_xxx"` in `~/.bashrc`.
+
+**3. Docker** — pass via `-e` when launching the container: `docker run -e BEREACH_API_KEY=brc_xxx ...`
 
 Restart the Gateway after configuring.
 
+## Troubleshooting
+
+### "Cannot read properties of undefined (reading 'trim')" or "plugin disabled (not in allowlist)"
+
+OpenClaw loads plugins from **two locations**:
+- `node_modules/bereach-openclaw/` — the npm package (source)
+- `extensions/bereach/` — the active copy OpenClaw uses at runtime
+
+If `extensions/bereach/` is corrupt or incomplete, you get trim/undefined errors. Fix:
+
+**1. Backup and remove the active extension:**
+```bash
+mv /data/.openclaw/extensions/bereach /data/.openclaw/extensions/bereach.bak.$(date +%s)
+```
+
+**2. Reinstall from npm (inside the container):**
+```bash
+cd /data/.openclaw
+npm i bereach-openclaw@latest
+```
+
+**3. Restart OpenClaw** so it rebuilds `extensions/bereach/` from the package.
+
+**4. If `extensions/bereach/` is still incomplete after restart**, force a symlink:
+```bash
+rm -rf /data/.openclaw/extensions/bereach
+ln -s /data/.openclaw/node_modules/bereach-openclaw /data/.openclaw/extensions/bereach
+# then restart the container
+```
+
+**5. Verify** — compare the two manifests:
+```bash
+wc -l /data/.openclaw/extensions/bereach/openclaw.plugin.json
+wc -l /data/.openclaw/node_modules/bereach-openclaw/openclaw.plugin.json
+```
+They should match. Per [OpenClaw Plugin Manifest](https://docs.openclaw.ai/plugins/manifest), tools are registered at runtime via `api.registerTool()`.
+
 ## Usage
 
 ### Tools (33 registered)

package/openclaw.plugin.json

@@ -1,10 +1,13 @@
 {
   "id": "bereach",
   "name": "BeReach",
+  "version": "0.2.10",
   "description": "LinkedIn outreach automation — 33 tools, auto-reply commands, campaign monitoring",
   "configSchema": {
     "type": "object",
-    "required": ["BEREACH_API_KEY"],
+    "required": [
+      "BEREACH_API_KEY"
+    ],
     "additionalProperties": false,
     "properties": {
       "BEREACH_API_KEY": {
@@ -20,5 +23,8 @@
       "sensitive": true,
       "placeholder": "brc_..."
     }
-  }
+  },
+  "skills": [
+    "skills/bereach"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bereach-openclaw",
-  "version": "0.2.7",
+  "version": "0.2.10",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "scripts": {
@@ -15,6 +15,7 @@
     "bereach": "^0.1.4"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }

package/scripts/test-register.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env tsx
+/// <reference types="node" />
 /**
  * Simulates OpenClaw plugin registration to catch config/trim errors.
  * Run: pnpm exec tsx scripts/test-register.ts
@@ -10,13 +11,13 @@ import register from "../src/index";
 const apiKey = process.env.BEREACH_API_KEY || "brc_test_placeholder";
 
 const mockApi = {
-  config: { BEREACH_API_KEY: apiKey },
+  pluginConfig: { BEREACH_API_KEY: apiKey },
   registerTool: () => {},
   registerCommand: () => {},
   registerCli: () => {},
 };
 
-console.log("Testing plugin register (simulates OpenClaw load)...");
+console.log("Testing plugin register with config (simulates OpenClaw load)...");
 try {
   register(mockApi);
   console.log("✓ register() completed — no trim/undefined errors");
@@ -24,3 +25,14 @@ try {
   console.error("✗ register() failed:", err?.message || err);
   process.exit(1);
 }
+
+console.log("\nTesting plugin register WITHOUT config (should load, fail on first use)...");
+try {
+  register({ pluginConfig: undefined, registerTool: () => {}, registerCommand: () => {}, registerCli: () => {} });
+  console.log("✓ register() completed — plugin loads without config (lazy init)");
+} catch (err: any) {
+  console.error("✗ register() failed with missing config:", err?.message || err);
+  process.exit(1);
+}
+
+console.log("\n✓ All tests passed");

package/src/client.ts

@@ -1,12 +1,22 @@
 import { Bereach } from "bereach";
 
 let instance: Bereach | null = null;
+let pendingKey: string | undefined;
+
+function normalizeKey(raw: unknown): string | undefined {
+  if (raw == null) return undefined;
+  const s = typeof raw === "string" ? raw : String(raw);
+  const t = s.trim();
+  return t.length > 0 ? t : undefined;
+}
+
+export function setApiKey(key: string | undefined): void {
+  pendingKey = normalizeKey(key);
+}
 
 export function createClient(key?: string): Bereach {
   if (!instance) {
-    const raw = key ?? process.env.BEREACH_API_KEY;
-    const apiKey =
-      typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
+    const apiKey = normalizeKey(key ?? pendingKey ?? process.env.BEREACH_API_KEY);
     if (!apiKey) {
       throw new Error(
         "BEREACH_API_KEY is required (set in plugin config or environment)",
@@ -16,3 +26,7 @@ export function createClient(key?: string): Bereach {
   }
   return instance;
 }
+
+export function getClient(): Bereach {
+  return createClient();
+}

package/src/commands/index.ts

@@ -1,14 +1,16 @@
-import type { Bereach } from "bereach";
+import { getClient } from "../client";
 
 /**
  * Registers auto-reply commands and CLI commands.
  * Auto-reply commands execute without invoking the LLM.
+ * Client is created lazily on first command invocation.
  */
-export function registerCommands(api: any, client: Bereach) {
+export function registerCommands(api: any) {
   api.registerCommand({
     name: "bereach-credits",
     description: "Show current BeReach credit balance",
     handler: async () => {
+      const client = getClient();
       const res = await (client as any).profile.getCredits();
       const c = res.credits;
       return {
@@ -24,6 +26,7 @@ export function registerCommands(api: any, client: Bereach) {
     name: "bereach-status",
     description: "Show LinkedIn rate limit summary",
     handler: async () => {
+      const client = getClient();
       const res = await (client as any).profile.getLimits();
       const lines = ["BeReach Rate Limits:"];
       for (const [action, data] of Object.entries(res.limits) as [string, any][]) {
@@ -38,6 +41,7 @@ export function registerCommands(api: any, client: Bereach) {
     name: "bereach-limits",
     description: "Show detailed per-action LinkedIn rate limits",
     handler: async () => {
+      const client = getClient();
       const res = await (client as any).profile.getLimits();
       const lines = [`BeReach Rate Limits (multiplier: ${res.multiplier}x):`];
       for (const [action, data] of Object.entries(res.limits) as [string, any][]) {
@@ -62,6 +66,7 @@ export function registerCommands(api: any, client: Bereach) {
         .command("status")
         .description("Show LinkedIn rate limit summary")
         .action(async () => {
+          const client = getClient();
           const res = await (client as any).profile.getLimits();
           console.log("BeReach Rate Limits:");
           for (const [action, data] of Object.entries(res.limits) as [string, any][]) {

package/src/index.ts

@@ -1,18 +1,18 @@
-import { createClient } from "./client";
+import { setApiKey } from "./client";
 import { registerAllTools } from "./tools";
 import { registerCommands } from "./commands";
 
 function getApiKey(api: any): string | undefined {
-  const cfg = api?.config;
   const key =
-    cfg?.BEREACH_API_KEY ??
-    cfg?.plugins?.entries?.bereach?.config?.BEREACH_API_KEY;
+    api?.pluginConfig?.BEREACH_API_KEY ?? // 1. OpenClaw config (plugins.entries.bereach.config)
+    api?.config?.BEREACH_API_KEY ?? // 2. Fallback config path
+    process.env.BEREACH_API_KEY; // 3. Env var (or ~/.bashrc export)
   return typeof key === "string" && key.trim().length > 0 ? key.trim() : undefined;
 }
 
 export default function register(api: any) {
   const apiKey = getApiKey(api);
-  const client = createClient(apiKey);
-  registerAllTools(api, client);
-  registerCommands(api, client);
+  setApiKey(apiKey);
+  registerAllTools(api);
+  registerCommands(api);
 }

package/src/tools/index.ts

@@ -1,23 +1,28 @@
+import { getClient } from "./../client";
 import { definitions } from "./definitions";
-import type { Bereach } from "bereach";
 
 /**
  * Registers all 33 BeReach tools with the OpenClaw agent.
- * Each tool delegates to the corresponding SDK method via dot-path resolution.
+ * Format per https://docs.openclaw.ai/plugins/agent-tools
+ * optional: true — tools have side effects (messages, connections) and require BEREACH_API_KEY
  */
-export function registerAllTools(api: any, client: Bereach) {
+export function registerAllTools(api: any) {
   for (const def of definitions) {
     api.registerTool(
-      def.name,
       {
+        name: def.name,
         description: def.description,
         parameters: def.parameters,
+        async execute(_id: string, params: Record<string, unknown>) {
+          const client = getClient();
+          const [resource, method] = def.handler.split(".");
+          const result = await (client as any)[resource][method](params);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+          };
+        },
       },
-      async (params: Record<string, unknown>) => {
-        const [resource, method] = def.handler.split(".");
-        const result = await (client as any)[resource][method](params);
-        return result;
-      },
+      { optional: true },
     );
   }
 }

package/tsconfig.json

@@ -8,7 +8,8 @@
     "skipLibCheck": true,
     "outDir": "dist",
     "rootDir": "src",
-    "declaration": true
+    "declaration": true,
+    "types": ["node"]
   },
   "include": ["src/**/*.ts"],
   "exclude": ["__tests__", "node_modules", "dist"]