bereach-openclaw 0.2.16 → 0.3.0

package/__tests__/helpers.test.ts

@@ -0,0 +1,684 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Bereach } from "bereach";
+import {
+  collectAllComments,
+  listAllInvitations,
+  visitProfileIfNeeded,
+  findConversationForDmGuard,
+  withRetry,
+  SkippableError,
+  FatalError,
+} from "../src/lead-magnet/helpers";
+
+beforeEach(() => {
+  vi.spyOn(globalThis, "setTimeout").mockImplementation(((cb: () => void) => {
+    cb();
+    return 0;
+  }) as unknown as typeof setTimeout);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ── Mock factory ────────────────────────────────────────────────────
+
+function createMockClient(overrides: Partial<Record<string, Record<string, unknown>>> = {}) {
+  return {
+    linkedinScrapers: {
+      collectComments: vi.fn(),
+      visitProfile: vi.fn(),
+      ...overrides.linkedinScrapers,
+    },
+    linkedinActions: {
+      listInvitations: vi.fn(),
+      ...overrides.linkedinActions,
+    },
+    linkedinChat: {
+      findConversation: vi.fn(),
+      ...overrides.linkedinChat,
+    },
+    campaigns: {
+      syncActions: vi.fn(),
+      ...overrides.campaigns,
+    },
+  } as unknown as Bereach;
+}
+
+function commentsPage(
+  profiles: Array<Record<string, unknown>>,
+  opts: { total: number; start: number; hasMore: boolean },
+) {
+  return {
+    success: true,
+    profiles,
+    count: profiles.length,
+    total: opts.total,
+    start: opts.start,
+    hasMore: opts.hasMore,
+    previousTotal: null,
+    creditsUsed: 1,
+    retryAfter: 0,
+  };
+}
+
+function invitationsPage(
+  invitations: Array<Record<string, unknown>>,
+  opts: { total: number; start: number },
+) {
+  return {
+    success: true,
+    invitations,
+    total: opts.total,
+    start: opts.start,
+    count: invitations.length,
+    creditsUsed: 1,
+    retryAfter: 0,
+  };
+}
+
+// ── withRetry ───────────────────────────────────────────────────────
+
+describe("withRetry", () => {
+  it("returns result on success", async () => {
+    const result = await withRetry(() => Promise.resolve(42));
+    expect(result).toBe(42);
+  });
+
+  it("retries on 429 (statusCode) and succeeds", async () => {
+    let calls = 0;
+    const result = await withRetry(async () => {
+      calls++;
+      if (calls < 3) {
+        throw Object.assign(new Error("rate limited"), { statusCode: 429 });
+      }
+      return "ok";
+    });
+    expect(result).toBe("ok");
+    expect(calls).toBe(3);
+  });
+
+  it("retries on 429 (status fallback) and succeeds", async () => {
+    let calls = 0;
+    const result = await withRetry(async () => {
+      calls++;
+      if (calls < 2) {
+        throw Object.assign(new Error("rate limited"), { status: 429 });
+      }
+      return "ok";
+    });
+    expect(result).toBe("ok");
+    expect(calls).toBe(2);
+  });
+
+  it("throws FatalError on 401", async () => {
+    await expect(
+      withRetry(() => {
+        throw Object.assign(new Error("unauthorized"), { statusCode: 401 });
+      }),
+    ).rejects.toThrow(FatalError);
+  });
+
+  it("throws FatalError on 404", async () => {
+    await expect(
+      withRetry(() => {
+        throw Object.assign(new Error("not found"), { statusCode: 404 });
+      }),
+    ).rejects.toThrow(FatalError);
+  });
+
+  it("throws FatalError on 405", async () => {
+    await expect(
+      withRetry(() => {
+        throw Object.assign(new Error("not allowed"), { statusCode: 405 });
+      }),
+    ).rejects.toThrow(FatalError);
+  });
+
+  it("throws SkippableError on 400", async () => {
+    await expect(
+      withRetry(() => {
+        throw Object.assign(new Error("bad request"), { statusCode: 400 });
+      }),
+    ).rejects.toThrow(SkippableError);
+  });
+
+  it("throws SkippableError on 500", async () => {
+    await expect(
+      withRetry(() => {
+        throw Object.assign(new Error("server error"), { statusCode: 500 });
+      }),
+    ).rejects.toThrow(SkippableError);
+  });
+
+  it("throws SkippableError after exhausting 429 retries", async () => {
+    await expect(
+      withRetry(
+        () => {
+          throw Object.assign(new Error("rate limited"), { statusCode: 429 });
+        },
+        2,
+      ),
+    ).rejects.toThrow(SkippableError);
+  });
+
+  it("throws SkippableError on errors without status", async () => {
+    await expect(
+      withRetry(() => {
+        throw new Error("generic failure");
+      }),
+    ).rejects.toThrow(SkippableError);
+  });
+});
+
+// ── collectAllComments ──────────────────────────────────────────────
+
+describe("collectAllComments", () => {
+  it("fetches a single page when hasMore is false", async () => {
+    const profiles = [{ name: "Alice", profileUrl: "u/alice" }];
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.collectComments);
+    mock.mockResolvedValueOnce(commentsPage(profiles, { total: 1, start: 0, hasMore: false }));
+
+    const result = await collectAllComments(client, "https://post", "slug");
+
+    expect(result.profiles).toHaveLength(1);
+    expect(result.total).toBe(1);
+    expect(result.skipped).toBe(false);
+    expect(mock).toHaveBeenCalledTimes(1);
+    expect(mock).toHaveBeenCalledWith({ postUrl: "https://post", start: 0, count: 100, campaignSlug: "slug" });
+  });
+
+  it("paginates across 3 pages", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.collectComments);
+
+    const page1 = Array.from({ length: 100 }, (_, i) => ({ name: `p${i}` }));
+    const page2 = Array.from({ length: 100 }, (_, i) => ({ name: `p${100 + i}` }));
+    const page3 = [{ name: "p200" }, { name: "p201" }];
+
+    mock
+      .mockResolvedValueOnce(commentsPage(page1, { total: 202, start: 0, hasMore: true }))
+      .mockResolvedValueOnce(commentsPage(page2, { total: 202, start: 100, hasMore: true }))
+      .mockResolvedValueOnce(commentsPage(page3, { total: 202, start: 200, hasMore: false }));
+
+    const result = await collectAllComments(client, "https://post", "slug");
+
+    expect(result.profiles).toHaveLength(202);
+    expect(result.total).toBe(202);
+    expect(result.skipped).toBe(false);
+    expect(mock).toHaveBeenCalledTimes(3);
+  });
+
+  it("skips when previousTotal matches current total", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.collectComments);
+    mock.mockResolvedValueOnce(commentsPage([], { total: 50, start: 0, hasMore: false }));
+
+    const result = await collectAllComments(client, "https://post", "slug", { previousTotal: 50 });
+
+    expect(result.skipped).toBe(true);
+    expect(result.profiles).toHaveLength(0);
+    expect(result.total).toBe(50);
+    expect(mock).toHaveBeenCalledTimes(1);
+    expect(mock).toHaveBeenCalledWith({ postUrl: "https://post", count: 0 });
+  });
+
+  it("fetches when previousTotal differs from current total", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.collectComments);
+
+    mock
+      .mockResolvedValueOnce(commentsPage([], { total: 55, start: 0, hasMore: false }))
+      .mockResolvedValueOnce(
+        commentsPage([{ name: "new" }], { total: 55, start: 0, hasMore: false }),
+      );
+
+    const result = await collectAllComments(client, "https://post", "slug", { previousTotal: 50 });
+
+    expect(result.skipped).toBe(false);
+    expect(mock).toHaveBeenCalledTimes(2);
+  });
+
+  it("handles empty post (0 comments)", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.collectComments);
+    mock.mockResolvedValueOnce(commentsPage([], { total: 0, start: 0, hasMore: false }));
+
+    const result = await collectAllComments(client, "https://post", "slug");
+
+    expect(result.profiles).toHaveLength(0);
+    expect(result.total).toBe(0);
+    expect(result.skipped).toBe(false);
+  });
+
+  it("does not pass previousTotal=0 as no-op (0 is a valid total)", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.collectComments);
+    mock.mockResolvedValueOnce(commentsPage([], { total: 0, start: 0, hasMore: false }));
+
+    const result = await collectAllComments(client, "https://post", "slug", { previousTotal: 0 });
+
+    expect(result.skipped).toBe(true);
+    expect(result.total).toBe(0);
+    expect(mock).toHaveBeenCalledTimes(1);
+    expect(mock).toHaveBeenCalledWith({ postUrl: "https://post", count: 0 });
+  });
+});
+
+// ── listAllInvitations ──────────────────────────────────────────────
+
+describe("listAllInvitations", () => {
+  it("fetches a single page when total <= count", async () => {
+    const invitations = [{ invitationId: "1", sharedSecret: "s1", entityUrn: "u1" }];
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinActions.listInvitations);
+    mock.mockResolvedValueOnce(invitationsPage(invitations, { total: 1, start: 0 }));
+
+    const result = await listAllInvitations(client);
+
+    expect(result.invitations).toHaveLength(1);
+    expect(result.total).toBe(1);
+    expect(mock).toHaveBeenCalledTimes(1);
+  });
+
+  it("paginates across 2 pages", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinActions.listInvitations);
+
+    const page1 = Array.from({ length: 100 }, (_, i) => ({
+      invitationId: `${i}`,
+      sharedSecret: `s${i}`,
+      entityUrn: `u${i}`,
+    }));
+    const page2 = [{ invitationId: "100", sharedSecret: "s100", entityUrn: "u100" }];
+
+    mock
+      .mockResolvedValueOnce(invitationsPage(page1, { total: 101, start: 0 }))
+      .mockResolvedValueOnce(invitationsPage(page2, { total: 101, start: 100 }));
+
+    const result = await listAllInvitations(client);
+
+    expect(result.invitations).toHaveLength(101);
+    expect(result.total).toBe(101);
+    expect(mock).toHaveBeenCalledTimes(2);
+  });
+
+  it("handles no pending invitations", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinActions.listInvitations);
+    mock.mockResolvedValueOnce(invitationsPage([], { total: 0, start: 0 }));
+
+    const result = await listAllInvitations(client);
+
+    expect(result.invitations).toHaveLength(0);
+    expect(result.total).toBe(0);
+  });
+
+  it("handles exactly 100 invitations (boundary: total === start + count)", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinActions.listInvitations);
+
+    const page = Array.from({ length: 100 }, (_, i) => ({
+      invitationId: `${i}`,
+      sharedSecret: `s${i}`,
+      entityUrn: `u${i}`,
+    }));
+    mock.mockResolvedValueOnce(invitationsPage(page, { total: 100, start: 0 }));
+
+    const result = await listAllInvitations(client);
+
+    expect(result.invitations).toHaveLength(100);
+    expect(mock).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ── visitProfileIfNeeded ────────────────────────────────────────────
+
+describe("visitProfileIfNeeded", () => {
+  it("returns knownDistance without visiting when set", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+
+    const result = await visitProfileIfNeeded(client, "u/alice", "slug", 1);
+
+    expect(result.memberDistance).toBe(1);
+    expect(result.visited).toBe(false);
+    expect(result.pendingConnection).toBeNull();
+    expect(mock).not.toHaveBeenCalled();
+  });
+
+  it("returns knownDistance=0 without visiting (0 is valid)", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+
+    const result = await visitProfileIfNeeded(client, "u/alice", "slug", 0);
+
+    expect(result.memberDistance).toBe(0);
+    expect(result.visited).toBe(false);
+    expect(mock).not.toHaveBeenCalled();
+  });
+
+  it("returns knownDistance=2 without visiting", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+
+    const result = await visitProfileIfNeeded(client, "u/alice", "slug", 2);
+
+    expect(result.memberDistance).toBe(2);
+    expect(result.visited).toBe(false);
+    expect(mock).not.toHaveBeenCalled();
+  });
+
+  it("calls linkedinScrapers.visitProfile when knownDistance is null", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+    mock.mockResolvedValueOnce({
+      success: true,
+      firstName: "Alice",
+      lastName: "Smith",
+      headline: "Engineer",
+      publicIdentifier: "alice",
+      profileUrl: "https://linkedin.com/in/alice",
+      profileUrn: "urn:li:fsd_profile:123",
+      imageUrl: null,
+      memberDistance: 1,
+      pendingConnection: "none",
+      cached: false,
+      creditsUsed: 1,
+      retryAfter: 0,
+    } as never);
+
+    const result = await visitProfileIfNeeded(client, "u/alice", "slug", null);
+
+    expect(result.memberDistance).toBe(1);
+    expect(result.visited).toBe(true);
+    expect(result.pendingConnection).toBe("none");
+    expect(result.firstName).toBe("Alice");
+    expect(result.profileUrn).toBe("urn:li:fsd_profile:123");
+    expect(mock).toHaveBeenCalledWith({ profile: "u/alice", campaignSlug: "slug" });
+  });
+
+  it("calls visitProfile when knownDistance is undefined", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+    mock.mockResolvedValueOnce({
+      success: true,
+      firstName: "Bob",
+      lastName: "Jones",
+      headline: null,
+      publicIdentifier: "bob",
+      profileUrl: "https://linkedin.com/in/bob",
+      imageUrl: null,
+      memberDistance: 2,
+      pendingConnection: "pending",
+      cached: false,
+      creditsUsed: 1,
+      retryAfter: 0,
+    } as never);
+
+    const result = await visitProfileIfNeeded(client, "u/bob", "slug", undefined);
+
+    expect(result.memberDistance).toBe(2);
+    expect(result.visited).toBe(true);
+    expect(result.pendingConnection).toBe("pending");
+  });
+
+  it("handles null memberDistance from visit response", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+    mock.mockResolvedValueOnce({
+      success: true,
+      firstName: "X",
+      lastName: "Y",
+      headline: null,
+      publicIdentifier: "x",
+      profileUrl: "u/x",
+      imageUrl: null,
+      memberDistance: null,
+      pendingConnection: "none",
+      cached: false,
+      creditsUsed: 1,
+      retryAfter: 0,
+    } as never);
+
+    const result = await visitProfileIfNeeded(client, "u/x", "slug", null);
+
+    expect(result.memberDistance).toBeNull();
+    expect(result.visited).toBe(true);
+  });
+
+  it("propagates FatalError from visitProfile", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinScrapers.visitProfile);
+    mock.mockRejectedValueOnce(Object.assign(new Error("unauthorized"), { statusCode: 401 }));
+
+    await expect(
+      visitProfileIfNeeded(client, "u/x", "slug", null),
+    ).rejects.toThrow(FatalError);
+  });
+});
+
+// ── findConversationForDmGuard ──────────────────────────────────────
+
+describe("findConversationForDmGuard", () => {
+  it("returns skip=false when no conversation found", async () => {
+    const client = createMockClient();
+    const mock = vi.mocked(client.linkedinChat.findConversation);
+    mock.mockResolvedValueOnce({
+      success: true,
+      found: false,
+      conversation: null,
+      messages: null,
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(false);
+    expect(result.messages).toHaveLength(0);
+  });
+
+  it("returns skip=true when resourceLink found in messages", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+    const syncMock = vi.mocked(client.campaigns.syncActions);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: [
+        {
+          messageUrn: "m1",
+          text: "Here is the resource: https://link",
+          deliveredAt: 1000,
+          senderProfileUrn: "urn:me",
+          sender: { name: "Me", profileUrl: "u/me" },
+          attachments: [],
+        },
+      ],
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+    syncMock.mockResolvedValueOnce({ success: true, synced: [], creditsUsed: 0, retryAfter: 0 } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(true);
+    expect(result.messages).toHaveLength(1);
+    expect(syncMock).toHaveBeenCalledOnce();
+  });
+
+  it("returns skip=false when conversation exists but link not in messages", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: [
+        {
+          messageUrn: "m1",
+          text: "Hello! Nice to connect.",
+          deliveredAt: 1000,
+          senderProfileUrn: "urn:them",
+          sender: { name: "Alice", profileUrl: "u/alice" },
+          attachments: [],
+        },
+      ],
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(false);
+    expect(result.messages).toHaveLength(1);
+  });
+
+  it("returns messages for tone adaptation when no link found", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: [
+        {
+          messageUrn: "m1",
+          text: "Hey! How are you?",
+          deliveredAt: 1000,
+          senderProfileUrn: "urn:them",
+          sender: { name: "Alice", profileUrl: "u/alice" },
+          attachments: [],
+        },
+        {
+          messageUrn: "m2",
+          text: "Great, thanks!",
+          deliveredAt: 2000,
+          senderProfileUrn: "urn:me",
+          sender: { name: "Me", profileUrl: "u/me" },
+          attachments: [],
+        },
+      ],
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(false);
+    expect(result.messages).toHaveLength(2);
+    expect(result.messages[0].text).toBe("Hey! How are you?");
+  });
+
+  it("returns skip=true (fail-safe) when findConversation throws", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+    findMock.mockRejectedValueOnce(Object.assign(new Error("network"), { statusCode: 500 }));
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(true);
+    expect(result.messages).toHaveLength(0);
+  });
+
+  it("still returns skip=true when syncActions fails after finding link", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+    const syncMock = vi.mocked(client.campaigns.syncActions);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: [
+        {
+          messageUrn: "m1",
+          text: "https://link already sent",
+          deliveredAt: 1000,
+          senderProfileUrn: "urn:me",
+          sender: { name: "Me", profileUrl: "u/me" },
+          attachments: [],
+        },
+      ],
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+    syncMock.mockRejectedValueOnce(new Error("sync failed"));
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(true);
+  });
+
+  it("handles conversation found but messages array is null", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: null,
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(false);
+    expect(result.messages).toHaveLength(0);
+  });
+
+  it("handles conversation found but messages array is empty", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: [],
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link", "slug");
+
+    expect(result.skip).toBe(false);
+    expect(result.messages).toHaveLength(0);
+  });
+
+  it("matches resourceLink as substring in message text", async () => {
+    const client = createMockClient();
+    const findMock = vi.mocked(client.linkedinChat.findConversation);
+    const syncMock = vi.mocked(client.campaigns.syncActions);
+
+    findMock.mockResolvedValueOnce({
+      success: true,
+      found: true,
+      conversation: null,
+      messages: [
+        {
+          messageUrn: "m1",
+          text: "Voici ta ressource https://link/resource?id=123 bonne lecture !",
+          deliveredAt: 1000,
+          senderProfileUrn: "urn:me",
+          sender: { name: "Me", profileUrl: "u/me" },
+          attachments: [],
+        },
+      ],
+      creditsUsed: 0,
+      retryAfter: 0,
+    } as never);
+    syncMock.mockResolvedValueOnce({ success: true, synced: [], creditsUsed: 0, retryAfter: 0 } as never);
+
+    const result = await findConversationForDmGuard(client, "u/alice", "https://link/resource", "slug");
+
+    expect(result.skip).toBe(true);
+  });
+});

