@effect-uai/browser 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Betalyra Sociedade Unipessoal Lda.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/Connect.d.mts

@@ -0,0 +1,31 @@
+import * as CoreBrowser from "@effect-uai/core/Browser";
+import { Context, Layer } from "effect";
+
+//#region src/Connect.d.ts
+declare namespace Connect_d_exports {
+  export { CdpBrowser, CdpConnectConfig, layer };
+}
+type CdpConnectConfig = {
+  /**
+   * Browser-level CDP WebSocket endpoint, e.g.
+   * `ws://127.0.0.1:9222/devtools/browser/<uuid>` for local Chromium or
+   * obscura, or a hosted provider's connect URL (credentials in the URL).
+   */
+  readonly endpoint: string;
+};
+declare const CdpBrowser_base: Context.ServiceClass<CdpBrowser, "@betalyra/effect-uai/providers/browser/CdpBrowser", CoreBrowser.BrowserService>;
+/**
+ * Provider tag. Identical surface to the core `Browser` service; both tags
+ * are registered by {@link layer}.
+ */
+declare class CdpBrowser extends CdpBrowser_base {}
+/**
+ * Registers the generic CDP adapter against both the provider tag
+ * ({@link CdpBrowser}) and the core `Browser` tag. No capability markers:
+ * proxy / stealth / recording are vendor features, not part of a bare CDP
+ * endpoint.
+ */
+declare const layer: (config: CdpConnectConfig) => Layer.Layer<CdpBrowser | CoreBrowser.Browser>;
+//#endregion
+export { CdpBrowser, CdpConnectConfig, layer, Connect_d_exports as t };
+//# sourceMappingURL=Connect.d.mts.map

package/dist/Connect.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Connect.d.mts","names":[],"sources":["../src/Connect.ts"],"mappings":";;;;;;;KAyBY,gBAAA;;;;;;WAMD,QAAA;AAAA;AAAA,cACV,eAAA;;;AAMD;;cAAa,UAAA,SAAmB,eAAA;;AAuIhC;;;;;cAAa,KAAA,GAAS,MAAA,EAAQ,gBAAA,KAAmB,KAAA,CAAM,KAAA,CAAM,UAAA,GAAa,WAAA,CAAY,OAAA"}

package/dist/Connect.mjs

