surfsky 0.0.1 → 0.0.3

package/README.md

@@ -47,7 +47,9 @@ import { Surfsky } from "surfsky";
 // or new Surfsky({ apiToken: "...", baseUrl: "..." }) instead of env vars
 await using client = new Surfsky();
 // starts a session, stops it when the block ends so it doesn't keep billing
-await using browser = await client.browser({ proxy: { tier: "premium", country: "us" } });
+await using browser = await client.browser({
+  proxy: { tier: "premium", country: "us" },
+});
 await browser.goto("https://duckduckgo.com", { waitUntil: "domcontentloaded" });
 await browser.type('[name="q"]', "surfsky cloud browser");
 await browser.click("#searchbox_homepage button[type=submit]");
@@ -125,7 +127,8 @@ If you need more control, write your own loop on top of the pool:
 
 ```ts
 await using pool = await client.browsers();
-await pool.lease(async (browser) => {   // waits for a free browser
+await pool.lease(async (browser) => {
+  // waits for a free browser
   await browser.goto("https://example.com");
   console.log(await browser.title());
 });
@@ -179,12 +182,14 @@ built-in pools:
 import { ProxyCycle, ProxyTemplate } from "surfsky";
 
 proxy = { tier: "premium", country: "us", region: "ny", type: "mobile" }; // Surfsky premium
-proxy = { tier: "shared", country: "us" };                               // Surfsky shared, for tests
-proxy = { country: "de" };                                               // premium if set up, else shared
-proxy = "socks5://user:pass@host:1080";                                  // your own
-proxy = new ProxyCycle(myProxies);                                       // round-robin over your own list
-proxy = new ProxyTemplate("http://user-sessid-{session}:pw@gate.example.com:7000");
-proxy = async () => pickOne();                                           // any function, sync or async
+proxy = { tier: "shared", country: "us" }; // Surfsky shared, for tests
+proxy = { country: "de" }; // premium if set up, else shared
+proxy = "socks5://user:pass@host:1080"; // your own
+proxy = new ProxyCycle(myProxies); // round-robin over your own list
+proxy = new ProxyTemplate(
+  "http://user-sessid-{session}:pw@gate.example.com:7000",
+);
+proxy = async () => pickOne(); // any function, sync or async
 ```
 
 `client.proxies` lists available countries, regions and cities, plus your quota.
@@ -277,6 +282,10 @@ waits for one of its own and throws `RateLimitError` only if it has none.
 
 ### Reading
 
+`selector` is CSS, or XPath when it starts with `//`, `..` or `xpath=`. XPath
+covers the DOM reads below and `screenshot({ selector })`; `innerText`,
+`allInnerTexts`, `selectOption` and the input methods take CSS only.
+
 | Method                                                       | Description                                                                             |
 | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
 | `url()`, `title()`                                           | Current URL and title.                                                                  |