package/openclaw.plugin.json

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

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "bereach-openclaw",
-  "version": "0.2.16",
+  "version": "0.3.0",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
+  "exports": {
+    ".": "./src/index.ts",
+    "./lead-magnet": "./src/lead-magnet/helpers.ts"
+  },
   "scripts": {
-    "test:register": "tsx scripts/test-register.ts"
+    "test:register": "tsx scripts/test-register.ts",
+    "test": "vitest run"
   },
   "openclaw": {
     "extensions": [
@@ -12,11 +17,12 @@
     ]
   },
   "dependencies": {
-    "bereach": "^0.1.4"
+    "bereach": "^0.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "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: 1772673508
+lastUpdatedAt: 1772701953
 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       | 1772673508    |
+| 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    |
 | 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             |
 
@@ -81,9 +81,13 @@ The SDK auto-reads `BEREACH_API_KEY` from the environment. NEVER hardcode tokens
 
 - Lead magnet scripts use the SDK. Tools are for interactive agent use only.
 - 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.
+- Scripts MUST be TypeScript (`.ts`). Load the [SDK Reference](sdk-reference.md) sub-skill for method signatures.
+
+**Mandatory validation loop** — after generating or editing any script:
+
+1. **Step 1 (blocking)** — Run `npx tsc --noEmit` in the script directory. It MUST exit 0. If type errors: fix them using the SDK Reference, then repeat. Do NOT run tsx until tsc passes.
+2. **Step 2** — Run `npx tsx <script-name>.ts`. Fix runtime errors (e.g. "visitProfile is not a function"). If config missing, run with minimal env to reach first SDK call.
+3. **Both must succeed** — tsx passing alone is NOT sufficient. Do not consider the script ready until BOTH tsc and tsx succeed.
 
 ### Always
 
@@ -139,7 +143,7 @@ More workflows coming soon. You can build your own using the SDK methods and too
 
 Crons are OpenClaw scheduled tasks. Create entries in `~/.openclaw/cron/jobs.json` (via `openclaw cron add`).
 
-**Lead Magnet** — 3 global crons. Config at `~/.openclaw/lead-magnet.json`. Each cron runs one script that loops over all enabled campaigns:
+**Lead Magnet** — 3 global crons. Campaign config at `~/.bereach/lead-magnet.json`. Each cron runs one script that loops over all enabled campaigns:
 
 ```json
 { "id": "lm-comments", "every": "1h", "skill": "bereach", "sessionTarget": "spawn", "prompt": "Run lm-comments.ts and report recap" }

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: 1772673508
+lastUpdatedAt: 1772701953
 ---
 
 # BeReach Lead Magnet Skill
@@ -16,6 +16,60 @@ Requires [BeReach SKILL.md](SKILL.md) (constraints, SDK setup, anti-hallucinatio
 
 All lead magnet scripts MUST be TypeScript using the `bereach` SDK (see main skill for SDK setup and rules).
 
+**Always use full SDK paths** — e.g. `client.linkedinChat.findConversation`, `client.linkedinScrapers.visitProfile`. Never infer the resource from method name alone (e.g. "inbox" ≠ linkedinInbox; "visit" ≠ linkedinActions.visitProfile).
+
+**Validation loop (mandatory)** — after writing each script:
+
+1. **Step 1 (blocking)** — `npx tsc --noEmit` MUST exit 0. Fix any type errors using SDK Reference. Do NOT run tsx until tsc passes.
+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
+
+`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.
+
+```typescript
+import {
+  collectAllComments,
+  listAllInvitations,
+  visitProfileIfNeeded,
+  findConversationForDmGuard,
+} from "bereach-openclaw/lead-magnet";
+```
+
+Your spec should list which helpers you plan to use.
+
+### collectAllComments(client, postUrl, campaignSlug, opts?)
+
+Paginates `collectComments` automatically (`while hasMore`, `start += 100`). Prevents the most common bug: fetching only the first 100 comments.
+
+- `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 }`.
+
+### listAllInvitations(client)
+
+Paginates `listInvitations` automatically (`while total > start + count`, `count: 100`). Prevents fetching only the first 10 invitations.
+
+- Returns `{ invitations, total }`.
+
+### visitProfileIfNeeded(client, profile, campaignSlug, knownDistance)
+
+If `knownDistance` is already set (including 0): returns it immediately (0 credits). If `null`/`undefined`: calls `client.linkedinScrapers.visitProfile` (correct path — not `linkedinActions`).
+
+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).
+
+Returns `{ memberDistance, pendingConnection, visited, firstName, headline, ... }`.
+
+### 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).
+
+- 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.
+
 ## Tone
 
 All script output and chatbot messages are **for the end user**. Write like you're talking to a non-technical person. Never mention internal concepts like "Track A", "Layer 2", "DM guard", "server-side dedup", "retryAfter", "URN", "O(1) lookup", etc. The campaign slug is fine to show — it helps the user know which campaign is running. Just say what happened in plain language: "Sent the resource to 12 people", "Skipped 3 (already received it)", "Outside active hours, will resume at 7:00".
