bereach-openclaw 0.2.0

package/README.md

@@ -0,0 +1,70 @@
+# BeReach — OpenClaw Plugin
+
+LinkedIn outreach automation via [BeReach](https://berea.ch). Registers 33 in-process tools, auto-reply commands, and a campaign monitoring service.
+
+## Install
+
+```bash
+openclaw plugins install bereach-openclaw
+```
+
+## Setup
+
+Set your API key in OpenClaw config (`~/.openclaw/openclaw.json`):
+
+```json5
+{
+  plugins: {
+    entries: {
+      bereach: {
+        enabled: true,
+        config: {
+          BEREACH_API_KEY: "brc_your_token_here"
+        }
+      }
+    }
+  }
+}
+```
+
+Or pass it via Docker environment: `docker run -e BEREACH_API_KEY=brc_xxx ...`
+
+Restart the Gateway after configuring.
+
+## Usage
+
+### Tools (33 registered)
+
+All BeReach operations are available as agent tools — the agent uses them automatically based on your requests. No MCP needed; tools run in-process via the `bereach` SDK.
+
+### Auto-reply commands
+
+These execute instantly without invoking the AI:
+
+| Command | Description |
+| --- | --- |
+| `/bereach-credits` | Show current credit balance |
+| `/bereach-status` | Show LinkedIn rate limit summary |
+| `/bereach-limits` | Show detailed per-action rate limits |
+
+### CLI
+
+```bash
+openclaw bereach status
+```
+
+### Campaign monitor
+
+A background service polls active campaigns every 5 minutes and logs activity deltas (new actions since last check).
+
+## What's included
+
+| Component | Description |
+| --- | --- |
+| `src/tools/` | 33 tool definitions generated from OpenAPI |
+| `src/commands/` | Auto-reply commands + CLI |
+| `src/services/` | Campaign monitoring service |
+| `skills/bereach/SKILL.md` | Main behavioral skill |
+| `skills/bereach/sub/lead-magnet.md` | Lead magnet workflow |
+| `skills/bereach/sdk-reference.md` | SDK method reference |
+| `skills/bereach/openclaw-optimization.md` | OpenClaw cost optimization guide |

package/openclaw.plugin.json

@@ -0,0 +1,24 @@
+{
+  "id": "bereach",
+  "name": "BeReach",
+  "description": "LinkedIn outreach automation — 33 tools, auto-reply commands, campaign monitoring",
+  "configSchema": {
+    "type": "object",
+    "required": ["BEREACH_API_KEY"],
+    "additionalProperties": false,
+    "properties": {
+      "BEREACH_API_KEY": {
+        "type": "string",
+        "minLength": 1,
+        "description": "BeReach API token (starts with brc_)"
+      }
+    }
+  },
+  "uiHints": {
+    "BEREACH_API_KEY": {
+      "label": "BeReach Token",
+      "sensitive": true,
+      "placeholder": "brc_..."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "bereach-openclaw",
+  "version": "0.2.0",
+  "description": "BeReach LinkedIn automation plugin for OpenClaw",
+  "license": "AGPL-3.0",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "bereach": "^0.1.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/skills/bereach/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: bereach
+description: "Automate LinkedIn outreach via BeReach (berea.ch). Use when: prospecting, engaging posts, scraping engagement, searching LinkedIn, managing inbox, running campaigns, managing invitations. Requires BEREACH_API_KEY."
+lastUpdatedAt: 1772619338
+---
+
+# BeReach — LinkedIn Outreach Automation
+
+Automate LinkedIn prospection and engagement via BeReach.
+
+## Sub-skills
+
+**At install**: fetch and read ALL sub-skills.
+
+**After install**: re-load on-demand only when needed.
+
+| Sub-skill             | Keywords                                                                                                                  | URL                                                     | lastUpdatedAt |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------- |
+| Lead Magnet           | lead magnet, comment to DM, resource delivery, post giveaway, auto-accept invitations, cron, recap, campaign stats, pause | sub/lead-magnet.md       | 1772619338    |
+| OpenClaw Optimization | openclaw, model, opus, sonnet, haiku, config, SOUL.md, heartbeat, prompt caching, AI cost reduction, /model               | openclaw-optimization.md | 1772619338    |
+| SDK Reference         | sdk, method, parameter, signature, reference, api, script                                                                 | sdk-reference.md         | 1772619338             |
+
+## Installation
+
+### Tools (interactive use)
+
+Tools are already configured by the plugin — no manual setup needed.
+
+### SDK (script generation)
+
+The TypeScript SDK provides typed methods for all BeReach operations. Use it when generating scripts (cron jobs, batch automations).
+
+```bash
+npm add bereach
+```
+
+```typescript
+import { Bereach } from "bereach";
+
+const token = process.env.BEREACH_API_KEY;
+if (!token) {
+  console.error("BEREACH_API_KEY environment variable is required");
+  process.exit(1);
+}
+const client = new Bereach({ token });
+```
+
+The SDK auto-reads `BEREACH_API_KEY` from the environment. NEVER hardcode tokens in scripts.
+
+## Onboarding
+
+1. **Token** — read `BEREACH_API_KEY` from environment with no default/fallback value. If not set, stop immediately.
+2. **Read all sub-skills** — fetch every sub-skill listed above.
+3. **Profile + language** — call `getLinkedInProfile` (tool or `client.profile.getLinkedInProfile()`). Profile inputs: URL (e.g. `https://linkedin.com/in/username`) or URN (`urn:li:fsd_profile:ACoAA...`). Detect user's language from profile (location, headline, posts). This becomes the default language for all generated content. Per prospect, adapt if their profile clearly indicates a different language.
+4. **Welcome** — personalized welcome using profile data. Suggest a first action based on their profile.
+
+## Rules
+
+### Interactive mode (tools)
+
+- Use available tools exclusively. If a tool doesn't exist, the operation doesn't exist.
+- NEVER use raw HTTP calls (fetch, axios, curl).
+
+### Script mode (SDK)
+
+- Import from the `bereach` SDK exclusively. If a method doesn't exist, the operation doesn't exist.
+- Scripts MUST be TypeScript (`.ts`). Run with `npx tsx script.ts`.
+- Run `npx tsc --noEmit` before executing to catch type errors.
+- Load the [SDK Reference](sdk-reference.md) sub-skill for method signatures.
+
+### Always
+
+- NEVER hardcode tokens. Read from `process.env.BEREACH_API_KEY`. If not set, exit immediately.
+- NEVER invent a tool/method name. Check the resources table below or tool schemas.
+- If unsure about a method: check the SDK Reference sub-skill.
+
+### SDK resources and methods
+
+| Resource | Methods |
+| --- | --- |
+| `client.linkedinScrapers` | `collectLikes`, `collectComments`, `collectCommentReplies`, `collectPosts`, `visitProfile`, `visitCompany` |
+| `client.linkedinActions` | `connectProfile`, `listInvitations`, `acceptInvitation`, `sendMessage`, `replyToComment`, `likeComment`, `publishPost` |
+| `client.linkedinChat` | `listConversations`, `searchConversations`, `findConversation`, `getMessages` |
+| `client.linkedinSearch` | `unifiedSearch`, `searchPosts`, `searchPeople`, `searchCompanies`, `searchJobs`, `searchByUrl`, `resolveParameters` |
+| `client.profile` | `getLinkedInProfile`, `refresh`, `getPosts`, `getFollowers`, `getLimits`, `getCredits` |
+| `client.campaigns` | `getStatus`, `syncActions`, `getStats` |
+
+## Tone
+
+Adapt to user's tone from their posts and messages. Comment replies: 3-5 words, no personalization needed. DMs: 1-2 sentences, personalize from visit data (headline, company, position, recent posts) and conversation history when available.
+
+## Constraints
+
+These are technical constraints BeReach requires. Everything else, adapt as needed.
+
+1. **Dedup** — pass `campaignSlug` on every action. BeReach deduplicates by target automatically. Duplicates return `duplicate: true` and cost nothing. Pre-check: use `client.campaigns.getStatus()` or the `getStatus` tool.
+2. **Pacing** — after every SDK/tool call, sleep a random delay. Write actions (DM, reply, like, connect, accept, sync): `random delay 8-12s`. Read actions (visit, scrape, find, count-0 checks): `random delay 2-6s`. On 429: wait the number of seconds from the error response, retry (max 3). If daily/weekly cap hit, switch action type.
+3. **Save incrementally** — persist tracking after each action, not at the end.
+4. **Limits check** — call `getLimits` once per day at session start.
+5. **Visit before connecting** — looks natural to LinkedIn.
+6. **Credits** — check with `getCredits` → `{credits: {current, limit, remaining, percentage}}`.
+7. **Connection requests are scarce** — only 30/day. Before sending one, check `pendingConnection` from the visit response: `"pending"` = already sent, skip. `"failed"` = failed today, skip. `"none"` = safe to send.
+8. **Error handling** — wrap every SDK call in a shared helper. The wrapper must check the **error type** to branch:
+   - `429`: wait `error.retryAfter` seconds, retry (max 3). All retries fail → skip profile, move on.
+   - `400`/`409`/`410`: log, skip item, continue.
+   - `401`: stop (auth broken).
+   - `404`/`405`: stop — method/tool doesn't exist. Re-read the SDK resources table or tool list.
+   - `500`: log, skip item, continue (transient).
+   - Parse the response body inside a try/catch — malformed JSON must not crash the script.
+   - Never treat a failed call as "success with empty result".
+   - Never `process.exit()` on transient errors — skip and continue.
+
+## Workflows
+
+Each workflow is detailed in its sub-skill. Load the relevant sub-skill when needed.
+
+- **Lead Magnet** — deliver a resource to everyone who engages with a post (comments, likes, invitations). → Lead Magnet sub-skill
+
+More workflows coming soon. You can build your own using the SDK methods and tools listed above.
+
+### Cron
+
+Crons are OpenClaw scheduled tasks. Create entries in `~/.openclaw/crons.json`:
+
+```json
+{
+  "id": "bereach-{workflow}",
+  "every": "30m",
+  "skill": "bereach",
+  "sessionTarget": "spawn",
+  "prompt": "Run {workflow} script and report results"
+}
+```
+
+Always use `"sessionTarget": "spawn"` for crons that execute scripts. This spawns a sub-agent in an isolated session — the script runs independently and pushes results back to the user when done, without blocking the main session. Never use `exec()` directly from a cron prompt; it blocks until the script finishes.
+
+Remove with `openclaw cron remove <id>`.

package/skills/bereach/openclaw-optimization.md

@@ -0,0 +1,91 @@
+---
+name: openclaw-optimization
+description: "Optimize OpenClaw for cost efficiency with Anthropic Claude. Use when: reducing AI costs, configuring model routing, configuring heartbeat, optimizing workspace files."
+lastUpdatedAt: 1772619338
+---
+
+# OpenClaw Optimization
+
+> **Anthropic only.** Skip this skill if the user is not on Anthropic Claude. Proposed during BeReach onboarding or on explicit request. If declined, don't bring it up again.
+
+## Config
+
+Merge into `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "anthropic/claude-sonnet-4-5" },
+      models: {
+        "anthropic/claude-opus-4-6": { alias: "opus" },
+        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
+        "anthropic/claude-haiku-4-5": { alias: "haiku" }
+      },
+      heartbeat: {
+        every: "1h",
+        model: "anthropic/claude-haiku-4-5"
+      }
+    }
+  }
+}
+```
+
+**Sonnet** for all general agent work (default). **Opus** for code generation and code updates — mandatory, switch to it with `/model opus` before writing or editing any code. **Haiku** for heartbeat only. Prompt caching is on by default for Anthropic, no config needed.
+
+## Model switching protocol
+
+Opus is 5x more expensive than Sonnet. Use it ONLY for the code generation step, then switch back.
+
+1. `/model opus` -- right before Write() or Edit() of code
+2. Write/Edit the code
+3. `/model sonnet` -- IMMEDIATELY after, same message
+4. Continue all other work on Sonnet (upload, cron, recap, conversation, debugging)
+
+If you forget step 3, every subsequent message costs 5x more for no benefit. The switch-back is not optional.
+
+## Workspace files
+
+Create these in `~/.openclaw/workspace/`. Keep them lean — every token is sent on every request.
+
+### HEARTBEAT.md
+
+OpenClaw reads this file on every heartbeat. If nothing needs attention, the agent replies `HEARTBEAT_OK` and the message is suppressed.
+
+```markdown
+# Heartbeat checklist
+
+- Check BeReach campaigns: new comments to process, pending connections to accept, messages to send.
+- Only report if there's something actionable.
+```
+
+### SOUL.md
+
+```markdown
+# SOUL.md
+
+## Core Principles
+
+[3-5 bullet points — user fills in]
+
+## How to Operate
+
+- Don't read extra files at session start. Use memory_search() for prior context.
+- Save incrementally after each action. Dedup via campaignSlug.
+- Before writing or editing any code: `/model opus`. IMMEDIATELY after Write/Edit: `/model sonnet`. Never stay on Opus for non-code work (upload, cron, recap, conversation).
+- Update memory/YYYY-MM-DD.md at session end with work done and next steps.
+```
+
+### USER.md
+
+```markdown
+# USER.md
+
+- **Name:** [NAME]
+- **Timezone:** [TZ]
+- **Mission:** [1-2 sentences]
+```
+
+## Verify
+
+Run `openclaw shell`, then `session_status`. Confirm: context under 8KB, default Sonnet, Opus available for code, heartbeat Haiku.