@lhremote/core 0.0.0 → 0.2.0

package/dist/db/errors.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Base class for all database-related errors.
+ */
+export class DatabaseError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DatabaseError";
+    }
+}
+/**
+ * Thrown when a LinkedHelper database file cannot be found at the
+ * expected location for a given account.
+ */
+export class DatabaseNotFoundError extends DatabaseError {
+    constructor(accountId) {
+        super(`No database found for account ${String(accountId)}`);
+        this.name = "DatabaseNotFoundError";
+    }
+}
+/**
+ * Thrown when a chat lookup yields no results.
+ */
+export class ChatNotFoundError extends DatabaseError {
+    constructor(chatId) {
+        super(`Chat not found for id ${String(chatId)}`);
+        this.name = "ChatNotFoundError";
+    }
+}
+/**
+ * Thrown when a profile lookup yields no results. The person may not
+ * have been extracted by LinkedHelper yet.
+ */
+export class ProfileNotFoundError extends DatabaseError {
+    constructor(identifier) {
+        const detail = typeof identifier === "number"
+            ? `id ${String(identifier)}`
+            : `public ID "${identifier}"`;
+        super(`Profile not found for ${detail}. It may not have been extracted yet.`);
+        this.name = "ProfileNotFoundError";
+    }
+}
+/**
+ * Thrown when a campaign lookup yields no results.
+ */
+export class CampaignNotFoundError extends DatabaseError {
+    campaignId;
+    constructor(campaignId) {
+        super(`Campaign not found for id ${String(campaignId)}`);
+        this.name = "CampaignNotFoundError";
+        this.campaignId = campaignId;
+    }
+}
+/**
+ * Thrown when a campaign action lookup yields no results.
+ */
+export class ActionNotFoundError extends DatabaseError {
+    constructor(actionId, campaignId) {
+        super(`Action ${String(actionId)} not found in campaign ${String(campaignId)}`);
+        this.name = "ActionNotFoundError";
+    }
+}
+/**
+ * Thrown when an action has no successor in the campaign chain.
+ */
+export class NoNextActionError extends DatabaseError {
+    constructor(actionId, campaignId) {
+        super(`Action ${String(actionId)} is the last action in campaign ${String(campaignId)}`);
+        this.name = "NoNextActionError";
+    }
+}
+/**
+ * Thrown when an exclude list is not found for a campaign or action.
+ */
+export class ExcludeListNotFoundError extends DatabaseError {
+    constructor(level, id) {
+        super(`Exclude list not found for ${level} ${String(id)}`);
+        this.name = "ExcludeListNotFoundError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/db/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/db/errors.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACtD,YAAY,SAAiB;QAC3B,KAAK,CAAC,iCAAiC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD,YAAY,MAAc;QACxB,KAAK,CAAC,yBAAyB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IACrD,YAAY,UAA2B;QACrC,MAAM,MAAM,GACV,OAAO,UAAU,KAAK,QAAQ;YAC5B,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE;YAC5B,CAAC,CAAC,cAAc,UAAU,GAAG,CAAC;QAClC,KAAK,CACH,yBAAyB,MAAM,uCAAuC,CACvE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,UAAU,CAAS;IAE5B,YAAY,UAAkB;QAC5B,KAAK,CAAC,6BAA6B,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACpD,YAAY,QAAgB,EAAE,UAAkB;QAC9C,KAAK,CACH,UAAU,MAAM,CAAC,QAAQ,CAAC,0BAA0B,MAAM,CAAC,UAAU,CAAC,EAAE,CACzE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD,YAAY,QAAgB,EAAE,UAAkB;QAC9C,KAAK,CACH,UAAU,MAAM,CAAC,QAAQ,CAAC,mCAAmC,MAAM,CAAC,UAAU,CAAC,EAAE,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IACzD,YAAY,KAA4B,EAAE,EAAU;QAClD,KAAK,CAAC,8BAA8B,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF"}

package/dist/db/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/db/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/db/errors.test.ts"],"names":[],"mappings":""}

package/dist/db/errors.test.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { describe, expect, it } from "vitest";
+import { DatabaseError, DatabaseNotFoundError, ProfileNotFoundError, } from "./errors.js";
+describe("DatabaseError", () => {
+    it("is an instance of Error", () => {
+        const err = new DatabaseError("test");
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe("DatabaseError");
+    });
+});
+describe("DatabaseNotFoundError", () => {
+    it("includes the account ID in the message", () => {
+        const err = new DatabaseNotFoundError(42);
+        expect(err.message).toBe("No database found for account 42");
+        expect(err).toBeInstanceOf(DatabaseError);
+        expect(err.name).toBe("DatabaseNotFoundError");
+    });
+});
+describe("ProfileNotFoundError", () => {
+    it("formats numeric IDs", () => {
+        const err = new ProfileNotFoundError(7);
+        expect(err.message).toContain("id 7");
+        expect(err.name).toBe("ProfileNotFoundError");
+    });
+    it("formats string public IDs", () => {
+        const err = new ProfileNotFoundError("alice-smith");
+        expect(err.message).toContain('public ID "alice-smith"');
+    });
+    it("extends DatabaseError", () => {
+        expect(new ProfileNotFoundError(1)).toBeInstanceOf(DatabaseError);
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/db/errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../../src/db/errors.test.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,GAAG,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,GAAG,GAAG,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;QAC7D,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC7B,MAAM,GAAG,GAAG,IAAI,oBAAoB,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,GAAG,GAAG,IAAI,oBAAoB,CAAC,aAAa,CAAC,CAAC;QACpD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,yBAAyB,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC/B,MAAM,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/db/escape-like.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Escapes SQL LIKE wildcard characters (`%` and `_`) in user input
+ * so they are treated as literals.
+ *
+ * Must be used with `ESCAPE '\'` in the LIKE clause.
+ */
+export declare function escapeLike(input: string): string;
+//# sourceMappingURL=escape-like.d.ts.map

package/dist/db/escape-like.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-like.d.ts","sourceRoot":"","sources":["../../src/db/escape-like.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/db/escape-like.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Escapes SQL LIKE wildcard characters (`%` and `_`) in user input
+ * so they are treated as literals.
+ *
+ * Must be used with `ESCAPE '\'` in the LIKE clause.
+ */
+export function escapeLike(input) {
+    return input.replace(/[%_\\]/g, (ch) => `\\${ch}`);
+}
+//# sourceMappingURL=escape-like.js.map

package/dist/db/escape-like.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-like.js","sourceRoot":"","sources":["../../src/db/escape-like.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACrD,CAAC"}

package/dist/db/escape-like.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=escape-like.test.d.ts.map

package/dist/db/escape-like.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-like.test.d.ts","sourceRoot":"","sources":["../../src/db/escape-like.test.ts"],"names":[],"mappings":""}

package/dist/db/escape-like.test.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { describe, expect, it } from "vitest";
+import { escapeLike } from "./escape-like.js";
+describe("escapeLike", () => {
+    it("returns plain text unchanged", () => {
+        expect(escapeLike("hello world")).toBe("hello world");
+    });
+    it("escapes percent wildcard", () => {
+        expect(escapeLike("100%")).toBe("100\\%");
+    });
+    it("escapes underscore wildcard", () => {
+        expect(escapeLike("field_name")).toBe("field\\_name");
+    });
+    it("escapes backslash (the escape character itself)", () => {
+        expect(escapeLike("path\\to")).toBe("path\\\\to");
+    });
+    it("escapes multiple special characters", () => {
+        expect(escapeLike("100% of_items\\done")).toBe("100\\% of\\_items\\\\done");
+    });
+    it("handles empty string", () => {
+        expect(escapeLike("")).toBe("");
+    });
+});
+//# sourceMappingURL=escape-like.test.js.map

package/dist/db/escape-like.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-like.test.js","sourceRoot":"","sources":["../../src/db/escape-like.test.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAC5C,2BAA2B,CAC5B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/db/index.d.ts

@@ -0,0 +1,5 @@
+export { DatabaseClient, type DatabaseClientOptions } from "./client.js";
+export { discoverAllDatabases, discoverDatabase } from "./discovery.js";
+export { ActionNotFoundError, CampaignNotFoundError, ChatNotFoundError, DatabaseError, DatabaseNotFoundError, ExcludeListNotFoundError, NoNextActionError, ProfileNotFoundError, } from "./errors.js";
+export { CampaignExcludeListRepository, CampaignRepository, CampaignStatisticsRepository, MessageRepository, ProfileRepository, } from "./repositories/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC"}

package/dist/db/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { DatabaseClient } from "./client.js";
+export { discoverAllDatabases, discoverDatabase } from "./discovery.js";
+export { ActionNotFoundError, CampaignNotFoundError, ChatNotFoundError, DatabaseError, DatabaseNotFoundError, ExcludeListNotFoundError, NoNextActionError, ProfileNotFoundError, } from "./errors.js";
+export { CampaignExcludeListRepository, CampaignRepository, CampaignStatisticsRepository, MessageRepository, ProfileRepository, } from "./repositories/index.js";
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,cAAc,EAA8B,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,EAClB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC"}

package/dist/db/repositories/campaign-exclude-list.d.ts

@@ -0,0 +1,89 @@
+import type { ExcludeListEntry } from "../../types/index.js";
+import type { DatabaseClient } from "../client.js";
+/**
+ * Repository for campaign exclude-list operations.
+ *
+ * Provides read operations (getExcludeList) and write operations
+ * (addToExcludeList, removeFromExcludeList) for campaign and
+ * action-level exclude lists.
+ *
+ * Write operations require the DatabaseClient to be opened with
+ * `{ readOnly: false }`.
+ */
+export declare class CampaignExcludeListRepository {
+    private readonly client;
+    private readonly stmtGetCampaign;
+    private readonly stmtGetCampaignActions;
+    private writeStatements;
+    constructor(client: DatabaseClient);
+    /**
+     * Get the exclude list for a campaign or action.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param actionId - If provided, get the action-level exclude list.
+     *   Otherwise, get the campaign-level exclude list.
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    getExcludeList(campaignId: number, actionId?: number): ExcludeListEntry[];
+    /**
+     * Add people to a campaign or action exclude list.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param personIds - Person IDs to add.
+     * @param actionId - If provided, add to the action-level exclude list.
+     * @returns Number of people actually added (excludes already-present).
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    addToExcludeList(campaignId: number, personIds: number[], actionId?: number): number;
+    /**
+     * Remove people from a campaign or action exclude list.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param personIds - Person IDs to remove.
+     * @param actionId - If provided, remove from the action-level exclude list.
+     * @returns Number of people actually removed.
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    removeFromExcludeList(campaignId: number, personIds: number[], actionId?: number): number;
+    /**
+     * Prepare write statements lazily (only when needed).
+     * This avoids issues when the client is opened in read-only mode.
+     */
+    private getWriteStatements;
+    /**
+     * Resolve the collection_id for an exclude list.
+     *
+     * Follows the chain: exclude_list_id -> collection_people_versions -> collection_id.
+     *
+     * @param level - "campaign" or "action"
+     * @param id - Campaign ID (if level is "campaign") or action ID (if level is "action")
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    private resolveExcludeListCollectionId;
+    /**
+     * Validate campaign/action and resolve the exclude-list collection ID.
+     *
+     * Shared preamble for {@link getExcludeList}, {@link addToExcludeList},
+     * and {@link removeFromExcludeList}.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param actionId - If provided, scope to the action-level exclude list.
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    private resolveExcludeListContext;
+    /**
+     * Verify that a campaign exists.
+     *
+     * @throws {CampaignNotFoundError} if no campaign exists with the given ID.
+     */
+    private verifyCampaignExists;
+}
+//# sourceMappingURL=campaign-exclude-list.d.ts.map

package/dist/db/repositories/campaign-exclude-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-exclude-list.d.ts","sourceRoot":"","sources":["../../../src/db/repositories/campaign-exclude-list.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAWnD;;;;;;;;;GASG;AACH,qBAAa,6BAA6B;IAU5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IATnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IAGxC,OAAO,CAAC,eAAe,CAGP;gBAEa,MAAM,EAAE,cAAc;IAiBnD;;;;;;;;;OASG;IACH,cAAc,CACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,gBAAgB,EAAE;IAiBrB;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM;IA6BT;;;;;;;;;;OAUG;IACH,qBAAqB,CACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM;IA6BT;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,8BAA8B;IA4CtC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,yBAAyB;IAsBjC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;CAI7B"}

package/dist/db/repositories/campaign-exclude-list.js

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { ActionNotFoundError, CampaignNotFoundError, ExcludeListNotFoundError, } from "../errors.js";
+/**
+ * Repository for campaign exclude-list operations.
+ *
+ * Provides read operations (getExcludeList) and write operations
+ * (addToExcludeList, removeFromExcludeList) for campaign and
+ * action-level exclude lists.
+ *
+ * Write operations require the DatabaseClient to be opened with
+ * `{ readOnly: false }`.
+ */
+export class CampaignExcludeListRepository {
+    client;
+    stmtGetCampaign;
+    stmtGetCampaignActions;
+    // Write statements (prepared lazily to avoid issues with read-only mode)
+    writeStatements = null;
+    constructor(client) {
+        this.client = client;
+        const { db } = client;
+        this.stmtGetCampaign = db.prepare(`SELECT id, name, description, is_paused, is_archived, is_valid,
+              li_account_id, created_at
+       FROM campaigns WHERE id = ?`);
+        this.stmtGetCampaignActions = db.prepare(`SELECT a.id, a.campaign_id
+       FROM actions a
+       WHERE a.campaign_id = ?
+       ORDER BY a.id`);
+    }
+    /**
+     * Get the exclude list for a campaign or action.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param actionId - If provided, get the action-level exclude list.
+     *   Otherwise, get the campaign-level exclude list.
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    getExcludeList(campaignId, actionId) {
+        const { collectionId } = this.resolveExcludeListContext(campaignId, actionId);
+        const rows = this.client.db
+            .prepare(`SELECT person_id FROM collection_people
+         WHERE collection_id = ?
+         ORDER BY person_id`)
+            .all(collectionId);
+        return rows.map((r) => ({ personId: r.person_id }));
+    }
+    /**
+     * Add people to a campaign or action exclude list.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param personIds - Person IDs to add.
+     * @param actionId - If provided, add to the action-level exclude list.
+     * @returns Number of people actually added (excludes already-present).
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    addToExcludeList(campaignId, personIds, actionId) {
+        if (personIds.length === 0)
+            return 0;
+        const { collectionId } = this.resolveExcludeListContext(campaignId, actionId);
+        const stmts = this.getWriteStatements();
+        let added = 0;
+        this.client.db.exec("BEGIN");
+        try {
+            for (const personId of personIds) {
+                const result = stmts.insertCollectionPerson.run(collectionId, personId);
+                if (result.changes > 0)
+                    added++;
+            }
+            this.client.db.exec("COMMIT");
+        }
+        catch (e) {
+            this.client.db.exec("ROLLBACK");
+            throw e;
+        }
+        return added;
+    }
+    /**
+     * Remove people from a campaign or action exclude list.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param personIds - Person IDs to remove.
+     * @param actionId - If provided, remove from the action-level exclude list.
+     * @returns Number of people actually removed.
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    removeFromExcludeList(campaignId, personIds, actionId) {
+        if (personIds.length === 0)
+            return 0;
+        const { collectionId } = this.resolveExcludeListContext(campaignId, actionId);
+        const stmts = this.getWriteStatements();
+        let removed = 0;
+        this.client.db.exec("BEGIN");
+        try {
+            for (const personId of personIds) {
+                const result = stmts.deleteCollectionPerson.run(collectionId, personId);
+                if (result.changes > 0)
+                    removed++;
+            }
+            this.client.db.exec("COMMIT");
+        }
+        catch (e) {
+            this.client.db.exec("ROLLBACK");
+            throw e;
+        }
+        return removed;
+    }
+    /**
+     * Prepare write statements lazily (only when needed).
+     * This avoids issues when the client is opened in read-only mode.
+     */
+    getWriteStatements() {
+        if (this.writeStatements)
+            return this.writeStatements;
+        const { db } = this.client;
+        this.writeStatements = {
+            insertCollectionPerson: db.prepare(`INSERT OR IGNORE INTO collection_people (collection_id, person_id)
+         VALUES (?, ?)`),
+            deleteCollectionPerson: db.prepare(`DELETE FROM collection_people
+         WHERE collection_id = ? AND person_id = ?`),
+        };
+        return this.writeStatements;
+    }
+    /**
+     * Resolve the collection_id for an exclude list.
+     *
+     * Follows the chain: exclude_list_id -> collection_people_versions -> collection_id.
+     *
+     * @param level - "campaign" or "action"
+     * @param id - Campaign ID (if level is "campaign") or action ID (if level is "action")
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    resolveExcludeListCollectionId(level, id) {
+        const { db } = this.client;
+        let excludeListId = null;
+        if (level === "campaign") {
+            const row = db
+                .prepare(`SELECT exclude_list_id FROM campaign_versions
+           WHERE campaign_id = ? ORDER BY id DESC LIMIT 1`)
+                .get(id);
+            excludeListId = row?.exclude_list_id ?? null;
+        }
+        else {
+            const row = db
+                .prepare(`SELECT exclude_list_id FROM action_versions
+           WHERE action_id = ? ORDER BY id DESC LIMIT 1`)
+                .get(id);
+            excludeListId = row?.exclude_list_id ?? null;
+        }
+        if (excludeListId === null) {
+            throw new ExcludeListNotFoundError(level, id);
+        }
+        // Resolve CPV -> collection_id
+        const cpv = db
+            .prepare(`SELECT collection_id FROM collection_people_versions WHERE id = ?`)
+            .get(excludeListId);
+        if (!cpv) {
+            throw new ExcludeListNotFoundError(level, id);
+        }
+        return cpv.collection_id;
+    }
+    /**
+     * Validate campaign/action and resolve the exclude-list collection ID.
+     *
+     * Shared preamble for {@link getExcludeList}, {@link addToExcludeList},
+     * and {@link removeFromExcludeList}.
+     *
+     * @param campaignId - Campaign ID (verified to exist).
+     * @param actionId - If provided, scope to the action-level exclude list.
+     * @throws {CampaignNotFoundError} if the campaign does not exist.
+     * @throws {ActionNotFoundError} if actionId is provided and not in the campaign.
+     * @throws {ExcludeListNotFoundError} if the exclude list chain is not found.
+     */
+    resolveExcludeListContext(campaignId, actionId) {
+        this.verifyCampaignExists(campaignId);
+        if (actionId !== undefined) {
+            const rows = this.stmtGetCampaignActions.all(campaignId);
+            if (!rows.some((a) => a.id === actionId)) {
+                throw new ActionNotFoundError(actionId, campaignId);
+            }
+        }
+        const level = actionId !== undefined ? "action" : "campaign";
+        const targetId = actionId ?? campaignId;
+        const collectionId = this.resolveExcludeListCollectionId(level, targetId);
+        return { collectionId, level, targetId };
+    }
+    /**
+     * Verify that a campaign exists.
+     *
+     * @throws {CampaignNotFoundError} if no campaign exists with the given ID.
+     */
+    verifyCampaignExists(campaignId) {
+        const row = this.stmtGetCampaign.get(campaignId);
+        if (!row)
+            throw new CampaignNotFoundError(campaignId);
+    }
+}
+//# sourceMappingURL=campaign-exclude-list.js.map

package/dist/db/repositories/campaign-exclude-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-exclude-list.js","sourceRoot":"","sources":["../../../src/db/repositories/campaign-exclude-list.ts"],"names":[],"mappings":"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"}

package/dist/db/repositories/campaign-exclude-list.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=campaign-exclude-list.test.d.ts.map

package/dist/db/repositories/campaign-exclude-list.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-exclude-list.test.d.ts","sourceRoot":"","sources":["../../../src/db/repositories/campaign-exclude-list.test.ts"],"names":[],"mappings":""}