@@ -125,11 +179,10 @@ Before running a script for a campaign, acquire a lock to prevent concurrent run
 
 For each campaign (from config): scrape commenters and engage them.
 
-1. **Check first** (mandatory): `collectComments` with `count: 0` → store `total`. On subsequent rounds, compare with previous `total`. If unchanged, skip this round. This saves credits and rate limit slots.
-2. **Fetch**: `collectComments` with `campaignSlug` → response: `profiles[]` (NOT "comments"). Paginate: while `hasMore`, increment `start` by `count`.
-3. Each profile has: `profileUrl`, `commentUrn`, `name`, `profileUrn`, `actionsCompleted: { message, reply, like, visit, connect }`, `knownDistance`, `hasReplyFromPostAuthor`
-4. For each profile (skip own URN, skip `actionsCompleted.message === true`):
-   a. If `knownDistance` is set, use it (skip visit, saves 1 credit). Otherwise: `visitProfile` with `campaignSlug` → `memberDistance`, `pendingConnection`
+1. **Fetch all comments**: `collectAllComments(client, postUrl, campaignSlug, { previousTotal })` — handles pagination and count-0 pre-check. If `skipped`, exit early.
+2. Each profile has: `profileUrl`, `commentUrn`, `name`, `profileUrn`, `actionsCompleted: { message, reply, like, visit, connect }`, `knownDistance`, `hasReplyFromPostAuthor`
+3. For each profile (skip own URN, skip `actionsCompleted.message === true`):
+   a. `visitProfileIfNeeded(client, profile, campaignSlug, knownDistance)` → `memberDistance`, `pendingConnection`
    b. Distance 1:
    - **DM dedup** (see "DM dedup" section): check both layers. If either says "already sent", skip. Otherwise: `sendMessage` with `campaignSlug`.
    - Skip reply if `actionsCompleted.reply === true` or `hasReplyFromPostAuthor === true`. Otherwise: `replyToComment` with `commentUrn` and `campaignSlug`