@@ -0,0 +1,122 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+import { openCdp } from "./internal/cdp.mjs";
+import { isMethodMissing, makeSession } from "./internal/session.mjs";
+import * as CoreBrowser from "@effect-uai/core/Browser";
+import * as BrowserError from "@effect-uai/core/BrowserError";
+import { Context, Effect, Layer } from "effect";
+//#region src/Connect.ts
+/**
+* Generic CDP connect provider.
+*
+* Point it at any browser-level CDP WebSocket endpoint and it registers
+* the core `Browser` capability over it. This is the shared floor for the
+* whole field: a locally launched Chromium (`--remote-debugging-port`),
+* obscura's partial CDP server, or a hosted vendor's `wss://` connect URL
+* pasted straight in. Vendor-specific packages (session-create REST call,
+* auth handshake) can layer on top and reuse this data plane.
+*
+* Sessions map to CDP targets: `create` opens a fresh target (tab),
+* `attach` re-attaches to an existing one by target id (finalizer detaches
+* without closing, for warm reuse), `destroy` closes the target from
+* anywhere. The `timeout` / `idleTimeout` knobs on the create request are
+* enforced locally by the session's reaper fibers; a plain CDP endpoint
+* has no server-side cap to mirror them to.
+*/
+var Connect_exports = /* @__PURE__ */ __exportAll({
+	CdpBrowser: () => CdpBrowser,
+	layer: () => layer
+});
+const PROVIDER = "cdp";
+/**
+* Provider tag. Identical surface to the core `Browser` service; both tags
+* are registered by {@link layer}.
+*/
+var CdpBrowser = class extends Context.Service()("@betalyra/effect-uai/providers/browser/CdpBrowser") {};
+const mapCreate = (e) => new BrowserError.BrowserCreateFailed({
+	provider: PROVIDER,
+	...e.reason !== void 0 ? { reason: e.reason } : {},
+	raw: e
+});
+const mapLookup = (id) => (e) => e.kind === "reply" && /no target|not found|invalid target|no session/i.test(e.reason ?? "") ? new BrowserError.BrowserSessionNotFound({
+	provider: PROVIDER,
+	id
+}) : mapCreate(e);
+/**
+* Enable the domains the session verbs rely on. Partial CDP servers that
+* auto-enable (or don't know an `enable` method) are tolerated: a
+* method-missing reply is not an error.
+*/
+const enableDomains = (cdp, sessionId) => Effect.forEach([
+	"Page.enable",
+	"Runtime.enable",
+	"Network.enable"
+], (method) => cdp.send(method, {}, sessionId).pipe(Effect.catchIf(isMethodMissing, () => Effect.succeed({})))).pipe(Effect.asVoid, Effect.mapError(mapCreate));
+const applyViewport = (cdp, sessionId, viewport) => cdp.send("Emulation.setDeviceMetricsOverride", {
+	width: viewport.width,
+	height: viewport.height,
+	deviceScaleFactor: 1,
+	mobile: false
+}, sessionId).pipe(Effect.catchIf(isMethodMissing, () => Effect.succeed({})), Effect.asVoid, Effect.mapError(mapCreate));
+const makeService = (config) => ({
+	create: (request) => Effect.gen(function* () {
+		const cdp = yield* openCdp(config.endpoint);
+		const { targetId } = yield* cdp.send("Target.createTarget", { url: "about:blank" }).pipe(Effect.mapError(mapCreate));
+		const closeTarget = cdp.send("Target.closeTarget", { targetId }).pipe(Effect.ignore);
+		yield* Effect.addFinalizer(() => closeTarget);
+		const { sessionId } = yield* cdp.send("Target.attachToTarget", {
+			targetId,
+			flatten: true
+		}).pipe(Effect.mapError(mapCreate));
+		yield* enableDomains(cdp, sessionId);
+		if (request.viewport !== void 0) yield* applyViewport(cdp, sessionId, request.viewport);
+		return yield* makeSession({
+			cdp,
+			id: CoreBrowser.BrowserSessionId(targetId),
+			sessionId,
+			provider: PROVIDER,
+			request,
+			dispose: closeTarget
+		});
+	}),
+	attach: (id) => Effect.gen(function* () {
+		const cdp = yield* openCdp(config.endpoint);
+		const { sessionId } = yield* cdp.send("Target.attachToTarget", {
+			targetId: id,
+			flatten: true
+		}).pipe(Effect.mapError(mapLookup(id)));
+		yield* Effect.addFinalizer(() => cdp.send("Target.detachFromTarget", { sessionId }).pipe(Effect.ignore));
+		yield* enableDomains(cdp, sessionId);
+		return yield* makeSession({
+			cdp,
+			id,
+			sessionId,
+			provider: PROVIDER,
+			request: {},
+			dispose: Effect.void
+		});
+	}),
+	list: Effect.scoped(Effect.gen(function* () {
+		const { targetInfos } = yield* (yield* openCdp(config.endpoint)).send("Target.getTargets").pipe(Effect.mapError(mapCreate));
+		return targetInfos.filter((target) => target.type === "page").map((target) => ({
+			id: CoreBrowser.BrowserSessionId(target.targetId),
+			...target.url !== "" ? { url: target.url } : {}
+		}));
+	})),
+	destroy: (id) => Effect.scoped(Effect.gen(function* () {
+		yield* (yield* openCdp(config.endpoint)).send("Target.closeTarget", { targetId: id }).pipe(Effect.mapError(mapLookup(id)));
+	}))
+});
+/**
+* Registers the generic CDP adapter against both the provider tag
+* ({@link CdpBrowser}) and the core `Browser` tag. No capability markers:
+* proxy / stealth / recording are vendor features, not part of a bare CDP
+* endpoint.
+*/
+const layer = (config) => {
+	const service = makeService(config);
+	return Layer.mergeAll(Layer.succeed(CdpBrowser, service), Layer.succeed(CoreBrowser.Browser, service));
+};
+//#endregion
+export { CdpBrowser, layer, Connect_exports as t };
+
+//# sourceMappingURL=Connect.mjs.map

