@lhremote/core 0.0.0 → 0.2.0

package/dist/services/errors.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { DEFAULT_CDP_PORT } from "../constants.js";
+/**
+ * Base class for all service-layer errors.
+ */
+export class ServiceError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ServiceError";
+    }
+}
+/**
+ * Thrown when the LinkedHelper application binary cannot be found
+ * at the expected platform-specific location.
+ */
+export class AppNotFoundError extends ServiceError {
+    constructor(message) {
+        super(message ?? "LinkedHelper application binary not found. Set LINKEDHELPER_PATH to override.");
+        this.name = "AppNotFoundError";
+    }
+}
+/**
+ * Thrown when the LinkedHelper application fails to start.
+ */
+export class AppLaunchError extends ServiceError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AppLaunchError";
+    }
+}
+/**
+ * Thrown when the LinkedHelper launcher is not reachable via CDP.
+ */
+export class LinkedHelperNotRunningError extends ServiceError {
+    constructor(port) {
+        super(`LinkedHelper is not running (no CDP endpoint at port ${String(port)})`);
+        this.name = "LinkedHelperNotRunningError";
+    }
+}
+/**
+ * Thrown when starting a LinkedHelper instance fails.
+ */
+export class StartInstanceError extends ServiceError {
+    constructor(accountId, reason) {
+        super(`Failed to start instance for account ${String(accountId)}${reason ? `: ${reason}` : ""}`);
+        this.name = "StartInstanceError";
+    }
+}
+/**
+ * Thrown when an expected LinkedHelper instance is not running.
+ */
+export class InstanceNotRunningError extends ServiceError {
+    constructor(message) {
+        super(message ?? "Instance not running");
+        this.name = "InstanceNotRunningError";
+    }
+}
+/**
+ * Thrown when the CDP port appears to belong to a LinkedHelper instance
+ * (webview) rather than the launcher process.
+ */
+export class WrongPortError extends ServiceError {
+    constructor(port) {
+        super(`CDP port ${String(port)} appears to be a LinkedHelper instance, not the launcher. ` +
+            `Use the launcher port instead (default: ${String(DEFAULT_CDP_PORT)}).`);
+        this.name = "WrongPortError";
+    }
+}
+/**
+ * Thrown when a LinkedHelper action execution fails.
+ */
+export class ActionExecutionError extends ServiceError {
+    /** The action type that was attempted (e.g., 'MessageToPerson'). */
+    actionType;
+    constructor(actionType, message, options) {
+        super(message ?? `Action '${actionType}' failed`, options);
+        this.name = "ActionExecutionError";
+        this.actionType = actionType;
+    }
+}
+/**
+ * Thrown when a profile URL fails validation (e.g. not a LinkedIn
+ * profile path, or uses a forbidden scheme like `file://`).
+ */
+export class InvalidProfileUrlError extends ServiceError {
+    constructor(url) {
+        super(`Invalid profile URL: ${url} — expected https://www.linkedin.com/in/<slug>`);
+        this.name = "InvalidProfileUrlError";
+    }
+}
+/**
+ * Thrown when profile extraction times out waiting for data
+ * to appear in the database.
+ */
+export class ExtractionTimeoutError extends ServiceError {
+    constructor(profileUrl, timeoutMs) {
+        super(`Profile extraction timed out after ${String(timeoutMs)}ms for ${profileUrl}`);
+        this.name = "ExtractionTimeoutError";
+    }
+}
+/**
+ * Thrown when a campaign operation fails during execution
+ * (create, start, stop, or other CDP-based operations).
+ */
+export class CampaignExecutionError extends ServiceError {
+    campaignId;
+    constructor(message, campaignId, options) {
+        super(message, options);
+        this.name = "CampaignExecutionError";
+        this.campaignId = campaignId;
+    }
+}
+/**
+ * Thrown when a campaign operation times out waiting for
+ * a state transition (e.g., runner not reaching idle).
+ */
+export class CampaignTimeoutError extends ServiceError {
+    campaignId;
+    constructor(message, campaignId, options) {
+        super(message, options);
+        this.name = "CampaignTimeoutError";
+        this.campaignId = campaignId;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/services/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/services/errors.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,YAAY,OAAgB;QAC1B,KAAK,CACH,OAAO,IAAI,+EAA+E,CAC3F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC9C,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,YAAY;IAC3D,YAAY,IAAY;QACtB,KAAK,CACH,wDAAwD,MAAM,CAAC,IAAI,CAAC,GAAG,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,YAAY;IAClD,YAAY,SAAiB,EAAE,MAAe;QAC5C,KAAK,CACH,wCAAwC,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,YAAY,OAAgB;QAC1B,KAAK,CAAC,OAAO,IAAI,sBAAsB,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC9C,YAAY,IAAY;QACtB,KAAK,CACH,YAAY,MAAM,CAAC,IAAI,CAAC,4DAA4D;YAClF,2CAA2C,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAC1E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,oEAAoE;IAC3D,UAAU,CAAS;IAE5B,YAAY,UAAkB,EAAE,OAAgB,EAAE,OAAsB;QACtE,KAAK,CACH,OAAO,IAAI,WAAW,UAAU,UAAU,EAC1C,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IACtD,YAAY,GAAW;QACrB,KAAK,CACH,wBAAwB,GAAG,gDAAgD,CAC5E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IACtD,YAAY,UAAkB,EAAE,SAAiB;QAC/C,KAAK,CACH,sCAAsC,MAAM,CAAC,SAAS,CAAC,UAAU,UAAU,EAAE,CAC9E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IAC7C,UAAU,CAAqB;IAExC,YAAY,OAAe,EAAE,UAAmB,EAAE,OAAsB;QACtE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IAC3C,UAAU,CAAqB;IAExC,YAAY,OAAe,EAAE,UAAmB,EAAE,OAAsB;QACtE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

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

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

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

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

package/dist/services/errors.test.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { describe, expect, it } from "vitest";
+import { ActionExecutionError, AppLaunchError, AppNotFoundError, CampaignExecutionError, CampaignTimeoutError, ExtractionTimeoutError, InstanceNotRunningError, InvalidProfileUrlError, LinkedHelperNotRunningError, ServiceError, StartInstanceError, } from "./errors.js";
+describe("Service errors", () => {
+    it("should set correct name for ServiceError", () => {
+        const error = new ServiceError("test");
+        expect(error.name).toBe("ServiceError");
+        expect(error.message).toBe("test");
+        expect(error).toBeInstanceOf(Error);
+    });
+    it("should support cause via ErrorOptions", () => {
+        const cause = new TypeError("original");
+        const error = new ServiceError("wrapper", { cause });
+        expect(error.cause).toBe(cause);
+    });
+    it("should set correct name for AppNotFoundError", () => {
+        const error = new AppNotFoundError();
+        expect(error.name).toBe("AppNotFoundError");
+        expect(error.message).toContain("binary not found");
+        expect(error).toBeInstanceOf(ServiceError);
+        expect(error).toBeInstanceOf(Error);
+    });
+    it("should allow custom message for AppNotFoundError", () => {
+        const error = new AppNotFoundError("custom path");
+        expect(error.message).toBe("custom path");
+    });
+    it("should set correct name for AppLaunchError", () => {
+        const error = new AppLaunchError("spawn failed");
+        expect(error.name).toBe("AppLaunchError");
+        expect(error.message).toBe("spawn failed");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should support cause for AppLaunchError", () => {
+        const cause = new Error("ENOENT");
+        const error = new AppLaunchError("spawn failed", { cause });
+        expect(error.cause).toBe(cause);
+    });
+    it("should set correct name for LinkedHelperNotRunningError", () => {
+        const error = new LinkedHelperNotRunningError(9222);
+        expect(error.name).toBe("LinkedHelperNotRunningError");
+        expect(error.message).toContain("9222");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should set correct name for StartInstanceError", () => {
+        const error = new StartInstanceError(42);
+        expect(error.name).toBe("StartInstanceError");
+        expect(error.message).toContain("42");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should include reason in StartInstanceError", () => {
+        const error = new StartInstanceError(42, "account is already running");
+        expect(error.message).toContain("account is already running");
+    });
+    it("should set correct name for InstanceNotRunningError", () => {
+        const error = new InstanceNotRunningError();
+        expect(error.name).toBe("InstanceNotRunningError");
+        expect(error.message).toBe("Instance not running");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should allow custom message for InstanceNotRunningError", () => {
+        const error = new InstanceNotRunningError("LinkedIn target not found");
+        expect(error.message).toBe("LinkedIn target not found");
+    });
+    it("should set correct name for ActionExecutionError", () => {
+        const error = new ActionExecutionError("MessageToPerson");
+        expect(error.name).toBe("ActionExecutionError");
+        expect(error.actionType).toBe("MessageToPerson");
+        expect(error.message).toContain("MessageToPerson");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should allow custom message for ActionExecutionError", () => {
+        const error = new ActionExecutionError("InMail", "rate limited");
+        expect(error.message).toBe("rate limited");
+        expect(error.actionType).toBe("InMail");
+    });
+    it("should support cause via ErrorOptions for ActionExecutionError", () => {
+        const cause = new TypeError("CDP failed");
+        const error = new ActionExecutionError("InMail", "action failed", { cause });
+        expect(error.cause).toBe(cause);
+    });
+    it("should set correct name for InvalidProfileUrlError", () => {
+        const error = new InvalidProfileUrlError("file:///etc/passwd");
+        expect(error.name).toBe("InvalidProfileUrlError");
+        expect(error.message).toContain("file:///etc/passwd");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should set correct name for ExtractionTimeoutError", () => {
+        const error = new ExtractionTimeoutError("https://www.linkedin.com/in/test", 30000);
+        expect(error.name).toBe("ExtractionTimeoutError");
+        expect(error.message).toContain("30000ms");
+        expect(error.message).toContain("linkedin.com/in/test");
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should set correct name for CampaignExecutionError", () => {
+        const error = new CampaignExecutionError("create failed", 42);
+        expect(error.name).toBe("CampaignExecutionError");
+        expect(error.message).toBe("create failed");
+        expect(error.campaignId).toBe(42);
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should allow CampaignExecutionError without campaignId", () => {
+        const error = new CampaignExecutionError("create failed");
+        expect(error.campaignId).toBeUndefined();
+    });
+    it("should support cause for CampaignExecutionError", () => {
+        const cause = new Error("CDP timeout");
+        const error = new CampaignExecutionError("failed", 1, { cause });
+        expect(error.cause).toBe(cause);
+    });
+    it("should set correct name for CampaignTimeoutError", () => {
+        const error = new CampaignTimeoutError("runner did not reach idle", 42);
+        expect(error.name).toBe("CampaignTimeoutError");
+        expect(error.message).toContain("idle");
+        expect(error.campaignId).toBe(42);
+        expect(error).toBeInstanceOf(ServiceError);
+    });
+    it("should allow CampaignTimeoutError without campaignId", () => {
+        const error = new CampaignTimeoutError("timeout");
+        expect(error.campaignId).toBeUndefined();
+    });
+});
+//# sourceMappingURL=errors.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../../src/services/errors.test.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,2BAA2B,EAC3B,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACrD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,KAAK,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;QACpD,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,KAAK,GAAG,IAAI,gBAAgB,CAAC,aAAa,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC1C,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,KAAK,GAAG,IAAI,2BAA2B,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QACvD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,KAAK,GAAG,IAAI,kBAAkB,CAAC,EAAE,CAAC,CAAC;QACzC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,KAAK,GAAG,IAAI,kBAAkB,CAAC,EAAE,EAAE,4BAA4B,CAAC,CAAC;QACvE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,4BAA4B,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,KAAK,GAAG,IAAI,uBAAuB,EAAE,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,KAAK,GAAG,IAAI,uBAAuB,CAAC,2BAA2B,CAAC,CAAC;QACvE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,KAAK,GAAG,IAAI,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,KAAK,GAAG,IAAI,oBAAoB,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,YAAY,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,oBAAoB,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7E,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,KAAK,GAAG,IAAI,sBAAsB,CAAC,oBAAoB,CAAC,CAAC;QAC/D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QACtD,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,KAAK,GAAG,IAAI,sBAAsB,CACtC,kCAAkC,EAClC,KAAK,CACN,CAAC;QACF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;QACxD,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,KAAK,GAAG,IAAI,sBAAsB,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,KAAK,GAAG,IAAI,sBAAsB,CAAC,eAAe,CAAC,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,aAAa,EAAE,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,sBAAsB,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACjE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,KAAK,GAAG,IAAI,oBAAoB,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;QACxE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,KAAK,GAAG,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,aAAa,EAAE,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/services/index.d.ts

@@ -0,0 +1,10 @@
+export { AppService, type AppServiceOptions } from "./app.js";
+export { InstanceService, type ActionResult } from "./instance.js";
+export { startInstanceWithRecovery, waitForInstancePort, waitForInstanceShutdown, type StartInstanceOutcome, } from "./instance-lifecycle.js";
+export { LauncherService } from "./launcher.js";
+export { checkStatus, type AccountInstanceStatus, type DatabaseStatus, type LauncherStatus, type StatusReport, } from "./status.js";
+export { CampaignService } from "./campaign.js";
+export { AccountResolutionError, resolveAccount, } from "./account-resolution.js";
+export { withDatabase, withInstanceDatabase, type DatabaseContext, type InstanceDatabaseContext, } from "./instance-context.js";
+export { ActionExecutionError, AppLaunchError, AppNotFoundError, CampaignExecutionError, CampaignTimeoutError, ExtractionTimeoutError, InstanceNotRunningError, InvalidProfileUrlError, LinkedHelperNotRunningError, ServiceError, StartInstanceError, WrongPortError, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,WAAW,EACX,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,2BAA2B,EAC3B,YAAY,EACZ,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/services/index.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { AppService } from "./app.js";
+export { InstanceService } from "./instance.js";
+export { startInstanceWithRecovery, waitForInstancePort, waitForInstanceShutdown, } from "./instance-lifecycle.js";
+export { LauncherService } from "./launcher.js";
+export { checkStatus, } from "./status.js";
+export { CampaignService } from "./campaign.js";
+export { AccountResolutionError, resolveAccount, } from "./account-resolution.js";
+export { withDatabase, withInstanceDatabase, } from "./instance-context.js";
+export { ActionExecutionError, AppLaunchError, AppNotFoundError, CampaignExecutionError, CampaignTimeoutError, ExtractionTimeoutError, InstanceNotRunningError, InvalidProfileUrlError, LinkedHelperNotRunningError, ServiceError, StartInstanceError, WrongPortError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,UAAU,EAA0B,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAqB,MAAM,eAAe,CAAC;AACnE,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,GAExB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,WAAW,GAKZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,YAAY,EACZ,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,2BAA2B,EAC3B,YAAY,EACZ,kBAAkB,EAClB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/services/instance-context.d.ts

@@ -0,0 +1,37 @@
+import { DatabaseClient, type DatabaseClientOptions } from "../db/index.js";
+import { InstanceService } from "./instance.js";
+/**
+ * Resources available when only database access is needed.
+ */
+export interface DatabaseContext {
+    readonly accountId: number;
+    readonly db: DatabaseClient;
+}
+/**
+ * Resources available when both instance (CDP) and database access are needed.
+ */
+export interface InstanceDatabaseContext {
+    readonly accountId: number;
+    readonly instance: InstanceService;
+    readonly db: DatabaseClient;
+}
+/**
+ * Open the account's database inside a managed scope.
+ *
+ * The database is automatically closed when the callback finishes
+ * (whether it resolves or rejects).
+ */
+export declare function withDatabase<T>(accountId: number, callback: (ctx: DatabaseContext) => T | Promise<T>, options?: DatabaseClientOptions): Promise<T>;
+/**
+ * Discover the running instance, connect to it, open the account's
+ * database, and hand both to the callback.
+ *
+ * All resources are cleaned up automatically when the callback finishes.
+ *
+ * @throws {InstanceNotRunningError} if no instance port can be discovered.
+ */
+export declare function withInstanceDatabase<T>(cdpPort: number, accountId: number, callback: (ctx: InstanceDatabaseContext) => T | Promise<T>, options?: {
+    instanceTimeout?: number;
+    db?: DatabaseClientOptions;
+}): Promise<T>;
+//# sourceMappingURL=instance-context.d.ts.map

package/dist/services/instance-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-context.d.ts","sourceRoot":"","sources":["../../src/services/instance-context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAoB,MAAM,gBAAgB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAClD,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,GAAG,EAAE,uBAAuB,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC1D,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,EAAE,CAAC,EAAE,qBAAqB,CAAC;CAC5B,GACA,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/services/instance-context.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { DatabaseClient, discoverDatabase } from "../db/index.js";
+import { discoverInstancePort } from "../cdp/index.js";
+import { InstanceService } from "./instance.js";
+import { InstanceNotRunningError } from "./errors.js";
+/**
+ * Open the account's database inside a managed scope.
+ *
+ * The database is automatically closed when the callback finishes
+ * (whether it resolves or rejects).
+ */
+export async function withDatabase(accountId, callback, options) {
+    const dbPath = discoverDatabase(accountId);
+    const db = new DatabaseClient(dbPath, options);
+    try {
+        return await callback({ accountId, db });
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Discover the running instance, connect to it, open the account's
+ * database, and hand both to the callback.
+ *
+ * All resources are cleaned up automatically when the callback finishes.
+ *
+ * @throws {InstanceNotRunningError} if no instance port can be discovered.
+ */
+export async function withInstanceDatabase(cdpPort, accountId, callback, options) {
+    const instancePort = await discoverInstancePort(cdpPort);
+    if (instancePort === null) {
+        throw new InstanceNotRunningError("No LinkedHelper instance is running. Use start-instance first.");
+    }
+    const instance = new InstanceService(instancePort, options?.instanceTimeout != null ? { timeout: options.instanceTimeout } : undefined);
+    let db = null;
+    try {
+        await instance.connect();
+        const dbPath = discoverDatabase(accountId);
+        db = new DatabaseClient(dbPath, options?.db);
+        return await callback({ accountId, instance, db });
+    }
+    finally {
+        instance.disconnect();
+        db?.close();
+    }
+}
+//# sourceMappingURL=instance-context.js.map

package/dist/services/instance-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-context.js","sourceRoot":"","sources":["../../src/services/instance-context.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,cAAc,EAA8B,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAmBtD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAiB,EACjB,QAAkD,EAClD,OAA+B;IAE/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,EAAE,GAAG,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAe,EACf,SAAiB,EACjB,QAA0D,EAC1D,OAGC;IAED,MAAM,YAAY,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,IAAI,uBAAuB,CAC/B,gEAAgE,CACjE,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,eAAe,CAClC,YAAY,EACZ,OAAO,EAAE,eAAe,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,SAAS,CACpF,CAAC;IACF,IAAI,EAAE,GAA0B,IAAI,CAAC;IAErC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAC3C,EAAE,GAAG,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QAC7C,OAAO,MAAM,QAAQ,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IACrD,CAAC;YAAS,CAAC;QACT,QAAQ,CAAC,UAAU,EAAE,CAAC;QACtB,EAAE,EAAE,KAAK,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/services/instance-context.test.d.ts

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

package/dist/services/instance-context.test.d.ts.map

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

package/dist/services/instance-context.test.js

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("../cdp/index.js", () => ({
+    discoverInstancePort: vi.fn(),
+}));
+vi.mock("../db/index.js", () => ({
+    DatabaseClient: vi.fn(),
+    discoverDatabase: vi.fn(),
+}));
+vi.mock("./instance.js", () => ({
+    InstanceService: vi.fn(),
+}));
+import { discoverInstancePort } from "../cdp/index.js";
+import { DatabaseClient, discoverDatabase } from "../db/index.js";
+import { InstanceService } from "./instance.js";
+import { InstanceNotRunningError } from "./errors.js";
+import { withDatabase, withInstanceDatabase } from "./instance-context.js";
+const mockedDiscoverInstancePort = vi.mocked(discoverInstancePort);
+const mockedDiscoverDatabase = vi.mocked(discoverDatabase);
+const mockedDatabaseClient = vi.mocked(DatabaseClient);
+const mockedInstanceService = vi.mocked(InstanceService);
+function createMockDb(overrides = {}) {
+    const db = {
+        close: vi.fn(),
+        ...overrides,
+    };
+    mockedDatabaseClient.mockImplementation(function () {
+        return db;
+    });
+    return db;
+}
+function createMockInstance(overrides = {}) {
+    const instance = {
+        connect: vi.fn().mockResolvedValue(undefined),
+        disconnect: vi.fn(),
+        ...overrides,
+    };
+    mockedInstanceService.mockImplementation(function () {
+        return instance;
+    });
+    return instance;
+}
+describe("withDatabase", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("passes valid DatabaseContext to callback", async () => {
+        const mockDb = createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        let receivedCtx;
+        await withDatabase(42, (ctx) => {
+            receivedCtx = ctx;
+        });
+        expect(receivedCtx).toEqual({ accountId: 42, db: mockDb });
+    });
+    it("returns the callback result", async () => {
+        createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        const result = await withDatabase(42, () => "hello");
+        expect(result).toBe("hello");
+    });
+    it("returns the callback result for async callbacks", async () => {
+        createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        const result = await withDatabase(42, async () => Promise.resolve(123));
+        expect(result).toBe(123);
+    });
+    it("closes DB after callback completes successfully", async () => {
+        const mockDb = createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withDatabase(42, () => undefined);
+        expect(mockDb.close).toHaveBeenCalledOnce();
+    });
+    it("closes DB even when callback throws", async () => {
+        const mockDb = createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await expect(withDatabase(42, () => {
+            throw new Error("callback error");
+        })).rejects.toThrow("callback error");
+        expect(mockDb.close).toHaveBeenCalledOnce();
+    });
+    it("passes database options to DatabaseClient", async () => {
+        createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withDatabase(42, () => undefined, { readOnly: false });
+        expect(mockedDatabaseClient).toHaveBeenCalledWith("/path/to/db.db", {
+            readOnly: false,
+        });
+    });
+    it("discovers database for the given accountId", async () => {
+        createMockDb();
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withDatabase(99, () => undefined);
+        expect(mockedDiscoverDatabase).toHaveBeenCalledWith(99);
+    });
+});
+describe("withInstanceDatabase", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("connects to instance, opens DB, and passes context to callback", async () => {
+        const mockInstance = createMockInstance();
+        const mockDb = createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        let receivedCtx;
+        await withInstanceDatabase(9222, 42, (ctx) => {
+            receivedCtx = ctx;
+        });
+        expect(mockedDiscoverInstancePort).toHaveBeenCalledWith(9222);
+        expect(mockedInstanceService).toHaveBeenCalledWith(55123, undefined);
+        expect(mockInstance.connect).toHaveBeenCalledOnce();
+        expect(mockedDiscoverDatabase).toHaveBeenCalledWith(42);
+        expect(receivedCtx).toEqual({
+            accountId: 42,
+            instance: mockInstance,
+            db: mockDb,
+        });
+    });
+    it("returns the callback result", async () => {
+        createMockInstance();
+        createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        const result = await withInstanceDatabase(9222, 42, () => "world");
+        expect(result).toBe("world");
+    });
+    it("cleans up both resources on success", async () => {
+        const mockInstance = createMockInstance();
+        const mockDb = createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withInstanceDatabase(9222, 42, () => undefined);
+        expect(mockInstance.disconnect).toHaveBeenCalledOnce();
+        expect(mockDb.close).toHaveBeenCalledOnce();
+    });
+    it("cleans up both resources on callback failure", async () => {
+        const mockInstance = createMockInstance();
+        const mockDb = createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await expect(withInstanceDatabase(9222, 42, () => {
+            throw new Error("callback error");
+        })).rejects.toThrow("callback error");
+        expect(mockInstance.disconnect).toHaveBeenCalledOnce();
+        expect(mockDb.close).toHaveBeenCalledOnce();
+    });
+    it("disconnects instance when connect fails (db never opened)", async () => {
+        const mockInstance = createMockInstance({
+            connect: vi.fn().mockRejectedValue(new Error("connect failed")),
+            disconnect: vi.fn(),
+        });
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        await expect(withInstanceDatabase(9222, 42, () => undefined)).rejects.toThrow("connect failed");
+        expect(mockInstance.disconnect).toHaveBeenCalledOnce();
+        // DB was never created, so close should not have been called
+        expect(mockedDatabaseClient).not.toHaveBeenCalled();
+    });
+    it("throws InstanceNotRunningError when no instance port discovered", async () => {
+        mockedDiscoverInstancePort.mockResolvedValue(null);
+        await expect(withInstanceDatabase(9222, 42, () => undefined)).rejects.toThrow(InstanceNotRunningError);
+    });
+    it("passes instanceTimeout option to InstanceService", async () => {
+        createMockInstance();
+        createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withInstanceDatabase(9222, 42, () => undefined, {
+            instanceTimeout: 5000,
+        });
+        expect(mockedInstanceService).toHaveBeenCalledWith(55123, {
+            timeout: 5000,
+        });
+    });
+    it("passes db options to DatabaseClient", async () => {
+        createMockInstance();
+        createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withInstanceDatabase(9222, 42, () => undefined, {
+            db: { readOnly: false },
+        });
+        expect(mockedDatabaseClient).toHaveBeenCalledWith("/path/to/db.db", {
+            readOnly: false,
+        });
+    });
+    it("passes undefined to InstanceService when no timeout specified", async () => {
+        createMockInstance();
+        createMockDb();
+        mockedDiscoverInstancePort.mockResolvedValue(55123);
+        mockedDiscoverDatabase.mockReturnValue("/path/to/db.db");
+        await withInstanceDatabase(9222, 42, () => undefined);
+        expect(mockedInstanceService).toHaveBeenCalledWith(55123, undefined);
+    });
+});
+//# sourceMappingURL=instance-context.test.js.map

package/dist/services/instance-context.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-context.test.js","sourceRoot":"","sources":["../../src/services/instance-context.test.ts"],"names":[],"mappings":"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"}