@openpicker/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Usertour
+
+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/README.md

@@ -0,0 +1,29 @@
+# @openpicker/sdk
+
+SDK for invoking the [openpicker](https://github.com/usertour/openpicker) browser extension to
+pick a CSS selector on any page.
+
+```bash
+npm install @openpicker/sdk
+```
+
+```ts
+import { createOpenpicker, OpenpickerError } from "@openpicker/sdk"
+
+const op = createOpenpicker({ appName: "My App" })
+
+if (await op.isAvailable()) {
+  // `url` is required: the extension opens it in a tab, the user picks there,
+  // and the selector is routed back here.
+  const { selector, matchCount, element } = await op.pick({
+    url: "https://app.example.com",
+    screenshot: "element", // optional: "none" | "element" | "viewport"
+  })
+  console.log(selector, matchCount, element)
+} else {
+  // Prompt the user to install the openpicker extension.
+}
+```
+
+See the [protocol spec](https://github.com/usertour/openpicker/blob/main/PROTOCOL.md) for the
+wire format, and the [main README](https://github.com/usertour/openpicker) for the full API.

package/dist/index.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+// ../protocol/src/constants.ts
+var CHANNEL = "openpicker";
+var PROTOCOL_VERSION = 1;
+
+// ../protocol/src/envelope.ts
+function isEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.channel === CHANNEL && typeof v.kind === "string";
+}
+
+// src/index.ts
+var OpenpickerError = class extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "OpenpickerError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+};
+var ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function randomId(length) {
+  const bytes = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(bytes);
+  let out = "";
+  for (const byte of bytes) {
+    out += ID_ALPHABET[byte % ID_ALPHABET.length];
+  }
+  return out;
+}
+var Openpicker = class {
+  options;
+  win;
+  instanceId = randomId(6);
+  pending = /* @__PURE__ */ new Map();
+  seq = 0;
+  listening = false;
+  constructor(options = {}) {
+    this.options = options;
+    this.win = options.targetWindow ?? window;
+  }
+  onMessage = (event) => {
+    if (event.source !== this.win) return;
+    if (event.origin !== this.win.origin) return;
+    const data = event.data;
+    if (!isEnvelope(data) || data.kind !== "res") return;
+    const entry = this.pending.get(data.id);
+    if (!entry) return;
+    this.pending.delete(data.id);
+    if (entry.timer) clearTimeout(entry.timer);
+    if (data.ok) {
+      entry.resolve(data.result);
+    } else {
+      entry.reject(
+        new OpenpickerError(
+          data.error ?? { code: "internal_error", message: "openpicker: malformed error response" }
+        )
+      );
+    }
+  };
+  ensureListening() {
+    if (this.listening) return;
+    this.win.addEventListener("message", this.onMessage);
+    this.listening = true;
+  }
+  request(method, params, timeout) {
+    this.ensureListening();
+    const id = `op:${this.instanceId}:${++this.seq}`;
+    const envelope = {
+      channel: CHANNEL,
+      v: PROTOCOL_VERSION,
+      kind: "req",
+      id,
+      method,
+      params
+    };
+    return new Promise((resolve, reject) => {
+      let timer;
+      if (timeout > 0) {
+        timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(
+            new OpenpickerError({
+              code: "timeout",
+              message: `openpicker: "${method}" timed out after ${timeout}ms`
+            })
+          );
+        }, timeout);
+      }
+      this.pending.set(id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.win.postMessage(envelope, this.win.origin);
+    });
+  }
+  /** Probe the extension and negotiate version/capabilities. */
+  async ping() {
+    try {
+      return await this.request(
+        "ping",
+        { appName: this.options.appName },
+        this.options.pingTimeout ?? 1500
+      );
+    } catch (error) {
+      if (error instanceof OpenpickerError && error.code === "timeout") {
+        throw new OpenpickerError({
+          code: "extension_not_installed",
+          message: "openpicker: the extension is not installed or did not respond"
+        });
+      }
+      throw error;
+    }
+  }
+  /** Convenience: resolve `true` if the extension responds to a ping. */
+  async isAvailable() {
+    try {
+      await this.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Open `params.url` in a tab and start element selection there; resolves when the
+   * user confirms (OK) in the sidebar. `url` is required — the extension picks
+   * across the tab/origin boundary, which is the thing a page can't do for itself.
+   */
+  pick(params) {
+    return this.request("pick", { appName: this.options.appName, ...params }, 0);
+  }
+  /** Cancel an in-flight pick. */
+  async cancel() {
+    await this.request("cancel", {}, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Highlight element(s) matching a selector without entering pick mode. */
+  highlight(selector) {
+    return this.request("highlight", { selector }, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Remove any active highlight. */
+  async clearHighlight() {
+    await this.request("clearHighlight", {}, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Bring the calling tab to the foreground (a tab can only focus itself). */
+  async activateSelf() {
+    await this.request("activateSelf", {}, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Whether the cross-tab target tab opened by this tab is still open. */
+  async isTargetOpen() {
+    const { open } = await this.request("isTargetOpen", {}, this.options.defaultTimeout ?? 3e3);
+    return open;
+  }
+  /** Stop listening and reject any in-flight requests. */
+  destroy() {
+    if (this.listening) {
+      this.win.removeEventListener("message", this.onMessage);
+      this.listening = false;
+    }
+    for (const entry of this.pending.values()) {
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.reject(
+        new OpenpickerError({ code: "internal_error", message: "openpicker: instance destroyed" })
+      );
+    }
+    this.pending.clear();
+  }
+};
+function createOpenpicker(options) {
+  return new Openpicker(options);
+}
+
+exports.Openpicker = Openpicker;
+exports.OpenpickerError = OpenpickerError;
+exports.createOpenpicker = createOpenpicker;

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import { PingResult, PickParams, PickResult, HighlightResult, ProtocolError } from '@openpicker/protocol';
+export { HighlightResult, PickParams, PickResult, PickedElement, PingResult, ProtocolError, ScreenshotMode } from '@openpicker/protocol';
+
+/** Error thrown by the SDK; carries a stable {@link ProtocolError.code}. */
+declare class OpenpickerError extends Error {
+    readonly code: ProtocolError["code"];
+    readonly data?: unknown;
+    constructor(error: ProtocolError);
+}
+interface OpenpickerOptions {
+    /** Display name shown in the extension's consent prompt (never trusted for auth). */
+    appName?: string;
+    /** Timeout for `ping` before assuming the extension is not installed. Default 1500ms. */
+    pingTimeout?: number;
+    /** Timeout for quick operations (cancel/highlight/clearHighlight). Default 3000ms. */
+    defaultTimeout?: number;
+    /** Window to communicate over. Defaults to the global `window`. */
+    targetWindow?: Window;
+}
+/**
+ * A handle to the openpicker browser extension. Construct one per integration via
+ * {@link createOpenpicker}; call {@link Openpicker.destroy} when done.
+ */
+declare class Openpicker {
+    private readonly options;
+    private readonly win;
+    private readonly instanceId;
+    private readonly pending;
+    private seq;
+    private listening;
+    constructor(options?: OpenpickerOptions);
+    private onMessage;
+    private ensureListening;
+    private request;
+    /** Probe the extension and negotiate version/capabilities. */
+    ping(): Promise<PingResult>;
+    /** Convenience: resolve `true` if the extension responds to a ping. */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Open `params.url` in a tab and start element selection there; resolves when the
+     * user confirms (OK) in the sidebar. `url` is required — the extension picks
+     * across the tab/origin boundary, which is the thing a page can't do for itself.
+     */
+    pick(params: PickParams): Promise<PickResult>;
+    /** Cancel an in-flight pick. */
+    cancel(): Promise<void>;
+    /** Highlight element(s) matching a selector without entering pick mode. */
+    highlight(selector: string): Promise<HighlightResult>;
+    /** Remove any active highlight. */
+    clearHighlight(): Promise<void>;
+    /** Bring the calling tab to the foreground (a tab can only focus itself). */
+    activateSelf(): Promise<void>;
+    /** Whether the cross-tab target tab opened by this tab is still open. */
+    isTargetOpen(): Promise<boolean>;
+    /** Stop listening and reject any in-flight requests. */
+    destroy(): void;
+}
+/** Create an {@link Openpicker} handle. */
+declare function createOpenpicker(options?: OpenpickerOptions): Openpicker;
+
+export { Openpicker, OpenpickerError, type OpenpickerOptions, createOpenpicker };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import { PingResult, PickParams, PickResult, HighlightResult, ProtocolError } from '@openpicker/protocol';
+export { HighlightResult, PickParams, PickResult, PickedElement, PingResult, ProtocolError, ScreenshotMode } from '@openpicker/protocol';
+
+/** Error thrown by the SDK; carries a stable {@link ProtocolError.code}. */
+declare class OpenpickerError extends Error {
+    readonly code: ProtocolError["code"];
+    readonly data?: unknown;
+    constructor(error: ProtocolError);
+}
+interface OpenpickerOptions {
+    /** Display name shown in the extension's consent prompt (never trusted for auth). */
+    appName?: string;
+    /** Timeout for `ping` before assuming the extension is not installed. Default 1500ms. */
+    pingTimeout?: number;
+    /** Timeout for quick operations (cancel/highlight/clearHighlight). Default 3000ms. */
+    defaultTimeout?: number;
+    /** Window to communicate over. Defaults to the global `window`. */
+    targetWindow?: Window;
+}
+/**
+ * A handle to the openpicker browser extension. Construct one per integration via
+ * {@link createOpenpicker}; call {@link Openpicker.destroy} when done.
+ */
+declare class Openpicker {
+    private readonly options;
+    private readonly win;
+    private readonly instanceId;
+    private readonly pending;
+    private seq;
+    private listening;
+    constructor(options?: OpenpickerOptions);
+    private onMessage;
+    private ensureListening;
+    private request;
+    /** Probe the extension and negotiate version/capabilities. */
+    ping(): Promise<PingResult>;
+    /** Convenience: resolve `true` if the extension responds to a ping. */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Open `params.url` in a tab and start element selection there; resolves when the
+     * user confirms (OK) in the sidebar. `url` is required — the extension picks
+     * across the tab/origin boundary, which is the thing a page can't do for itself.
+     */
+    pick(params: PickParams): Promise<PickResult>;
+    /** Cancel an in-flight pick. */
+    cancel(): Promise<void>;
+    /** Highlight element(s) matching a selector without entering pick mode. */
+    highlight(selector: string): Promise<HighlightResult>;
+    /** Remove any active highlight. */
+    clearHighlight(): Promise<void>;
+    /** Bring the calling tab to the foreground (a tab can only focus itself). */
+    activateSelf(): Promise<void>;
+    /** Whether the cross-tab target tab opened by this tab is still open. */
+    isTargetOpen(): Promise<boolean>;
+    /** Stop listening and reject any in-flight requests. */
+    destroy(): void;
+}
+/** Create an {@link Openpicker} handle. */
+declare function createOpenpicker(options?: OpenpickerOptions): Openpicker;
+
+export { Openpicker, OpenpickerError, type OpenpickerOptions, createOpenpicker };

package/dist/index.js

@@ -0,0 +1,175 @@
+// ../protocol/src/constants.ts
+var CHANNEL = "openpicker";
+var PROTOCOL_VERSION = 1;
+
+// ../protocol/src/envelope.ts
+function isEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.channel === CHANNEL && typeof v.kind === "string";
+}
+
+// src/index.ts
+var OpenpickerError = class extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "OpenpickerError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+};
+var ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function randomId(length) {
+  const bytes = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(bytes);
+  let out = "";
+  for (const byte of bytes) {
+    out += ID_ALPHABET[byte % ID_ALPHABET.length];
+  }
+  return out;
+}
+var Openpicker = class {
+  options;
+  win;
+  instanceId = randomId(6);
+  pending = /* @__PURE__ */ new Map();
+  seq = 0;
+  listening = false;
+  constructor(options = {}) {
+    this.options = options;
+    this.win = options.targetWindow ?? window;
+  }
+  onMessage = (event) => {
+    if (event.source !== this.win) return;
+    if (event.origin !== this.win.origin) return;
+    const data = event.data;
+    if (!isEnvelope(data) || data.kind !== "res") return;
+    const entry = this.pending.get(data.id);
+    if (!entry) return;
+    this.pending.delete(data.id);
+    if (entry.timer) clearTimeout(entry.timer);
+    if (data.ok) {
+      entry.resolve(data.result);
+    } else {
+      entry.reject(
+        new OpenpickerError(
+          data.error ?? { code: "internal_error", message: "openpicker: malformed error response" }
+        )
+      );
+    }
+  };
+  ensureListening() {
+    if (this.listening) return;
+    this.win.addEventListener("message", this.onMessage);
+    this.listening = true;
+  }
+  request(method, params, timeout) {
+    this.ensureListening();
+    const id = `op:${this.instanceId}:${++this.seq}`;
+    const envelope = {
+      channel: CHANNEL,
+      v: PROTOCOL_VERSION,
+      kind: "req",
+      id,
+      method,
+      params
+    };
+    return new Promise((resolve, reject) => {
+      let timer;
+      if (timeout > 0) {
+        timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(
+            new OpenpickerError({
+              code: "timeout",
+              message: `openpicker: "${method}" timed out after ${timeout}ms`
+            })
+          );
+        }, timeout);
+      }
+      this.pending.set(id, {
+        resolve,
+        reject,
+        timer
+      });
+      this.win.postMessage(envelope, this.win.origin);
+    });
+  }
+  /** Probe the extension and negotiate version/capabilities. */
+  async ping() {
+    try {
+      return await this.request(
+        "ping",
+        { appName: this.options.appName },
+        this.options.pingTimeout ?? 1500
+      );
+    } catch (error) {
+      if (error instanceof OpenpickerError && error.code === "timeout") {
+        throw new OpenpickerError({
+          code: "extension_not_installed",
+          message: "openpicker: the extension is not installed or did not respond"
+        });
+      }
+      throw error;
+    }
+  }
+  /** Convenience: resolve `true` if the extension responds to a ping. */
+  async isAvailable() {
+    try {
+      await this.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Open `params.url` in a tab and start element selection there; resolves when the
+   * user confirms (OK) in the sidebar. `url` is required — the extension picks
+   * across the tab/origin boundary, which is the thing a page can't do for itself.
+   */
+  pick(params) {
+    return this.request("pick", { appName: this.options.appName, ...params }, 0);
+  }
+  /** Cancel an in-flight pick. */
+  async cancel() {
+    await this.request("cancel", {}, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Highlight element(s) matching a selector without entering pick mode. */
+  highlight(selector) {
+    return this.request("highlight", { selector }, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Remove any active highlight. */
+  async clearHighlight() {
+    await this.request("clearHighlight", {}, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Bring the calling tab to the foreground (a tab can only focus itself). */
+  async activateSelf() {
+    await this.request("activateSelf", {}, this.options.defaultTimeout ?? 3e3);
+  }
+  /** Whether the cross-tab target tab opened by this tab is still open. */
+  async isTargetOpen() {
+    const { open } = await this.request("isTargetOpen", {}, this.options.defaultTimeout ?? 3e3);
+    return open;
+  }
+  /** Stop listening and reject any in-flight requests. */
+  destroy() {
+    if (this.listening) {
+      this.win.removeEventListener("message", this.onMessage);
+      this.listening = false;
+    }
+    for (const entry of this.pending.values()) {
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.reject(
+        new OpenpickerError({ code: "internal_error", message: "openpicker: instance destroyed" })
+      );
+    }
+    this.pending.clear();
+  }
+};
+function createOpenpicker(options) {
+  return new Openpicker(options);
+}
+
+export { Openpicker, OpenpickerError, createOpenpicker };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@openpicker/sdk",
+  "version": "0.1.0",
+  "description": "Open-source CSS element picker — SDK for invoking the openpicker browser extension.",
+  "license": "MIT",
+  "author": "Usertour (https://www.usertour.io)",
+  "homepage": "https://github.com/usertour/openpicker#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usertour/openpicker.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/usertour/openpicker/issues"
+  },
+  "keywords": [
+    "openpicker",
+    "element-picker",
+    "css-selector",
+    "selector",
+    "picker",
+    "browser-extension",
+    "devtools",
+    "dom"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "@openpicker/protocol": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}