bereach-openclaw 0.3.2 → 0.3.4

package/__tests__/helpers.test.ts

@@ -8,6 +8,8 @@ import {
   withRetry,
   SkippableError,
   FatalError,
+  isWithinActiveHours,
+  printRecap,
 } from "../src/lead-magnet/helpers";
 
 beforeEach(() => {
@@ -39,8 +41,13 @@ function createMockClient(overrides: Partial<Record<string, Record<string, unkno
     },
     campaigns: {
       syncActions: vi.fn(),
+      getStats: vi.fn(),
       ...overrides.campaigns,
     },
+    profile: {
+      getCredits: vi.fn(),
+      ...overrides.profile,
+    },
   } as unknown as Bereach;
 }
 
@@ -682,3 +689,67 @@ describe("findConversationForDmGuard", () => {
     expect(result.skip).toBe(true);
   });
 });
+
+// ── isWithinActiveHours ──────────────────────────────────────────────
+
+describe("isWithinActiveHours", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.spyOn(globalThis, "setTimeout").mockImplementation(((cb: () => void) => {
+      cb();
+      return 0;
+    }) as unknown as typeof setTimeout);
+  });
+
+  it("returns true when current time is within default window", () => {
+    vi.setSystemTime(new Date("2026-03-05T14:00:00Z"));
+    expect(isWithinActiveHours({})).toBe(true);
+  });
+
+  it("returns false when outside custom window", () => {
+    vi.setSystemTime(new Date("2026-03-05T04:00:00Z"));
+    expect(isWithinActiveHours({ activeHours: { start: "09:00", end: "17:00" }, timezone: "UTC" })).toBe(false);
+  });
+
+  it("returns true when inside custom window", () => {
+    vi.setSystemTime(new Date("2026-03-05T12:00:00Z"));
+    expect(isWithinActiveHours({ activeHours: { start: "09:00", end: "17:00" }, timezone: "UTC" })).toBe(true);
+  });
+});
+
+// ── printRecap ───────────────────────────────────────────────────────
+
+describe("printRecap", () => {
+  it("calls getStats and getCredits and logs recap", async () => {
+    const client = createMockClient();
+    (client.campaigns.getStats as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      stats: { message: 5, reply: 3, like: 10 },
+      totalProfiles: 15,
+      creditsUsed: 18,
+    } as never);
+    (client.profile.getCredits as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      credits: { current: 50, limit: 1000, remaining: 950 },
+    } as never);
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await printRecap(client, "test-campaign");
+
+    expect(client.campaigns.getStats).toHaveBeenCalledWith({ campaignSlug: "test-campaign" });
+    expect(client.profile.getCredits).toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("test-campaign"));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("15 people reached"));
+    logSpy.mockRestore();
+  });
+
+  it("never throws on API error", async () => {
+    const client = createMockClient();
+    (client.campaigns.getStats as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      Object.assign(new Error("server error"), { statusCode: 500 }),
+    );
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await expect(printRecap(client, "failing-campaign")).resolves.toBeUndefined();
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("Recap unavailable"));
+    logSpy.mockRestore();
+  });
+});

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "bereach",
   "name": "BeReach",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "LinkedIn outreach automation — 33 tools, auto-reply commands",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "bereach-openclaw",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "exports": {
-    ".": "./src/index.ts",
-    "./lead-magnet": "./src/lead-magnet/helpers.ts"
+    ".": "./src/index.ts"
   },
   "scripts": {
-    "test:register": "tsx scripts/test-register.ts",
     "test": "vitest run"
   },
   "openclaw": {
@@ -17,10 +15,10 @@
     ]
   },
   "dependencies": {
-    "bereach": "^0.2.1"
+    "bereach": "^0.1.4"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.19.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/skills/bereach/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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: 1772701953
+lastUpdatedAt: 1772724697
 metadata: { "openclaw": { "requires": { "env": ["BEREACH_API_KEY"] }, "primaryEnv": "BEREACH_API_KEY" } }
 ---
 
@@ -17,7 +17,7 @@ Automate LinkedIn prospection and engagement via BeReach.
 
 | Sub-skill             | Keywords                                                                                                                  | URL                                                     | lastUpdatedAt |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------- |
-| Lead Magnet           | lead magnet, comment to DM, resource delivery, post giveaway, auto-accept invitations, scheduled run, recap, campaign stats, pause | sub/lead-magnet.md       | 1772701953    |
+| Lead Magnet           | lead magnet, comment to DM, resource delivery, post giveaway, auto-accept invitations, scheduled run, recap, campaign stats, pause | sub/lead-magnet.md       | 1772724697    |
 | 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         | 1772672714             |
 

package/skills/bereach/sub/lead-magnet.md

@@ -1,7 +1,7 @@
 ---
 name: bereach-lead-magnet
 description: "Lead magnet workflow — deliver a resource to everyone who engages with a LinkedIn post."
-lastUpdatedAt: 1772701953
+lastUpdatedAt: 1772724697
 ---
 
 # BeReach Lead Magnet Skill
@@ -24,51 +24,43 @@ All lead magnet scripts MUST be TypeScript using the `bereach` SDK (see main ski
 2. **Step 2** — `npx tsx <script-name>.ts`. Fix runtime errors (e.g. undefined method, wrong resource). If config missing, run with minimal env to reach first SDK call.
 3. **Both must succeed** — tsx passing alone is NOT sufficient. Only save or paste the script when BOTH succeed.
 
-## Helpers
+## Helpers (reference patterns — do NOT import)
 
-`bereach-openclaw` ships helper functions that handle the patterns most likely to go wrong: pagination, SDK path selection, and DM guard logic. Use them to avoid common mistakes. If you need custom behavior, you can call the SDK directly — but understand why the helper exists first.
+Before writing any lead-magnet script, read `plugins/openclaw/src/lead-magnet/helpers.ts` as context. It contains battle-tested implementations for the patterns most likely to go wrong: pagination, SDK path selection, error handling, and DM guard logic. **Do not import this file** — it is not an npm package. Instead, replicate the relevant patterns inline in your script using the raw `bereach` SDK.
 
-```typescript
-import {
-  collectAllComments,
-  listAllInvitations,
-  visitProfileIfNeeded,
-  findConversationForDmGuard,
-} from "bereach-openclaw/lead-magnet";
-```
+### withRetry(fn, maxRetries?)
 
-Your spec should list which helpers you plan to use.
+Wraps any SDK call. Retries on 429 with exponential backoff (`2^attempts` seconds). Throws `FatalError` on 401/404/405, `SkippableError` on everything else.
 
-### collectAllComments(client, postUrl, campaignSlug, opts?)
+### isWithinActiveHours(campaign)
 
-Paginates `collectComments` automatically (`while hasMore`, `start += 100`). Prevents the most common bug: fetching only the first 100 comments.
+Checks if current time is within the campaign's `activeHours` window in the campaign's `timezone`. Defaults to 07:00-23:00 Europe/Paris.
 
-- `opts.previousTotal` — pass the stored total from last run. Does a free `count: 0` check first; if unchanged, returns `{ skipped: true }` immediately.
-- Returns `{ profiles, total, skipped }`.
+### printRecap(client, campaignSlug)
 
-### listAllInvitations(client)
+Calls `getStats` + `getCredits` and prints a human-friendly end-of-run recap. Async.
 
-Paginates `listInvitations` automatically (`while total > start + count`, `count: 100`). Prevents fetching only the first 10 invitations.
+### collectAllComments(client, postUrl, campaignSlug, opts?)
 
-- Returns `{ invitations, total }`.
+Paginates `collectComments` (`while hasMore`, `start += 100`). Returns `{ profiles, total, skipped }`.
 
-### visitProfileIfNeeded(client, profile, campaignSlug, knownDistance)
+- `opts.previousTotal` — does a free `count: 0` check first; if unchanged, returns `{ skipped: true }` immediately.
+
+### listAllInvitations(client)
 
-If `knownDistance` is already set (including 0): returns it immediately (0 credits). If `null`/`undefined`: calls `client.linkedinScrapers.visitProfile` (correct path — not `linkedinActions`).
+Paginates `listInvitations` (`while total > start + count`, `count: 100`). Returns `{ invitations, total }`.
 
-Prevents two bugs:
-- `knownDistance || 2` — when `knownDistance` is null, the fallback should be a visit, not an assumption.
-- `client.linkedinActions.visitProfile` — wrong namespace (doesn't exist).
+### visitProfileIfNeeded(client, profile, campaignSlug, knownDistance)
 
-Returns `{ memberDistance, pendingConnection, visited, firstName, headline, ... }`.
+If `knownDistance` is set (including 0): returns it immediately (0 credits). Otherwise calls `client.linkedinScrapers.visitProfile` (not `linkedinActions`). Uses `!= null` (not `||`). Returns `{ memberDistance, pendingConnection, visited, ... }`.
 
 ### findConversationForDmGuard(client, profile, resourceLink, campaignSlug)
 
-Checks whether `resourceLink` was already sent via DM. Uses `client.linkedinChat.findConversation` (correct path — not `linkedinInbox`). Reads `messages` at the top level (not nested).
+Checks whether `resourceLink` was already sent via DM. Uses `client.linkedinChat.findConversation` (not `linkedinInbox`). Reads `messages` at the top level (not nested).
 
-- If link found: syncs action via `syncActions`, returns `{ skip: true, messages }`.
-- If no link: returns `{ skip: false, messages }` — messages available for DM tone adaptation.
-- On error: returns `{ skip: true }` — fail-safe, never DM on lookup failure.
+- Link found → syncs action, returns `{ skip: true, messages }`.
+- No link → returns `{ skip: false, messages }` (messages available for DM tone adaptation).
+- Error → returns `{ skip: true }` (fail-safe).
 
 ## Tone
 
@@ -152,12 +144,13 @@ All 3 scripts must perform pre-flight at the start of each run:
 
 Each script:
 
-1. Reads `~/.bereach/lead-magnet.json`
-2. Filters `campaigns` where `enabled !== false`
-3. For each campaign: acquire lock `lm-{slug}-{script}` (see "Lock mechanism" below). If locked, skip that campaign — a previous run is still active.
-4. Runs its logic for the campaign.
-5. Prints recap per campaign, releases lock, moves to next campaign.
-6. At end: aggregate recap for all campaigns.
+1. Reads `~/.bereach/lead-magnet.json`, validates config (see "Config validation"), filters `campaigns` where `enabled !== false`.
+2. For each campaign: `isWithinActiveHours(campaign)` — skip if outside window.
+3. Acquire lock `lm-{slug}-{script}` (see "Lock mechanism" below). If locked, skip that campaign.
+4. Wrap every SDK call in `withRetry(...)` — handles 429 retries and error classification.
+5. Runs its logic for the campaign.
+6. `printRecap(client, campaignSlug)` — prints human-friendly stats, releases lock, moves to next campaign.
+7. At end: aggregate recap for all campaigns.
 
 BeReach dedup ensures no action is performed twice across scripts (same `campaignSlug`).
 
@@ -196,8 +189,9 @@ For each campaign (from config): scrape commenters and engage them.
 
 Accept pending invitations and deliver the resource to campaign-related invitees.
 
+- **Build attribution map first**: for each enabled campaign, call `collectAllComments(client, postUrl, campaignSlug)` and build a `Map<profileUrl, campaign>` from all commenters. This map tells you which campaign an inviter belongs to.
 - `listAllInvitations(client)` → `{ invitations, total }`. Each invitation has: `invitationId`, `sharedSecret`, `fromMember: { name, profileUrl }`. Pagination is handled by the helper.
-- **Campaign attribution**: the helper returns ALL pending invitations. Cross-reference each inviter against campaign commenter lists to find which campaign (if any) they belong to. Accept all invitations, but only DM if campaign-matched.
+- **Campaign attribution**: look up `invitation.fromMember.profileUrl` in the map. If found, that invitation is campaign-related. Accept all invitations, but only DM if campaign-matched.
 - For each invitation:
   1. `acceptInvitation` with `invitationId` and `sharedSecret`
   2. If campaign matched: `visitProfileIfNeeded(client, profile, campaignSlug, null)`, then **DM dedup** → DM if not already sent.
@@ -275,19 +269,7 @@ The user can pause or resume any campaign by setting `enabled: false` in `~/.ber
 
 ### Recap (print after each run)
 
-At the end of every run, call these two methods and print the recap:
-
-1. `getStats` with `campaignSlug` → `{ stats: { message, reply, like, visit, connect }, totalProfiles, creditsUsed }`
-2. `getCredits` → `{ credits: { current, limit, remaining, percentage } }`
-
-Human-friendly, no jargon. Format:
-
-    {slug} — Recap
-    {totalProfiles} people reached
-    {stats.message} DMs sent · {stats.reply} replies · {stats.like} likes
-    Credits: {credits.current} used · {credits.remaining}/{credits.limit} remaining
-
-    You can ask me to disable features to save credits.
+Use `printRecap(client, campaignSlug)` — see Helpers section. It handles `getStats` + `getCredits` and formats the output.
 
 ### Toggleable features
 

package/src/commands/index.ts

@@ -11,7 +11,7 @@ export function registerCommands(api: any) {
     description: "Show current BeReach credit balance",
     handler: async () => {
       const client = getClient();
-      const res = await (client as any).profile.getCredits();
+      const res = await client.profile.getCredits();
       const c = res.credits;
       return {
         text: [
@@ -27,7 +27,7 @@ export function registerCommands(api: any) {
     description: "Show LinkedIn rate limit summary",
     handler: async () => {
       const client = getClient();
-      const res = await (client as any).profile.getLimits();
+      const res = await client.profile.getLimits();
       const lines = ["BeReach Rate Limits:"];
       for (const [action, data] of Object.entries(res.limits) as [string, any][]) {
         const d = data.daily;
@@ -42,7 +42,7 @@ export function registerCommands(api: any) {
     description: "Show detailed per-action LinkedIn rate limits",
     handler: async () => {
       const client = getClient();
-      const res = await (client as any).profile.getLimits();
+      const res = await client.profile.getLimits();
       const lines = [`BeReach Rate Limits (multiplier: ${res.multiplier}x):`];
       for (const [action, data] of Object.entries(res.limits) as [string, any][]) {
         const d = data.daily;
@@ -67,7 +67,7 @@ export function registerCommands(api: any) {
         .description("Show LinkedIn rate limit summary")
         .action(async () => {
           const client = getClient();
-          const res = await (client as any).profile.getLimits();
+          const res = await client.profile.getLimits();
           console.log("BeReach Rate Limits:");
           for (const [action, data] of Object.entries(res.limits) as [string, any][]) {
             const d = data.daily;

package/src/lead-magnet/helpers.ts

@@ -64,6 +64,7 @@ export async function collectAllComments(
     if (check.total === opts.previousTotal) {
       return { profiles: [] as CollectLinkedInCommentsProfile[], total: opts.previousTotal, skipped: true };
     }
+    await readPause();
   }
 
   const allProfiles: CollectLinkedInCommentsProfile[] = [];
@@ -153,7 +154,7 @@ export async function findConversationForDmGuard(
   if (!data.found) return { skip: false, messages: [] };
 
   const messages = data.messages ?? [];
-  const alreadySent = messages.some((m) => (m.text ?? "").includes(resourceLink));
+  const alreadySent = messages.some((m) => m.text.includes(resourceLink));
 
   if (alreadySent) {
     try {
@@ -169,3 +170,38 @@ export async function findConversationForDmGuard(
 
   return { skip: false, messages };
 }
+
+/** Check if current time is within campaign active hours. Defaults to 07:00-23:00 Europe/Paris. */
+export function isWithinActiveHours(campaign: {
+  activeHours?: { start: string; end: string };
+  timezone?: string;
+}): boolean {
+  const { start = "07:00", end = "23:00" } = campaign.activeHours ?? {};
+  const tz = campaign.timezone ?? "Europe/Paris";
+  const now = new Intl.DateTimeFormat("en-GB", {
+    timeZone: tz,
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(new Date());
+  return now >= start && now < end;
+}
+
+/** Print end-of-run recap: campaign stats + credit balance. Never throws. */
+export async function printRecap(client: Bereach, campaignSlug: string): Promise<void> {
+  try {
+    const stats = await withRetry(() => client.campaigns.getStats({ campaignSlug }));
+    const credits = await withRetry(() => client.profile.getCredits());
+
+    console.log(`\n${campaignSlug} — Recap`);
+    console.log(`${stats.totalProfiles} people reached`);
+    console.log(
+      `${stats.stats.message ?? 0} DMs sent · ${stats.stats.reply ?? 0} replies · ${stats.stats.like ?? 0} likes`,
+    );
+    console.log(
+      `Credits: ${credits.credits.current} used · ${credits.credits.remaining}/${credits.credits.limit} remaining`,
+    );
+  } catch {
+    console.log(`\n${campaignSlug} — Recap unavailable (API error)`);
+  }
+}