capiumbrowser 0.1.0

package/lib/launch-common.js

@@ -0,0 +1,82 @@
+/**
+ * launch-common -- driver-agnostic pieces of a Capium launch, shared by the Playwright and
+ * Puppeteer front-ends: flag assembly, geoip tri-state, and the license status file.
+ */
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const config = require('./config');
+const proxy = require('./proxy');
+
+/**
+ * Build [--proxy-server, --geoip] flags for geo coherence.
+ *
+ * The binary's CapiumGeoipResolver runs at PreBrowserStart ONLY when --geoip is present. A
+ * proxy on its own does NOT trigger it: the lookup is a synchronous, blocking round-trip that
+ * would otherwise add up to 2.5s to every proxied launch. When it does run it resolves the
+ * egress IP (proxy exit, else the host's real public IP) and pins WebRTC / timezone /
+ * geolocation / language -- so the SDK adds no probe of its own. geoipOn is tri-state:
+ *   * null  -> default: add no flag, so NO geo lookup runs (no launch latency) even with a
+ *              proxy. Pass geoip: true to opt into proxy-exit coherence.
+ *   * true  -> ON with --geoip (resolves the egress -- proxy exit, or the host IP if proxyless).
+ *   * false -> OFF with --geoip=false, which the binary honors FIRST (explicit opt-out).
+ * Returns {launchOptions, args}.
+ */
+function proxyAndGeoArgs(spec, geoipOn) {
+  const { launchOptions, args } = proxy.resolveProxyConfig(spec);
+  const out = [...args];
+  if (geoipOn === null || geoipOn === undefined) {
+    // default: no flag, no lookup
+  } else if (geoipOn) {
+    out.push('--geoip');
+  } else {
+    out.push('--geoip=false');
+  }
+  return { launchOptions, args: out };
+}
+
+function buildArgs({ seed, platform, stealthArgs, timezone, locale, extensionPaths, extra }) {
+  let args = [];
+  if (stealthArgs) args = args.concat(config.getDefaultStealthArgs(seed, platform));
+  if (timezone) args.push(`--timezone=${timezone}`); // capium in-binary tz spoof
+  if (locale) {
+    args.push(`--lang=${locale}`);
+    args.push(`--accept-lang=${locale}`);
+  }
+  if (extensionPaths) {
+    const paths = Array.isArray(extensionPaths) ? extensionPaths : [extensionPaths];
+    const joined = paths.join(',');
+    args.push(`--disable-extensions-except=${joined}`);
+    args.push(`--load-extension=${joined}`);
+  }
+  if (extra) args = args.concat(extra);
+  return args;
+}
+
+/**
+ * Create a unique empty file and point the browser at it via CAPIUM_LICENSE_STATUS_FILE.
+ * On a license fail-closed the binary writes "<code>\n<message>" here, so the SDK throws a
+ * precise error from the binary's OWN single verification -- no second server call. A unique
+ * file per launch keeps concurrent launches (a fleet) from clobbering each other; an old
+ * binary that doesn't write it just leaves it empty -> readLaunchStatus null -> stderr
+ * fallback.
+ */
+function newStatusFile(env) {
+  const p = path.join(os.tmpdir(),
+    `capium-lic-${crypto.randomBytes(6).toString('hex')}.err`);
+  fs.writeFileSync(p, '');
+  env.CAPIUM_LICENSE_STATUS_FILE = p;
+  return p;
+}
+
+function clearStatusFile(p) {
+  try {
+    fs.rmSync(p, { force: true });
+  } catch {}
+}
+
+module.exports = { proxyAndGeoArgs, buildArgs, newStatusFile, clearStatusFile };

package/lib/license.js