package/dist/Connect.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Connect.mjs","names":[],"sources":["../src/Connect.ts"],"sourcesContent":["/**\n * Generic CDP connect provider.\n *\n * Point it at any browser-level CDP WebSocket endpoint and it registers\n * the core `Browser` capability over it. This is the shared floor for the\n * whole field: a locally launched Chromium (`--remote-debugging-port`),\n * obscura's partial CDP server, or a hosted vendor's `wss://` connect URL\n * pasted straight in. Vendor-specific packages (session-create REST call,\n * auth handshake) can layer on top and reuse this data plane.\n *\n * Sessions map to CDP targets: `create` opens a fresh target (tab),\n * `attach` re-attaches to an existing one by target id (finalizer detaches\n * without closing, for warm reuse), `destroy` closes the target from\n * anywhere. The `timeout` / `idleTimeout` knobs on the create request are\n * enforced locally by the session's reaper fibers; a plain CDP endpoint\n * has no server-side cap to mirror them to.\n */\nimport * as CoreBrowser from \"@effect-uai/core/Browser\"\nimport * as BrowserError from \"@effect-uai/core/BrowserError\"\nimport { Context, Effect, Layer } from \"effect\"\nimport { type Cdp, type CdpError, openCdp } from \"./internal/cdp.js\"\nimport { isMethodMissing, makeSession } from \"./internal/session.js\"\n\nconst PROVIDER = \"cdp\"\n\nexport type CdpConnectConfig = {\n  /**\n   * Browser-level CDP WebSocket endpoint, e.g.\n   * `ws://127.0.0.1:9222/devtools/browser/<uuid>` for local Chromium or\n   * obscura, or a hosted provider's connect URL (credentials in the URL).\n   */\n  readonly endpoint: string\n}\n\n/**\n * Provider tag. Identical surface to the core `Browser` service; both tags\n * are registered by {@link layer}.\n */\nexport class CdpBrowser extends Context.Service<CdpBrowser, CoreBrowser.BrowserService>()(\n  \"@betalyra/effect-uai/providers/browser/CdpBrowser\",\n) {}\n\n// ---------------------------------------------------------------------------\n// Error mapping (control-plane operations; the session maps its own).\n// ---------------------------------------------------------------------------\n\nconst mapCreate = (e: CdpError): BrowserError.BrowserError =>\n  new BrowserError.BrowserCreateFailed({\n    provider: PROVIDER,\n    ...(e.reason !== undefined ? { reason: e.reason } : {}),\n    raw: e,\n  })\n\nconst mapLookup =\n  (id: string) =>\n  (e: CdpError): BrowserError.BrowserError =>\n    e.kind === \"reply\" && /no target|not found|invalid target|no session/i.test(e.reason ?? \"\")\n      ? new BrowserError.BrowserSessionNotFound({ provider: PROVIDER, id })\n      : mapCreate(e)\n\n// ---------------------------------------------------------------------------\n// Service\n// ---------------------------------------------------------------------------\n\n/**\n * Enable the domains the session verbs rely on. Partial CDP servers that\n * auto-enable (or don't know an `enable` method) are tolerated: a\n * method-missing reply is not an error.\n */\nconst enableDomains = (cdp: Cdp, sessionId: string) =>\n  Effect.forEach([\"Page.enable\", \"Runtime.enable\", \"Network.enable\"] as const, (method) =>\n    cdp.send(method, {}, sessionId).pipe(Effect.catchIf(isMethodMissing, () => Effect.succeed({}))),\n  ).pipe(Effect.asVoid, Effect.mapError(mapCreate))\n\nconst applyViewport = (\n  cdp: Cdp,\n  sessionId: string,\n  viewport: NonNullable<CoreBrowser.CommonSessionRequest[\"viewport\"]>,\n) =>\n  cdp\n    .send(\n      \"Emulation.setDeviceMetricsOverride\",\n      { width: viewport.width, height: viewport.height, deviceScaleFactor: 1, mobile: false },\n      sessionId,\n    )\n    .pipe(\n      // No Emulation domain: the engine's default viewport stands.\n      Effect.catchIf(isMethodMissing, () => Effect.succeed({})),\n      Effect.asVoid,\n      Effect.mapError(mapCreate),\n    )\n\nconst makeService = (config: CdpConnectConfig): CoreBrowser.BrowserService => ({\n  create: (request) =>\n    Effect.gen(function* () {\n      const cdp = yield* openCdp(config.endpoint)\n      const { targetId } = yield* cdp\n        .send(\"Target.createTarget\", { url: \"about:blank\" })\n        .pipe(Effect.mapError(mapCreate))\n      const closeTarget = cdp.send(\"Target.closeTarget\", { targetId }).pipe(Effect.ignore)\n      yield* Effect.addFinalizer(() => closeTarget)\n      const { sessionId } = yield* cdp\n        .send(\"Target.attachToTarget\", { targetId, flatten: true })\n        .pipe(Effect.mapError(mapCreate))\n      yield* enableDomains(cdp, sessionId)\n      if (request.viewport !== undefined) {\n        yield* applyViewport(cdp, sessionId, request.viewport)\n      }\n      return yield* makeSession({\n        cdp,\n        id: CoreBrowser.BrowserSessionId(targetId),\n        sessionId,\n        provider: PROVIDER,\n        request,\n        dispose: closeTarget,\n      })\n    }),\n\n  attach: (id) =>\n    Effect.gen(function* () {\n      const cdp = yield* openCdp(config.endpoint)\n      const { sessionId } = yield* cdp\n        .send(\"Target.attachToTarget\", { targetId: id, flatten: true })\n        .pipe(Effect.mapError(mapLookup(id)))\n      // Detach on scope close; the target keeps running for warm reuse.\n      yield* Effect.addFinalizer(() =>\n        cdp.send(\"Target.detachFromTarget\", { sessionId }).pipe(Effect.ignore),\n      )\n      yield* enableDomains(cdp, sessionId)\n      return yield* makeSession({\n        cdp,\n        id,\n        sessionId,\n        provider: PROVIDER,\n        request: {},\n        dispose: Effect.void,\n      })\n    }),\n\n  list: Effect.scoped(\n    Effect.gen(function* () {\n      const cdp = yield* openCdp(config.endpoint)\n      const { targetInfos } = yield* cdp.send(\"Target.getTargets\").pipe(Effect.mapError(mapCreate))\n      return targetInfos\n        .filter((target) => target.type === \"page\")\n        .map(\n          (target): CoreBrowser.BrowserSessionRef => ({\n            id: CoreBrowser.BrowserSessionId(target.targetId),\n            ...(target.url !== \"\" ? { url: target.url } : {}),\n          }),\n        )\n    }),\n  ),\n\n  destroy: (id) =>\n    Effect.scoped(\n      Effect.gen(function* () {\n        const cdp = yield* openCdp(config.endpoint)\n        yield* cdp.send(\"Target.closeTarget\", { targetId: id }).pipe(Effect.mapError(mapLookup(id)))\n      }),\n    ),\n})\n\n// ---------------------------------------------------------------------------\n// Layer\n// ---------------------------------------------------------------------------\n\n/**\n * Registers the generic CDP adapter against both the provider tag\n * ({@link CdpBrowser}) and the core `Browser` tag. No capability markers:\n * proxy / stealth / recording are vendor features, not part of a bare CDP\n * endpoint.\n */\nexport const layer = (config: CdpConnectConfig): Layer.Layer<CdpBrowser | CoreBrowser.Browser> => {\n  const service = makeService(config)\n  return Layer.mergeAll(\n    Layer.succeed(CdpBrowser, service),\n    Layer.succeed(CoreBrowser.Browser, service),\n  )\n}\n"],"mappings":"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"}