@@ -143,20 +196,20 @@ For each campaign (from config): scrape commenters and engage them.
 
 Accept pending invitations and deliver the resource to campaign-related invitees.
 
-- `listInvitations` → response: `invitations[]`. Each has: `invitationId`, `sharedSecret`, `fromMember: { name, profileUrl }`. Paginate: while `total > start + count`.
-- **Campaign attribution**: `listInvitations` 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.
+- `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.
 - For each invitation:
   1. `acceptInvitation` with `invitationId` and `sharedSecret`
-  2. If campaign matched: `visitProfile` with matched `campaignSlug`, then **DM dedup** → DM if not already sent.
+  2. If campaign matched: `visitProfileIfNeeded(client, profile, campaignSlug, null)`, then **DM dedup** → DM if not already sent.
   3. If no campaign match (organic invitation): accept only, no DM.
 
 ### Script 3 — New connections
 
 For each campaign (from config): check if distance 2+ commenters have now connected.
 
-- Re-fetch commenters: `collectComments` with `campaignSlug` — paginate all
+- Re-fetch commenters: `collectAllComments(client, postUrl, campaignSlug)` — pagination handled by helper
 - Filter: `actionsCompleted.message === false` and `knownDistance > 1` (skip profiles where `knownDistance` is null — they haven't been visited yet and belong to Script 1)
-- For each: `visitProfile` with `campaignSlug` → check `memberDistance` and `pendingConnection`
+- For each: `visitProfileIfNeeded(client, profile, campaignSlug, null)` → check `memberDistance` and `pendingConnection`
   - `memberDistance === 1`: **DM dedup** (see "DM dedup" section) → DM the resource if not already sent.
   - `pendingConnection === "pending"`: not connected yet, skip
 
@@ -172,9 +225,7 @@ Check in order. If either says "already sent", skip the DM.
 
 **Layer 1 — `actionsCompleted.message`** (free, within campaign). Already checked in the script loop — `true` → skip.
 
-**Layer 2 — `/find` inbox lookup** (0 credits, cross-campaign). Only when `resourceLink` is set. Call `findConversation` with `includeMessages: true` → `{ found, messages }`. `messages` is at the **top level**, not nested. If any message text contains `resourceLink`: skip DM, call `syncActions` to mark done. If found but no link in messages: pass `messages` as context for DM tone adaptation. The function must return both skip decision and messages.
-
-**Fail-safe**: if `findConversation` errors or all retries fail, **skip this profile** — do NOT send the DM. A failed lookup treated as "not found" causes duplicates. The profile will be retried next run.
+**Layer 2 — DM guard** (0 credits, cross-campaign). Only when `resourceLink` is set. Use `findConversationForDmGuard(client, profile, resourceLink, campaignSlug)` → `{ skip, messages }`. The helper handles: correct SDK path (`linkedinChat`, not `linkedinInbox`), top-level `messages`, `syncActions` on match, and fail-safe on error (skip = true). Pass returned `messages` as context for DM tone adaptation when `skip` is false.
 
 ## Language
 
@@ -206,7 +257,7 @@ Follow pacing rules from the main skill (Constraints #2). No exceptions — slee
 
 ## Cron
 
-Three global crons. Config at `~/.openclaw/lead-magnet.json`. Each cron runs one script that loops over all enabled campaigns.
+Three global crons. Campaign config at `~/.bereach/lead-magnet.json`. Each cron runs one script that loops over all enabled campaigns.
 
 All crons MUST use `"sessionTarget": "spawn"` to avoid blocking the main session. Each spawned sub-agent runs the script independently and pushes the recap back to the user when done.
 

package/src/lead-magnet/helpers.ts

@@ -0,0 +1,171 @@
+import type { Bereach } from "bereach";
+import type {
+  CollectLinkedInCommentsProfile,
+  Invitation,
+  FindLinkedInConversationMessage,
+} from "bereach/models/operations";
+import { Action } from "bereach/models/operations";
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+function randomDelay(minS: number, maxS: number) {
+  return sleep((minS + Math.random() * (maxS - minS)) * 1000);
+}
+
+/** 2-6s pause — read actions. */
+export const readPause = () => randomDelay(2, 6);
+/** 8-12s pause — write actions. */
+export const writePause = () => randomDelay(8, 12);
+
+export class SkippableError extends Error {
+  readonly skip = true as const;
+  constructor(message: string, options?: { cause?: unknown }) { super(message, options); this.name = "SkippableError"; }
+}
+
+export class FatalError extends Error {
+  readonly fatal = true as const;
+  constructor(message: string) { super(message); this.name = "FatalError"; }
+}
+
+/** Retry on 429 with exponential backoff, throw FatalError (401/404/405) or SkippableError (rest). */
+export async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  let attempts = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err: unknown) {
+      const e = err as { status?: number; statusCode?: number; message?: string };
+      const status = e?.statusCode ?? e?.status;
+
+      if (status === 429 && attempts < maxRetries) {
+        await sleep(2 ** attempts * 1000);
+        attempts++;
+        continue;
+      }
+      if (status === 401 || status === 404 || status === 405) {
+        throw new FatalError(e?.message ?? `Fatal error (HTTP ${status})`);
+      }
+      throw new SkippableError(e?.message ?? `Skippable error (HTTP ${status})`, { cause: err });
+    }
+  }
+}
+
+/** Paginate all comments. Pass `previousTotal` for a free count-0 early exit. */
+export async function collectAllComments(
+  client: Bereach,
+  postUrl: string,
+  campaignSlug: string,
+  opts?: { previousTotal?: number },
+) {
+  if (opts?.previousTotal != null) {
+    const check = await withRetry(() =>
+      client.linkedinScrapers.collectComments({ postUrl, count: 0 }),
+    );
+    if (check.total === opts.previousTotal) {
+      return { profiles: [] as CollectLinkedInCommentsProfile[], total: opts.previousTotal, skipped: true };
+    }
+  }
+
+  const allProfiles: CollectLinkedInCommentsProfile[] = [];
+  let start = 0;
+  const count = 100;
+  let total = 0;
+
+  while (true) {
+    const page = await withRetry(() =>
+      client.linkedinScrapers.collectComments({ postUrl, start, count, campaignSlug }),
+    );
+    if (page.profiles.length > 0) allProfiles.push(...page.profiles);
+    total = page.total;
+    if (!page.hasMore) break;
+    start += count;
+    await readPause();
+  }
+
+  return { profiles: allProfiles, total, skipped: false };
+}
+
+/** Paginate all pending invitations. */
+export async function listAllInvitations(client: Bereach) {
+  const allInvitations: Invitation[] = [];
+  let start = 0;
+  const count = 100;
+
+  while (true) {
+    const page = await withRetry(() =>
+      client.linkedinActions.listInvitations({ start, count }),
+    );
+    if (page.invitations.length > 0) allInvitations.push(...page.invitations);
+    if (page.total <= start + count) break;
+    start += count;
+    await readPause();
+  }
+
+  return { invitations: allInvitations, total: allInvitations.length };
+}
+
+/**
+ * Use knownDistance when set (0 credits), otherwise call linkedinScrapers.visitProfile.
+ * NOT linkedinActions.visitProfile — wrong namespace.
+ */
+export async function visitProfileIfNeeded(
+  client: Bereach,
+  profile: string,
+  campaignSlug: string,
+  knownDistance: number | null | undefined,
+) {
+  if (knownDistance != null) {
+    return { visited: false as const, memberDistance: knownDistance, pendingConnection: null };
+  }
+
+  const v = await withRetry(() =>
+    client.linkedinScrapers.visitProfile({ profile, campaignSlug }),
+  );
+
+  return { ...v, visited: true as const, memberDistance: v.memberDistance ?? null };
+}
+
+export interface DmGuardResult {
+  skip: boolean;
+  messages: FindLinkedInConversationMessage[];
+}
+
+/**
+ * Check if resourceLink was already sent via DM.
+ * Uses linkedinChat.findConversation (NOT linkedinInbox). Messages at top level.
+ * Fail-safe: on error, skip=true (never DM on lookup failure).
+ */
+export async function findConversationForDmGuard(
+  client: Bereach,
+  profile: string,
+  resourceLink: string,
+  campaignSlug: string,
+): Promise<DmGuardResult> {
+  let data: Awaited<ReturnType<typeof client.linkedinChat.findConversation>>;
+  try {
+    data = await withRetry(() =>
+      client.linkedinChat.findConversation({ profile, includeMessages: true }),
+    );
+  } catch {
+    return { skip: true, messages: [] };
+  }
+
+  if (!data.found) return { skip: false, messages: [] };
+
+  const messages = data.messages ?? [];
+  const alreadySent = messages.some((m) => m.text.includes(resourceLink));
+
+  if (alreadySent) {
+    try {
+      await client.campaigns.syncActions({
+        campaignSlug,
+        body: { profiles: [{ profile, actions: [Action.Message] }] },
+      });
+    } catch {
+      // non-critical
+    }
+    return { skip: true, messages };
+  }
+
+  return { skip: false, messages };
+}

package/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,