@@ -0,0 +1,217 @@
+/**
+ * License helpers for the SDK. Enforcement is in the browser binary -- this module
+ * only (a) resolves the key/server so we can pass them to the binary and the
+ * downloader, and (b) offers a dependency-free `status()` for the CLI.
+ * The SDK never holds its own seat (that would double-count one launch as two
+ * concurrent sessions). See https://docs.capiumbrowser.com for the full model.
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { CapiumConfigError, CapiumExpiredError, CapiumServerDownError } = require('./errors');
+
+const DEFAULT_SERVER = 'https://license.capzy.ai';
+
+function licenseFile() {
+  // CAPIUM_LICENSE_FILE is a test/deploy override; the contract path is ~/.capium/license.
+  return process.env.CAPIUM_LICENSE_FILE || path.join(os.homedir(), '.capium', 'license');
+}
+
+function fromFile() {
+  let key = null;
+  let server = null;
+  let text;
+  try {
+    text = fs.readFileSync(licenseFile(), 'utf8');
+  } catch {
+    return { key, server };
+  }
+  for (let line of text.split(/\r?\n/)) {
+    line = line.trim();
+    if (!line || line.startsWith('#') || !line.includes('=')) continue;
+    const i = line.indexOf('=');
+    const k = line.slice(0, i).trim().toUpperCase();
+    const v = line.slice(i + 1).trim();
+    if (k === 'KEY' && !key) key = v;
+    else if (k === 'SERVER' && !server) server = v;
+  }
+  return { key, server };
+}
+
+/**
+ * Resolve from explicit arg then env ONLY (no file). Used to inject into the browser's
+ * environment -- if the key lives only in ~/.capium/license the binary reads that file
+ * itself, so there's nothing to inject.
+ */
+function effective(key = null, server = null) {
+  return {
+    key: key || process.env.CAPIUM_LICENSE_KEY || null,
+    server: server || process.env.CAPIUM_LICENSE_SERVER || null,
+  };
+}
+
+/**
+ * Full resolution: arg -> env -> ~/.capium/license, defaulting the server.
+ * Throws CapiumConfigError if no key is found. Used by `capiumbrowser status`.
+ */
+function resolve(key = null, server = null) {
+  ({ key, server } = effective(key, server));
+  if (!key || !server) {
+    const f = fromFile();
+    key = key || f.key;
+    server = server || f.server;
+  }
+  if (!key) {
+    throw new CapiumConfigError(
+      'no license configured — set CAPIUM_LICENSE_KEY, pass licenseKey: ..., ' +
+        'or create ~/.capium/license with a KEY= line');
+  }
+  return { key, server: (server || DEFAULT_SERVER).replace(/\/+$/, '') };
+}
+
+/**
+ * Signed headers for an authenticated GET (download / update). The key travels in a header
+ * (over TLS), never in the URL; the request target is HMAC-signed -- same scheme as the
+ * licensing calls. `pathAndQuery` is exactly "<path>?<query>".
+ */
+function getHeaders(key, pathAndQuery) {
+  const ts = String(Math.floor(Date.now() / 1000));
+  const sig = crypto.createHmac('sha256', key).update(`${ts}.${pathAndQuery}`).digest('hex');
+  return { 'X-Capzy-License': key, 'X-Capzy-Timestamp': ts, 'X-Capzy-Signature': sig };
+}
+
+/**
+ * Full environment for the browser subprocess: the current env plus any explicitly-resolved
+ * license vars (so a key passed to launch() reaches the self-licensing binary without ever
+ * touching argv / `ps`).
+ */
+function childEnv(key = null, server = null) {
+  const { key: k, server: s } = effective(key, server);
+  const env = { ...process.env };
+  if (k) env.CAPIUM_LICENSE_KEY = k;
+  if (s) env.CAPIUM_LICENSE_SERVER = s;
+  return env;
+}
+
+function machineId() {
+  let raw = null;
+  if (process.platform === 'linux') {
+    for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+      try {
+        raw = fs.readFileSync(p, 'utf8').trim();
+        if (raw) break;
+      } catch {}
+    }
+  } else if (process.platform === 'darwin') {
+    try {
+      const out = execFileSync('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      for (const line of out.split('\n')) {
+        if (line.includes('IOPlatformUUID')) {
+          const parts = line.split('"');
+          raw = parts[parts.length - 2];
+          break;
+        }
+      }
+    } catch {}
+  } else if (process.platform === 'win32') {
+    try {
+      const out = execFileSync('reg', [
+        'query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid',
+      ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const m = out.match(/MachineGuid\s+REG_SZ\s+(\S+)/);
+      if (m) raw = m[1];
+    } catch {}
+  }
+  return raw || os.hostname();
+}
+
+function osName() {
+  return process.platform === 'win32' ? 'windows'
+    : process.platform === 'darwin' ? 'macos' : 'linux';
+}
+
+/**
+ * Read license entitlements (plan, sessions_cap, live_sessions, period_end).
+ *
+ * Signs a read-only `activate` with the license-key HMAC using a status-scoped device
+ * fingerprint + a throwaway public key, so it never disturbs a running browser's real
+ * device enrollment and never consumes a session slot.
+ */
+async function status(key = null, server = null) {
+  ({ key, server } = resolve(key, server));
+  const fp = crypto.createHash('sha256').update('capium-status:' + machineId()).digest('hex');
+  const body = JSON.stringify({
+    license_key: key,
+    device_fp: fp,
+    hostname: os.hostname().slice(0, 100),
+    os: osName(),
+    arch: 'x64',
+    device_pubkey: crypto.randomBytes(32).toString('base64'),
+  });
+  const ts = String(Math.floor(Date.now() / 1000));
+  const sig = crypto.createHmac('sha256', key).update(`${ts}.${body}`).digest('hex');
+  let res;
+  try {
+    res = await fetch(server + '/v1/activate', {
+      method: 'POST',
+      body,
+      headers: {
+        'X-Capzy-Timestamp': ts,
+        'X-Capzy-Device-Fp': fp,
+        'X-Capzy-Signature': sig,
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(10000),
+    });
+  } catch (e) {
+    throw new CapiumServerDownError(`license server unreachable at ${server} (${e.message || e})`);
+  }
+  if (!res.ok) {
+    if (res.status === 401 || res.status === 403) {
+      throw new CapiumExpiredError(
+        `license rejected (${res.status}) — expired, revoked, or invalid key`);
+    }
+    throw new CapiumServerDownError(`status failed: HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  const out = {};
+  for (const f of ['plan', 'sessions_cap', 'live_sessions', 'period_end', 'heartbeat_every']) {
+    out[f] = data[f] !== undefined ? data[f] : null;
+  }
+  return out;
+}
+
+/**
+ * Instant, OFFLINE no-key gate: resolve() throws CapiumConfigError if no key is set in
+ * arg/env/~/.capium/license, so "you forgot the license" surfaces as a typed error BEFORE
+ * a browser is spun up instead of an opaque driver "browser closed" crash.
+ *
+ * Deliberately does NOT hit the server. The browser binary is the SINGLE network verifier
+ * (activate -> session -> heartbeat); duplicating that with an SDK-side check would double
+ * the load on the licensing service. Expired / revoked / seat-limit / server-down all come
+ * back from the binary's one check and are surfaced from its status file via
+ * errors.readLaunchStatus -- no second round-trip.
+ */
+function preflight(key = null, server = null) {
+  resolve(key, server); // -> CapiumConfigError when no key is configured
+}
+
+module.exports = {
+  DEFAULT_SERVER,
+  effective,
+  resolve,
+  getHeaders,
+  childEnv,
+  status,
+  preflight,
+  _fromFile: fromFile,
+  _licenseFile: licenseFile,
+  _machineId: machineId,
+};

package/lib/proxy.js

@@ -0,0 +1,218 @@
+/**
+ * proxy -- proxy URL construction for the SDK.
+ *
+ *   buildProxyArg(spec)  ->  "--proxy-server=..." flag with inline credentials,
+ *                            or null for no proxy. Handles HTTP/HTTPS/SOCKS5,
+ *                            object specs and string URLs.
+ */
+'use strict';
+
+const UNRESERVED = /^[A-Za-z0-9\-._~]$/;
+
+/**
+ * Lenient percent-decode (Python urllib.parse.unquote semantics): valid %XX sequences are
+ * decoded, anything malformed (a lone '%') is left as-is. decodeURIComponent would throw.
+ */
+function lenientUnquote(s) {
+  return String(s).replace(/%([0-9A-Fa-f]{2})/g, (_, h) =>
+    String.fromCharCode(parseInt(h, 16)));
+}
+
+/**
+ * Full RFC-3986 percent-encoding of one --proxy-server userinfo field.
+ *
+ * Encode EVERYTHING outside the unreserved set -- ',', ';', '=', '+', ':', '@' all become
+ * %XX. The reserved chars matter because Chromium's --proxy-server value has its own
+ * grammar: ',' and ';' separate proxy rules and '=' is the scheme=proxy delimiter, so a raw
+ * one splits the config into garbage and the tunnel dies with ERR_TUNNEL_CONNECTION_FAILED
+ * (the Apify "groups-X,country-Y,session-Z" username failure).
+ *
+ * The capium binary percent-DECODES the inline user:pass@ before it authenticates, so the
+ * proxy receives the original literal characters. Encode-in-the-SDK / decode-in-the-binary
+ * is the canonical pairing -- nothing is left raw.
+ *
+ * IDEMPOTENT: unquote first, so a credential that ALREADY arrived percent-encoded isn't
+ * double-encoded (',' -> '%2C' -> '%252C'; the binary decodes only once, so the proxy would
+ * see a literal "%2C" -> ERR_TUNNEL_CONNECTION_FAILED). Mirrors the CDP path
+ * (toDriverProxy), which unquotes too, so inline and CDP normalize identically.
+ */
+function encodeCred(s) {
+  const raw = lenientUnquote(s);
+  let out = '';
+  for (const ch of raw) {
+    if (UNRESERVED.test(ch)) {
+      out += ch;
+    } else {
+      // encode as UTF-8 bytes
+      for (const b of Buffer.from(ch, 'utf8')) {
+        out += '%' + b.toString(16).toUpperCase().padStart(2, '0');
+      }
+    }
+  }
+  return out;
+}
+
+function proxyUrl(scheme, user, pw, host, port) {
+  return `${scheme}://${encodeCred(user)}:${encodeCred(pw)}@${host}:${Math.trunc(Number(port))}`;
+}
+
+/**
+ * (scheme, host, port, user, pass) from an object spec or a string URL. Creds are the raw
+ * (already percent-decoded) values.
+ */
+function specParts(spec) {
+  if (spec && typeof spec === 'object') {
+    const server = spec.server || '';
+    const u = new URL(server.includes('://') ? server : 'http://' + server);
+    return {
+      scheme: (u.protocol || 'http:').replace(/:$/, '') || 'http',
+      host: u.hostname,
+      port: u.port ? Number(u.port) : null,
+      user: spec.username || '',
+      pass: spec.password || '',
+    };
+  }
+  const raw = String(spec);
+  const u = new URL(raw.includes('://') ? raw : 'http://' + raw);
+  return {
+    scheme: (u.protocol || 'http:').replace(/:$/, '') || 'http',
+    host: u.hostname,
+    port: u.port ? Number(u.port) : null,
+    // WHATWG URL does NOT percent-decode username/password; unquote to raw like urlsplit use.
+    user: lenientUnquote(u.username || ''),
+    pass: lenientUnquote(u.password || ''),
+  };
+}
+
+function isNoProxy(spec) {
+  return !spec || spec === 'none' || spec === '0' || spec === false;
+}
+
+/**
+ * Return a --proxy-server=... flag for the capium binary, or null for no proxy.
+ *
+ * Accepted forms:
+ *   null / "" / "none" / "0" / false     ->  no proxy
+ *   "http://user:pass@host:port"         ->  HTTP/HTTPS proxy with credentials
+ *   "socks5://user:pass@host:port"       ->  SOCKS5 with credentials
+ *   "socks5://host:port"                 ->  SOCKS5, no auth
+ *   {server: "scheme://host:port",       ->  object spec; username/password are
+ *    username: "...", password: "..."}       optional -- no-auth if omitted
+ */
+function buildProxyArg(spec) {
+  if (isNoProxy(spec)) return null;
+
+  if (spec && typeof spec === 'object') {
+    const { scheme, host, port, user, pass } = specParts(spec);
+    if (user) return '--proxy-server=' + proxyUrl(scheme, user, pass, host, port);
+    return `--proxy-server=${spec.server}`;
+  }
+
+  const { scheme, host, port, user, pass } = specParts(spec);
+  if (user) return '--proxy-server=' + proxyUrl(scheme, user, pass, host, port);
+  const portStr = port ? `:${port}` : '';
+  return `--proxy-server=${scheme}://${host}${portStr}`;
+}
+
+// ---- proxy channel selection --------------------------------------------------------------
+// Everything now goes through the native inline --proxy-server flag. The capium binary
+// authenticates from the inline user:pass@ itself:
+//   * SOCKS5  -> RFC 1929 username/password in the handshake (socks_connect_job.cc)
+//   * HTTP/S  -> PREEMPTIVE Proxy-Authorization on the FIRST CONNECT
+//                (http_proxy_client_socket.cc; capium-preemptive-proxy-auth.patch)
+// Preemptive auth means the proxy never has to answer 407, which closes the reactive-auth
+// retry loop (net::ERR_TOO_MANY_RETRIES) that inline credentials -- especially country-
+// targeted / special-char usernames like "groups-X,country-Y,session-Z" -- used to trigger.
+//
+// The legacy driver proxy option (CDP auth, answers the 407 over CDP) remains only as an
+// escape hatch for a binary WITHOUT the preemptive patch -- opt in with CAPIUM_INLINE_PROXY_AUTH=0.
+
+/**
+ * Whether the capium binary authenticates from inline --proxy-server credentials.
+ *
+ * Default true: the capium binary decodes the inline user:pass@ itself (SOCKS5 RFC 1929 +
+ * preemptive HTTP Proxy-Authorization), so ALL proxies use the native --proxy-server flag.
+ * Set CAPIUM_INLINE_PROXY_AUTH=0 to force the legacy CDP-auth path for credentialed
+ * HTTP/HTTPS (only needed on a binary that lacks the preemptive-proxy-auth patch).
+ */
+function binarySupportsInlineProxyAuth() {
+  const v = process.env.CAPIUM_INLINE_PROXY_AUTH;
+  if (v !== undefined && v !== null) {
+    return ['1', 'true', 'yes', 'on'].includes(v.trim().toLowerCase());
+  }
+  return true;
+}
+
+function specIsSocks(spec) {
+  return specParts(spec).scheme.toLowerCase().startsWith('socks');
+}
+
+/**
+ * Optional proxy-bypass list from an object spec (the Playwright 'bypass' key).
+ *
+ * Comma-separated hosts/patterns that should connect DIRECT, skipping the proxy
+ * (e.g. "localhost,*.internal"). Only object specs carry it; a string proxy URL has
+ * nowhere to put it. Inline -> --proxy-bypass-list=<v>, CDP -> the option's own 'bypass'.
+ */
+function specBypass(spec) {
+  if (spec && typeof spec === 'object') return spec.bypass || null;
+  return null;
+}
+
+/**
+ * Normalize a spec into a driver proxy option {server, username?, password?}. Credentials
+ * are passed RAW -- the driver handles CDP-auth escaping itself, so nothing is re-encoded.
+ */
+function toDriverProxy(spec) {
+  const { scheme, host, port, user, pass } = specParts(spec);
+  let server = `${scheme}://${host}`;
+  if (port) server += `:${port}`;
+  const d = { server };
+  if (user) {
+    d.username = lenientUnquote(user);
+    d.password = lenientUnquote(pass || '');
+  }
+  const bypass = specBypass(spec);
+  if (bypass) d.bypass = bypass;
+  return d;
+}
+
+/**
+ * Return {launchOptions, args} for launching the capium binary.
+ *
+ * launchOptions -> merged into the driver's launch options (e.g. {proxy: {...}}); args ->
+ * appended to the Chromium arg list. Exactly one carries the proxy for any spec:
+ *   * DEFAULT: everything -> args (native inline --proxy-server; binary self-auths)
+ *   * escape hatch (CAPIUM_INLINE_PROXY_AUTH=0): credentialed HTTP/HTTPS -> launchOptions
+ *     (driver CDP auth), for a binary lacking the preemptive-proxy-auth patch. SOCKS5
+ *     can NEVER go this way (Chrome must receive it inline), so SOCKS always stays inline.
+ *
+ * An object spec's optional "bypass" (comma-separated DIRECT hosts) is carried too:
+ * --proxy-bypass-list=<v> on the inline paths, or the option's own "bypass" on CDP.
+ */
+function resolveProxyConfig(spec, inlineAuth = null) {
+  if (isNoProxy(spec)) return { launchOptions: {}, args: [] };
+  if (inlineAuth === null || inlineAuth === undefined) {
+    inlineAuth = binarySupportsInlineProxyAuth();
+  }
+  const hasCreds = Boolean(specParts(spec).user);
+  if (specIsSocks(spec) || !hasCreds || inlineAuth) {
+    const arg = buildProxyArg(spec);
+    if (!arg) return { launchOptions: {}, args: [] };
+    const args = [arg];
+    const bypass = specBypass(spec);
+    if (bypass) args.push(`--proxy-bypass-list=${bypass}`);
+    return { launchOptions: {}, args };
+  }
+  return { launchOptions: { proxy: toDriverProxy(spec) }, args: [] };
+}
+
+module.exports = {
+  buildProxyArg,
+  resolveProxyConfig,
+  binarySupportsInlineProxyAuth,
+  toDriverProxy,
+  _encodeCred: encodeCred,
+  _lenientUnquote: lenientUnquote,
+  _specParts: specParts,
+};

package/lib/version.js

@@ -0,0 +1,100 @@
+/**
+ * Version of the capium Node SDK (independent of the browser binary version).
+ *
+ * The SDK version and the Capium/Chromium binary version move on separate cadences: you update
+ * the SDK with `npm install -U capiumbrowser`, and the SDK fetches the *default* binary build to
+ * match. Crucially that default is **per platform** -- each OS/arch reaches a stable Capium build
+ * independently (Windows can sit on 150 while macOS is on 151).
+ *
+ * The stable build for each OS is not hardcoded here; it comes from `channels.json`, which ships
+ * inside the package and is the single source of truth (the release pipeline edits that file to
+ * promote an OS to a new stable, and the same file is published to the download server). This
+ * module just loads it; FALLBACK_VERSIONS is used only if the bundled manifest is missing or
+ * corrupt in an install.
+ *
+ * Override order at download time: CAPIUM_VERSION env > per-OS stable from channels.json.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SDK_VERSION = require('../package.json').version;
+
+// Used only if channels.json can't be read (corrupt/removed install). ensureBinary() raises a
+// clear error long before the "unsupported platform" case matters; this keeps lookups total.
+const FALLBACK_VERSIONS = {
+  'windows-x64': '152.0.7977.65', // real Chrome 152 stable per OS (win/mac .65, linux .64)
+  'macos-arm64': '152.0.7977.65',
+  'linux-x64': '152.0.7977.64',
+  'linux-arm64': '152.0.7977.64', // declared; not yet published (see channels.json)
+};
+const DEFAULT_BINARY_VERSION = '152.0.7977.65';
+
+function loadStable() {
+  // The `channels.stable` map from the bundled manifest, or null if unreadable.
+  try {
+    const raw = fs.readFileSync(path.join(__dirname, 'channels.json'), 'utf8');
+    const stable = JSON.parse(raw).channels.stable;
+    return stable && typeof stable === 'object' ? stable : null;
+  } catch {
+    return null;
+  }
+}
+
+const STABLE = loadStable();
+
+function versionsFromManifest() {
+  if (!STABLE) return { ...FALLBACK_VERSIONS };
+  const out = {};
+  for (const [tag, entry] of Object.entries(STABLE)) {
+    if (entry && typeof entry === 'object' && entry.version) out[tag] = entry.version;
+  }
+  return Object.keys(out).length ? out : { ...FALLBACK_VERSIONS };
+}
+
+// Default stable Capium binary build per distro tag, resolved from channels.json.
+const CAPIUM_BINARY_VERSIONS = versionsFromManifest();
+
+/** The current stable Capium binary version for a distro tag (e.g. 'windows-x64'). */
+function binaryVersionFor(tag) {
+  return CAPIUM_BINARY_VERSIONS[tag] || DEFAULT_BINARY_VERSION;
+}
+
+/**
+ * False only when the manifest declares the tag but marks it not-yet-published. Unknown
+ * tags / missing manifest return true so the download layer's own error/404 speaks instead.
+ */
+function isPublished(tag) {
+  if (!STABLE) return true;
+  const entry = STABLE[tag];
+  if (!entry || typeof entry !== 'object') return true;
+  return entry.published !== false;
+}
+
+/**
+ * Best-effort distro tag for the current host, mirroring download.js's mapping. Kept
+ * dependency-free (no require of download.js) so version.js stays loadable in isolation.
+ */
+function hostTag() {
+  const p = process.platform;
+  const osName = p === 'darwin' ? 'macos' : p === 'win32' ? 'windows' : 'linux';
+  const m = os.arch();
+  const arch = m === 'x64' || m === 'ia32' ? 'x64' : m === 'arm64' ? 'arm64' : m;
+  return `${osName}-${arch}`;
+}
+
+// The stable build this SDK targets for THIS host (CLI display, examples). Code that fetches a
+// build should prefer binaryVersionFor(tag) with the tag it already resolved.
+const CAPIUM_BINARY_VERSION = binaryVersionFor(hostTag());
+
+module.exports = {
+  SDK_VERSION,
+  CAPIUM_BINARY_VERSION,
+  CAPIUM_BINARY_VERSIONS,
+  binaryVersionFor,
+  isPublished,
+  hostTag,
+  _FALLBACK_VERSIONS: FALLBACK_VERSIONS,
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "capiumbrowser",
+  "version": "0.1.0",
+  "description": "Drop-in stealth browser SDK on top of Playwright or Puppeteer (Capium Chromium).",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Capzy (https://capzy.ai)",
+  "homepage": "https://capiumbrowser.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/capzy-ai/capiumbrowser.git",
+    "directory": "capiumbrowser-node"
+  },
+  "bugs": {
+    "url": "https://github.com/capzy-ai/capiumbrowser/issues"
+  },
+  "keywords": [
+    "playwright",
+    "puppeteer",
+    "stealth",
+    "chromium",
+    "browser",
+    "fingerprint",
+    "automation"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "capiumbrowser": "bin/capiumbrowser.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./playwright": "./playwright.js",
+    "./puppeteer": "./puppeteer.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "playwright.js",
+    "puppeteer.js",
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "tar": "^7.4.0"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.40.0",
+    "puppeteer-core": ">=21.0.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    },
+    "puppeteer-core": {
+      "optional": true
+    }
+  }
+}