@@ -408,64 +417,6 @@ Live tests start real sessions and bill your account:
 SURFSKY_LIVE_TESTS=1 SURFSKY_API_TOKEN=... SURFSKY_API_BASE_URL=... bun run test:live
 ```
 
-## Releasing
-
-One-time, GitHub:
-
-```sh
-gh repo create surfskyio/surfsky-js --public --source=. --remote=origin --push
-```
-
-CI (`.github/workflows/ci.yml`) then runs on every push and PR: lint, typecheck,
-tests and a build on Node 22, 24 and 26, plus the same on Bun.
-
-One-time, npm: publishing runs from `.github/workflows/release.yml` with no npm
-token, so it needs [trusted
-publishing](https://docs.npmjs.com/trusted-publishers) configured for the
-package — provider GitHub Actions, repository `surfskyio/surfsky-js`, workflow
-`release.yml`, environment `npm`, publish allowed. A trusted publisher is a
-setting *on a package*, so the first version goes out by hand:
-
-```sh
-npm login
-bun run check && bun run build
-npm publish   # no --provenance: that needs the OIDC token only CI has
-```
-
-Then attach the publisher, on npmjs.com under the package's settings or, with
-npm new enough to have the command, from the shell:
-
-```sh
-npm trust github surfsky --repo surfskyio/surfsky-js --file release.yml \
-  --env npm --allow-publish
-```
-
-The alternative to all of it is a granular access token in the repo as
-`NPM_TOKEN`, with `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` added to the
-publish step.
-
-Two things bite here: npm never validates a trusted-publisher config when you
-save it, so a wrong workflow name surfaces only as a failed publish, and
-`repository.url` in `package.json` has to match the GitHub repository exactly.
-
-The `npm` environment is also where a required reviewer goes, if a release
-should wait for an approval.
-
-Every release after that is a tag:
-
-```sh
-# bump "version" in package.json first
-bun run check && bun run build
-git commit -am "release: v0.1.0"
-git tag v0.1.0
-git push origin main --tags
-```
-
-The workflow refuses to publish when the tag and `package.json` disagree, then
-runs `bun run check`, builds, imports `dist/index.js` once to prove the bundle
-loads, and publishes. `files` limits the tarball to `dist/`, `README.md`,
-`LICENSE` and `package.json` - check it with `npm pack --dry-run`.
-
 ## License
 
 MIT

package/dist/index.js

@@ -865,6 +865,9 @@ const WORLD_NAME = "utility";
 /** A dialog is answered after this long, as a person would. */
 const DIALOG_DELAY = [600, 1400];
 const FUNCTION = /^\s*(async\s+)?(function\b|\([^()]*\)\s*=>|[\w$]+\s*=>)/;
+function asXPath(s) {
+	return /^\s*(xpath=|\/\/|\.\.)/.test(s) ? s.trim().replace(/^xpath=/, "") : void 0;
+}
 const SELECT = `(selector, value, label) => {
   const el = document.querySelector(selector);
   if (!el) return null;
@@ -1329,6 +1332,8 @@ var Page = class extends Actions {
 	}
 	async count(selector) {
 		const document = await this.send("DOM.getDocument", { depth: 0 });
+		const xpath = asXPath(selector);
+		if (xpath !== void 0) return (await this.#search(xpath)).length;
 		return ((await this.send("DOM.querySelectorAll", {
 			nodeId: document.root.nodeId,
 			selector
@@ -1371,11 +1376,26 @@ var Page = class extends Actions {
 	}
 	async #nodeId(selector) {
 		const document = await this.send("DOM.getDocument", { depth: 0 });
+		const xpath = asXPath(selector);
+		if (xpath !== void 0) return (await this.#search(xpath))[0];
 		return (await this.send("DOM.querySelector", {
 			nodeId: document.root.nodeId,
 			selector
 		})).nodeId || void 0;
 	}
+	async #search(query) {
+		const { searchId, resultCount = 0 } = await this.send("DOM.performSearch", { query });
+		try {
+			if (!resultCount) return [];
+			return (await this.send("DOM.getSearchResults", {
+				searchId,
+				fromIndex: 0,
+				toIndex: resultCount
+			})).nodeIds ?? [];
+		} finally {
+			await this.send("DOM.discardSearchResults", { searchId }).catch(() => void 0);
+		}
+	}
 	/** Wait until the URL contains the fragment. Returns the URL. */
 	async waitForUrl(fragment, options = {}) {
 		const deadline = new Deadline(options.timeout ?? 3e4, `the page did not reach '${fragment}'`);
@@ -2598,7 +2618,7 @@ var Proxies = class {
 };
 //#endregion
 //#region src/version.ts
-const VERSION = "0.0.1";
+const VERSION = "0.0.3";
 //#endregion
 //#region src/client.ts
 function userAgent() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surfsky",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "TypeScript SDK for the Surfsky antidetect browser cloud.",
   "keywords": [
     "surfsky",