@phi-code-admin/browser 1.0.1 → 1.0.2

package/dist/index.d.ts

@@ -30,11 +30,21 @@ export declare function closeAll(): Promise<void>;
 export interface CreateTabResult {
     tabId: string;
     userId: string;
+    sessionKey: string;
     url?: string;
 }
-/** Open a new browser tab. Returns the tab id used by the other tools. */
-export declare function createTab(options: {
+/**
+ * Open a new browser tab. Returns the tab id used by the other tools.
+ *
+ * The camofox-browser REST contract requires every tab to be associated
+ * with a `userId` (logical user) AND a `sessionKey` (logical session
+ * inside that user — used to group tabs that should share cookies /
+ * fingerprints / proxies). Phi-code's chat agents only need one of each,
+ * so both default to a constant sentinel when omitted.
+ */
+export declare function createTab(options?: {
     userId?: string;
+    sessionKey?: string;
     url?: string;
     viewport?: {
         width: number;
@@ -56,6 +66,7 @@ export declare function navigate(options: {
     url: string;
     tabId?: string;
     userId?: string;
+    sessionKey?: string;
     waitUntil?: "load" | "domcontentloaded" | "networkidle";
     timeoutMs?: number;
 }): Promise<NavigateResult>;
@@ -65,6 +76,7 @@ export declare function navigate(options: {
  */
 export declare function snapshot(options: {
     tabId: string;
+    userId?: string;
 }): Promise<unknown>;
 export interface ExtractResult {
     url?: string;
@@ -82,6 +94,7 @@ export interface ExtractResult {
 export declare function extract(options: {
     tabId?: string;
     userId?: string;
+    sessionKey?: string;
     url?: string;
     mode?: "readability" | "html" | "text";
 }): Promise<ExtractResult>;
@@ -93,6 +106,7 @@ export interface ScreenshotResult {
 /** Capture a screenshot of the given tab as a base64-encoded PNG. */
 export declare function screenshot(options: {
     tabId: string;
+    userId?: string;
     fullPage?: boolean;
     clip?: {
         x: number;
@@ -110,10 +124,12 @@ export declare function search(options: {
     query: string;
     engine?: "google" | "duckduckgo" | "bing";
     userId?: string;
+    sessionKey?: string;
 }): Promise<ExtractResult>;
 /** Click an element by ref (from `snapshot`) or CSS selector. */
 export declare function click(options: {
     tabId: string;
+    userId?: string;
     ref?: string;
     selector?: string;
     button?: "left" | "right" | "middle";
@@ -123,6 +139,7 @@ export declare function click(options: {
 /** Type text into a focused element (or one targeted via ref/selector). */
 export declare function type(options: {
     tabId: string;
+    userId?: string;
     text: string;
     ref?: string;
     selector?: string;
@@ -134,6 +151,7 @@ export declare function type(options: {
 /** Scroll the page or a specific element by ref. */
 export declare function scroll(options: {
     tabId: string;
+    userId?: string;
     direction: "up" | "down" | "left" | "right";
     ref?: string;
     pixels?: number;
@@ -143,6 +161,7 @@ export declare function scroll(options: {
 /** Close a single tab. The underlying browser context is kept warm. */
 export declare function closeTab(options: {
     tabId: string;
+    userId?: string;
 }): Promise<{
     tabId: string;
 }>;

package/dist/index.js

@@ -26,6 +26,7 @@ let serverProcess = null;
 let serverPort = null;
 let bootPromise = null;
 const DEFAULT_USER_ID = "phi-default";
+const DEFAULT_SESSION_KEY = "phi-default-session";
 const HEALTH_TIMEOUT_MS = 30_000;
 const HEALTH_POLL_INTERVAL_MS = 250;
 async function findAvailablePort() {
@@ -243,16 +244,25 @@ async function request(pathname, options = {}) {
         clearTimeout(timeout);
     }
 }
-/** Open a new browser tab. Returns the tab id used by the other tools. */
-export async function createTab(options) {
+/**
+ * Open a new browser tab. Returns the tab id used by the other tools.
+ *
+ * The camofox-browser REST contract requires every tab to be associated
+ * with a `userId` (logical user) AND a `sessionKey` (logical session
+ * inside that user — used to group tabs that should share cookies /
+ * fingerprints / proxies). Phi-code's chat agents only need one of each,
+ * so both default to a constant sentinel when omitted.
+ */
+export async function createTab(options = {}) {
     const userId = options.userId ?? DEFAULT_USER_ID;
-    const body = { userId };
+    const sessionKey = options.sessionKey ?? DEFAULT_SESSION_KEY;
+    const body = { userId, sessionKey };
     if (options.url)
         body.url = options.url;
     if (options.viewport)
         body.viewport = options.viewport;
     const res = await request("/tabs", { method: "POST", body });
-    return { tabId: res.tabId, userId, url: options.url };
+    return { tabId: res.tabId, userId, sessionKey, url: options.url };
 }
 /**
  * Navigate the given tab (or a freshly opened one) to a URL.
@@ -262,11 +272,19 @@ export async function createTab(options) {
 export async function navigate(options) {
     let tabId = options.tabId;
     if (!tabId) {
-        const tab = await createTab({ userId: options.userId, url: options.url });
+        const tab = await createTab({
+            userId: options.userId,
+            sessionKey: options.sessionKey,
+            url: options.url,
+        });
         tabId = tab.tabId;
         return { tabId, url: options.url };
     }
-    const body = { url: options.url };
+    const body = {
+        userId: options.userId ?? DEFAULT_USER_ID,
+        sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+        url: options.url,
+    };
     if (options.waitUntil)
         body.waitUntil = options.waitUntil;
     if (options.timeoutMs)
@@ -279,7 +297,9 @@ export async function navigate(options) {
  * Refs returned here can be used with `click`/`type`/`scroll`.
  */
 export async function snapshot(options) {
-    return await request(`/tabs/${encodeURIComponent(options.tabId)}/snapshot`);
+    const userId = options.userId ?? DEFAULT_USER_ID;
+    const qs = `?userId=${encodeURIComponent(userId)}`;
+    return await request(`/tabs/${encodeURIComponent(options.tabId)}/snapshot${qs}`);
 }
 /**
  * Extract the readable content of the current page (Readability-style).
@@ -292,32 +312,45 @@ export async function extract(options) {
         if (!options.url) {
             throw new Error("extract() requires either tabId or url");
         }
-        const tab = await createTab({ userId: options.userId, url: options.url });
+        const tab = await createTab({
+            userId: options.userId,
+            sessionKey: options.sessionKey,
+            url: options.url,
+        });
         tabId = tab.tabId;
         // Wait for the navigation to settle before extracting.
         await request(`/tabs/${encodeURIComponent(tabId)}/wait`, {
             method: "POST",
-            body: { event: "load" },
+            body: { userId: options.userId ?? DEFAULT_USER_ID, event: "load" },
         }).catch(() => { });
     }
     else if (options.url) {
-        await navigate({ tabId, url: options.url });
+        await navigate({
+            tabId,
+            url: options.url,
+            userId: options.userId,
+            sessionKey: options.sessionKey,
+        });
     }
     const res = await request(`/tabs/${encodeURIComponent(tabId)}/extract`, {
         method: "POST",
-        body: { mode: options.mode ?? "readability" },
+        body: {
+            userId: options.userId ?? DEFAULT_USER_ID,
+            sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+            mode: options.mode ?? "readability",
+        },
     });
     return res;
 }
 /** Capture a screenshot of the given tab as a base64-encoded PNG. */
 export async function screenshot(options) {
     const query = new URLSearchParams();
+    query.set("userId", options.userId ?? DEFAULT_USER_ID);
     if (options.fullPage)
         query.set("fullPage", "1");
     if (options.clip)
         query.set("clip", JSON.stringify(options.clip));
-    const qs = query.toString();
-    const res = await request(`/tabs/${encodeURIComponent(options.tabId)}/screenshot${qs ? `?${qs}` : ""}`);
+    const res = await request(`/tabs/${encodeURIComponent(options.tabId)}/screenshot?${query.toString()}`);
     return {
         tabId: options.tabId,
         mimeType: res.mimeType ?? "image/png",
@@ -336,14 +369,14 @@ export async function search(options) {
         : engine === "bing"
             ? `https://www.bing.com/search?q=${encodeURIComponent(options.query)}`
             : `https://duckduckgo.com/?q=${encodeURIComponent(options.query)}`;
-    return await extract({ url, userId: options.userId });
+    return await extract({ url, userId: options.userId, sessionKey: options.sessionKey });
 }
 /** Click an element by ref (from `snapshot`) or CSS selector. */
 export async function click(options) {
     if (!options.ref && !options.selector) {
         throw new Error("click() requires `ref` or `selector`");
     }
-    const body = {};
+    const body = { userId: options.userId ?? DEFAULT_USER_ID };
     if (options.ref)
         body.ref = options.ref;
     if (options.selector)
@@ -358,7 +391,10 @@ export async function click(options) {
 }
 /** Type text into a focused element (or one targeted via ref/selector). */
 export async function type(options) {
-    const body = { text: options.text };
+    const body = {
+        userId: options.userId ?? DEFAULT_USER_ID,
+        text: options.text,
+    };
     if (options.ref)
         body.ref = options.ref;
     if (options.selector)
@@ -375,7 +411,10 @@ export async function type(options) {
 }
 /** Scroll the page or a specific element by ref. */
 export async function scroll(options) {
-    const body = { direction: options.direction };
+    const body = {
+        userId: options.userId ?? DEFAULT_USER_ID,
+        direction: options.direction,
+    };
     if (options.ref)
         body.ref = options.ref;
     if (options.pixels)
@@ -388,7 +427,9 @@ export async function scroll(options) {
 }
 /** Close a single tab. The underlying browser context is kept warm. */
 export async function closeTab(options) {
-    await request(`/tabs/${encodeURIComponent(options.tabId)}`, { method: "DELETE" });
+    const userId = options.userId ?? DEFAULT_USER_ID;
+    const qs = `?userId=${encodeURIComponent(userId)}`;
+    await request(`/tabs/${encodeURIComponent(options.tabId)}${qs}`, { method: "DELETE" });
     return { tabId: options.tabId };
 }
 /** List all open tabs for a user. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/browser",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"description": "Phi-code browser automation API: lazy-start the bundled Camoufox + camofox-browser server and expose 10 high-level tools (navigate, extract, screenshot, click, type, scroll, snapshot, search, close_tab, list_tabs) as plain ES module functions. Zero external dependencies at runtime.",
 	"type": "module",
 	"main": "dist/index.js",