@browserless/agent 0.0.0-stage → 14.0.0

package/src/rules.js

@@ -0,0 +1,312 @@
+'use strict'
+
+const RULE_KEYS = ['selector', 'selectorAll', 'attr', 'type']
+const LOCATION_KEYS = ['selector', 'selectorAll']
+const MAX_RULE_DEPTH = 4
+const MAX_SELECTOR_LENGTH = 300
+const MODEL_DEFAULT_ATTR = 'text'
+
+const isPlainObject = value =>
+  value !== null &&
+  typeof value === 'object' &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value))
+
+const isSelector = value =>
+  typeof value === 'string' && value.trim() !== '' && value.length <= MAX_SELECTOR_LENGTH
+
+const isNested = rule => isPlainObject(rule?.attr)
+
+const hasLocation = rule => LOCATION_KEYS.some(key => key in rule)
+
+const invalidRule = (path, problem) => new TypeError(`Invalid rule \`${path}\`: ${problem}.`)
+
+const assertSelectors = (rule, path) => {
+  for (const key of LOCATION_KEYS) {
+    if (!(key in rule)) continue
+    const selectors = Array.isArray(rule[key]) ? rule[key] : [rule[key]]
+    if (selectors.length === 0 || !selectors.every(isSelector)) {
+      throw invalidRule(path, `${key} must be a CSS selector or a list of them`)
+    }
+  }
+}
+
+const assertRule = (rule, path, depth) => {
+  if (!isPlainObject(rule)) throw invalidRule(path, 'a rule must be an object')
+  if (depth > MAX_RULE_DEPTH) throw invalidRule(path, 'rules are nested too deeply')
+  const unknown = Object.keys(rule).find(key => !RULE_KEYS.includes(key))
+  if (unknown) throw invalidRule(path, `\`${unknown}\` is not supported`)
+  assertSelectors(rule, path)
+  if ('type' in rule && typeof rule.type !== 'string') {
+    throw invalidRule(path, 'type must be a string')
+  }
+  if (!('attr' in rule)) return
+  if (isNested(rule)) return assertRules(rule.attr, `${path}.attr`, depth + 1)
+  const attrs = Array.isArray(rule.attr) ? rule.attr : [rule.attr]
+  if (attrs.length === 0 || !attrs.every(attr => typeof attr === 'string' && attr !== '')) {
+    throw invalidRule(path, 'attr must be an attribute name, a list of them, or nested rules')
+  }
+}
+
+const assertRules = (rules, path = 'data', depth = 1) => {
+  if (!isPlainObject(rules) || Object.keys(rules).length === 0) {
+    throw invalidRule(path, 'rules must be an object with at least one field')
+  }
+  for (const [name, rule] of Object.entries(rules)) {
+    const alternatives = Array.isArray(rule) ? rule : [rule]
+    if (alternatives.length === 0) throw invalidRule(`${path}.${name}`, 'a rule must be an object')
+    for (const alternative of alternatives) assertRule(alternative, `${path}.${name}`, depth)
+  }
+  return rules
+}
+
+const pick = (rule, keys) =>
+  Object.fromEntries(keys.filter(key => key in rule).map(key => [key, rule[key]]))
+
+const writtenLocation = (written, path) => {
+  if (!isPlainObject(written)) throw invalidRule(path, 'the model wrote no rule for this field')
+  if ('selectorAll' in written) return { selectorAll: written.selectorAll }
+  if ('selector' in written) return { selector: written.selector }
+  throw invalidRule(path, 'the model wrote no selector for this field')
+}
+
+const filledAttr = (field, written, path) => {
+  if (isNested(field)) {
+    if (!isNested(written)) {
+      throw invalidRule(path, 'the model wrote no nested rules for this field')
+    }
+    return { attr: fillFields(field.attr, written.attr, `${path}.attr`) }
+  }
+  if ('attr' in field) return { attr: field.attr }
+  if (isNested(written)) throw invalidRule(path, 'the model wrote nested rules for a single value')
+  return isPlainObject(written) && 'attr' in written ? { attr: written.attr } : {}
+}
+
+const fillField = (field, written, path) => {
+  if (Array.isArray(field)) return field.map(alternative => fillField(alternative, written, path))
+  if (hasLocation(field) && !isNested(field)) return field
+  const type = field.type ?? (isPlainObject(written) ? written.type : undefined)
+  return {
+    ...(hasLocation(field) ? pick(field, LOCATION_KEYS) : writtenLocation(written, path)),
+    ...filledAttr(field, written, path),
+    ...(type === undefined ? {} : { type })
+  }
+}
+
+const firstAlternative = rule => (Array.isArray(rule) ? rule[0] : rule)
+
+const fillFields = (fields, written, path = 'data') =>
+  Object.fromEntries(
+    Object.entries(fields).map(([name, field]) => [
+      name,
+      fillField(
+        field,
+        isPlainObject(written) ? firstAlternative(written[name]) : undefined,
+        `${path}.${name}`
+      )
+    ])
+  )
+
+function evaluateRules (data) {
+  const ATTR_PROPERTIES = { html: 'innerHTML', text: 'textContent', val: 'value' }
+  const RAW_ATTRIBUTES = ['href', 'src']
+  const DEFAULT_ATTRS = ['html']
+  const THOUSANDS_ONLY = /^(\d{1,3})([.,])\d{3}(?:\2\d{3})*$/
+  const GROUPED_WITH_DECIMALS = /^(\d{1,3}(?:([.,])\d{3})+)([.,])(\d+)$/
+  const PLAIN_DECIMALS = /^(\d+)[.,](\d+)$/
+  const ZERO_AND_ONE_GROUP_LENGTH = 5
+
+  const toList = value => (Array.isArray(value) ? value : [value])
+  const condense = text => text.replace(/\s+/g, ' ').trim()
+  const isNested = rule =>
+    rule.attr !== null && typeof rule.attr === 'object' && !Array.isArray(rule.attr)
+  const isEmpty = value => value === undefined || value === null || value === ''
+
+  const toNumber = text => {
+    const token = text.replace(/−/g, '-').match(/-?\d[\d.,]*/)?.[0]
+    if (!token) return undefined
+    const sign = token.startsWith('-') ? -1 : 1
+    const digits = token.replace(/^-/, '').replace(/[.,]+$/, '')
+    if (/^\d+$/.test(digits)) return sign * Number(digits)
+    const thousands = digits.match(THOUSANDS_ONLY)
+    const isFractionOfZero =
+      thousands && thousands[1] === '0' && digits.length === ZERO_AND_ONE_GROUP_LENGTH
+    if (thousands && !isFractionOfZero) return sign * Number(digits.replace(/[.,]/g, ''))
+    const grouped = digits.match(GROUPED_WITH_DECIMALS)
+    if (grouped && grouped[2] !== grouped[3]) {
+      return sign * Number(`${grouped[1].replace(/[.,]/g, '')}.${grouped[4]}`)
+    }
+    const decimals = digits.match(PLAIN_DECIMALS)
+    return decimals ? sign * Number(`${decimals[1]}.${decimals[2]}`) : undefined
+  }
+
+  const toUrl = text => {
+    try {
+      const url = new URL(text, document.baseURI)
+      return ['http:', 'https:', 'data:'].includes(url.protocol) ? url.href : undefined
+    } catch {}
+  }
+
+  const toDate = text => {
+    if (!/\d{4}/.test(text)) return undefined
+    const date = new Date(text)
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+  }
+
+  const toAuto = text => {
+    if (/^-?\d+(?:\.\d+)?$/.test(text)) return Number(text)
+    if (text === 'true' || text === 'false') return text === 'true'
+    return text
+  }
+
+  const TYPES = {
+    number: toNumber,
+    url: toUrl,
+    image: toUrl,
+    date: toDate,
+    string: text => text
+  }
+
+  const typed = (value, rule) => {
+    if (isEmpty(value)) return undefined
+    const convert = Object.hasOwn(TYPES, rule.type) ? TYPES[rule.type] : toAuto
+    return convert(String(value))
+  }
+
+  const readAttr = (element, attr) => {
+    if (RAW_ATTRIBUTES.includes(attr)) return element.getAttribute(attr) ?? undefined
+    const property = ATTR_PROPERTIES[attr] || attr
+    const value =
+      typeof element[property] === 'string' ? element[property] : element.getAttribute(attr)
+    if (typeof value !== 'string') return undefined
+    return attr === 'text' ? condense(value) : value
+  }
+
+  const wholePage = rule =>
+    toList(rule.attr || DEFAULT_ATTRS)[0] === 'text'
+      ? condense(document.body.innerText)
+      : document.documentElement.outerHTML
+
+  const invalidSelectors = []
+
+  const splitSelectorList = selector => {
+    const parts = []
+    let depth = 0
+    let current = ''
+    for (const character of selector) {
+      if ('([{'.includes(character)) depth++
+      if (')]}'.includes(character)) depth--
+      if (character === ',' && depth === 0) {
+        parts.push(current)
+        current = ''
+      } else current += character
+    }
+    return [...parts, current]
+  }
+
+  const relativeTo = selector =>
+    splitSelectorList(selector)
+      .map(part => `:scope ${part.trim()}`)
+      .join(', ')
+
+  const query = (scope, selector) => {
+    try {
+      return [...scope.querySelectorAll(scope === document ? selector : relativeTo(selector))]
+    } catch {
+      invalidSelectors.push(selector)
+      return []
+    }
+  }
+
+  const resolve = (element, rule) => {
+    if (!element) return undefined
+    if (!isNested(rule)) {
+      const value = toList(rule.attr || DEFAULT_ATTRS)
+        .map(attr => readAttr(element, attr))
+        .find(found => !isEmpty(found))
+      return typed(value, rule)
+    }
+    return Object.fromEntries(
+      Object.entries(rule.attr).map(([name, nested]) => [name, select(element, nested) ?? null])
+    )
+  }
+
+  const withoutRepeatedPrimitives = values => {
+    const seen = new Set()
+    return values.filter(value => {
+      if (value !== null && typeof value === 'object') return true
+      if (seen.has(value)) return false
+      seen.add(value)
+      return true
+    })
+  }
+
+  const selectAll = (scope, selector, rule, topLevel) => {
+    const values = query(scope, selector).map(element => resolve(element, rule) ?? null)
+    return topLevel ? withoutRepeatedPrimitives(values.filter(value => value !== null)) : values
+  }
+
+  const select = (scope, alternatives) => {
+    const topLevel = scope === document
+    for (const rule of toList(alternatives)) {
+      const iterable = rule.selectorAll !== undefined
+      if (!iterable && rule.selector === undefined) {
+        const value = topLevel ? typed(wholePage(rule), rule) : undefined
+        if (!isEmpty(value)) return value
+        continue
+      }
+      for (const selector of toList(iterable ? rule.selectorAll : rule.selector)) {
+        const value = iterable
+          ? selectAll(scope, selector, rule, topLevel)
+          : resolve(query(scope, selector)[0], rule)
+        if (Array.isArray(value) ? value.length > 0 : !isEmpty(value)) return value
+      }
+    }
+  }
+
+  const values = Object.fromEntries(
+    Object.entries(data)
+      .map(([name, alternatives]) => [name, select(document, alternatives)])
+      .filter(([, value]) => value !== undefined)
+  )
+  return { values, invalidSelectors }
+}
+
+const applyRules = async (page, rules) => {
+  const { values, invalidSelectors } = await page.evaluate(evaluateRules, assertRules(rules))
+  if (invalidSelectors.length > 0) {
+    throw new TypeError(`Invalid CSS selector: ${invalidSelectors[0]}`)
+  }
+  return values
+}
+
+const readingText = rule => {
+  if (Array.isArray(rule)) return rule.map(readingText)
+  if (isNested(rule)) return { ...rule, attr: readingTextByDefault(rule.attr) }
+  return 'attr' in rule ? rule : { ...rule, attr: MODEL_DEFAULT_ATTR }
+}
+
+const readingTextByDefault = rules =>
+  Object.fromEntries(Object.entries(rules).map(([name, rule]) => [name, readingText(rule)]))
+
+const hasEverySelector = rule =>
+  Array.isArray(rule)
+    ? rule.every(hasEverySelector)
+    : hasLocation(rule) && (!isNested(rule) || Object.values(rule.attr).every(hasEverySelector))
+
+const isComplete = rules => Object.values(rules).every(hasEverySelector)
+
+const hasData = value => {
+  if (value === null || value === undefined || value === '') return false
+  if (typeof value !== 'object') return true
+  return Object.values(value).some(hasData)
+}
+
+module.exports = {
+  applyRules,
+  evaluateRules,
+  assertRules,
+  fillFields,
+  readingTextByDefault,
+  isComplete,
+  hasData
+}

package/src/snapshot.js

@@ -0,0 +1,339 @@
+/* global location, scrollX, scrollY, innerWidth, innerHeight, NodeFilter */
+// Adapted from browser-use/jev-ultrafast snapshot.js (MIT). See README.md.
+module.exports = function snapshot () {
+  return (() => {
+    if (!document.body) return null
+    const cache = (window.__browserlessAgent ||= { ids: new WeakMap(), nodes: new Map(), next: 1 })
+    const identity = e => {
+      if (!cache.ids.has(e)) cache.ids.set(e, cache.next++)
+      const id = cache.ids.get(e)
+      cache.nodes.set(id, e)
+      return id
+    }
+    for (const [id, e] of cache.nodes) if (!e.isConnected) cache.nodes.delete(id)
+    const roots = [document]
+    for (const root of roots) {
+      for (const e of root.querySelectorAll('*')) if (e.shadowRoot) roots.push(e.shadowRoot)
+    }
+    const queryAll = selector => roots.flatMap(root => [...root.querySelectorAll(selector)])
+    const flatParent = e => e.assignedSlot || e.parentElement || e.getRootNode().host || null
+    const flatChildren = e => {
+      if (e.tagName === 'SLOT') {
+        const assigned = e.assignedNodes({ flatten: true })
+        return assigned.length ? assigned : [...e.childNodes]
+      }
+      return [...(e.shadowRoot || e).childNodes].filter(
+        child => !['STYLE', 'SCRIPT', 'TEMPLATE'].includes(child.tagName)
+      )
+    }
+    cache.closest = (e, selector) => {
+      for (let current = e; current; current = flatParent(current)) {
+        if (current.matches(selector)) return current
+      }
+      return null
+    }
+    cache.contains = (ancestor, e) => {
+      for (let current = e; current; current = flatParent(current)) {
+        if (current === ancestor) return true
+      }
+      return false
+    }
+    cache.elementFromPoint = (x, y) => {
+      let hit = document.elementFromPoint(x, y)
+      while (hit?.shadowRoot) {
+        const { shadowRoot } = hit
+        const inner = shadowRoot.elementsFromPoint(x, y).find(e => e.getRootNode() === shadowRoot)
+        if (!inner) break
+        hit = inner
+      }
+      return hit
+    }
+    cache.activeElement = () => {
+      let active = document.activeElement
+      while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement
+      return active
+    }
+    const safe = e => !['password', 'file', 'hidden'].includes(e.type)
+    const visible = e =>
+      !cache.closest(e, '[aria-hidden="true"],[inert]') &&
+      e.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+    const name = (e, seen = new Set()) => {
+      if (!e || seen.has(e)) return ''
+      seen.add(e)
+      const referenced = (e.getAttribute('aria-labelledby') || '')
+        .split(/\s+/)
+        .map(id => name(e.getRootNode().getElementById(id), seen))
+        .filter(Boolean)
+        .join(' ')
+      return (
+        referenced ||
+        e.getAttribute('aria-label') ||
+        [...(e.labels || [])]
+          .map(l => name(l, seen))
+          .filter(Boolean)
+          .join(' ') ||
+        (['button', 'submit', 'reset'].includes(e.type) ? e.value : '') ||
+        e.getAttribute('alt') ||
+        (e.tagName === 'INPUT'
+          ? ''
+          : flatChildren(e)
+            .map(n =>
+              n.nodeType === 3
+                ? n.textContent
+                : n.nodeType === 1 && n.getAttribute('aria-hidden') !== 'true'
+                  ? name(n, seen)
+                  : ''
+            )
+            .join(' ')
+            .trim()) ||
+        e.getAttribute('title') ||
+        e.getAttribute('placeholder') ||
+        ''
+      )
+    }
+    const roles = [
+      'button',
+      'link',
+      'checkbox',
+      'radio',
+      'switch',
+      'tab',
+      'menuitem',
+      'menuitemradio',
+      'option',
+      'gridcell',
+      'combobox',
+      'textbox',
+      'searchbox',
+      'spinbutton'
+    ]
+    const selector =
+      'a[href],button,input,textarea,select,summary,[contenteditable]:not([contenteditable="false"]),' +
+      roles.map(role => '[role="' + role + '"]').join(',')
+    const editingHost = e => e.isContentEditable && !e.parentElement?.isContentEditable
+    const typeable = e => ['INPUT', 'TEXTAREA'].includes(e.tagName) || editingHost(e)
+    const role = e => {
+      const explicit = e.getAttribute('role')
+      if (roles.includes(explicit)) return explicit
+      if (e.tagName === 'BUTTON' || e.tagName === 'SUMMARY') return 'button'
+      if (e.tagName === 'A') return 'link'
+      if (e.tagName === 'SELECT') return 'combobox'
+      if (e.tagName === 'TEXTAREA' || editingHost(e)) return 'textbox'
+      if (e.tagName === 'INPUT') {
+        if (['checkbox', 'radio'].includes(e.type)) return e.type
+        if (['button', 'submit', 'reset', 'image'].includes(e.type)) return 'button'
+        if (e.type === 'search') return 'searchbox'
+        if (e.type === 'number') return 'spinbutton'
+        if (['text', 'email', 'url', 'tel'].includes(e.type)) return 'textbox'
+      }
+      return null
+    }
+    cache.pageKey = () => [
+      performance.timeOrigin,
+      location.href,
+      scrollX,
+      scrollY,
+      innerWidth,
+      innerHeight,
+      queryAll('input,textarea,select')
+        .filter(safe)
+        .map(e => [identity(e), e.value, e.checked, e.selectedIndex, e.disabled, e.readOnly])
+    ]
+    cache.guard = e => {
+      if (!e?.isConnected || !visible(e)) return null
+      const scope =
+        cache.closest(e, 'form,dialog,[role="dialog"],article,li,tr,[role="row"]') || flatParent(e)
+      return [
+        identity(e),
+        role(e),
+        name(e),
+        e.value ?? null,
+        e.checked ?? null,
+        e.selectedIndex ?? null,
+        e.readOnly ?? null,
+        e.matches(':disabled'),
+        e.getAttribute('aria-disabled'),
+        e.getAttribute('aria-expanded'),
+        e.getAttribute('aria-checked'),
+        e.getAttribute('aria-selected'),
+        e.tagName === 'SELECT'
+          ? [...e.options].map(o => [
+              o.value,
+              o.label,
+              o.disabled,
+              !!o.closest('optgroup[disabled]')
+            ])
+          : null,
+        e.getAttribute('href'),
+        scope?.innerText?.slice(0, 6000) || '',
+        [...(cache.closest(e, 'form')?.querySelectorAll('input,textarea,select') || [])]
+          .filter(safe)
+          .map(field => [
+            identity(field),
+            field.value,
+            field.checked,
+            field.selectedIndex,
+            field.disabled,
+            field.readOnly
+          ])
+      ]
+    }
+    const actions = []
+    for (const e of queryAll(selector)) {
+      if (
+        !safe(e) ||
+        !visible(e) ||
+        e.matches(':disabled') ||
+        cache.closest(e, '[aria-disabled="true"]')
+      ) {
+        continue
+      }
+      const r = e.getBoundingClientRect()
+      const x = r.x + r.width / 2
+      const y = r.y + r.height / 2
+      const rname = role(e)
+      if (
+        !rname ||
+        r.width <= 0 ||
+        r.height <= 0 ||
+        x < 0 ||
+        y < 0 ||
+        x >= innerWidth ||
+        y >= innerHeight
+      ) {
+        continue
+      }
+      if (rname === 'gridcell' && e.querySelector('button,[role="button"]')) continue
+      const hit = cache.elementFromPoint(x, y)
+      if (hit && !cache.contains(e, hit)) continue
+      const base = {
+        node: identity(e),
+        role: rname,
+        label: name(e) || rname,
+        rect: { x: r.x, y: r.y, w: r.width, h: r.height }
+      }
+      for (const key of ['checked', 'selected', 'expanded']) {
+        const value = e.getAttribute('aria-' + key)
+        if (value !== null) base[key] = value
+      }
+      if (['checkbox', 'radio'].includes(e.type)) base.checked = String(e.checked)
+      if (e.tagName === 'SELECT') {
+        for (const o of e.options) {
+          if (!o.selected && !o.disabled && !o.closest('optgroup[disabled]')) {
+            actions.push({
+              ...base,
+              kind: 'select',
+              value: o.value,
+              current_value: [...e.selectedOptions].map(o => o.label).join(', '),
+              label: base.label + ' → ' + o.label
+            })
+          }
+        }
+      } else {
+        const editable =
+          typeable(e) &&
+          !e.readOnly &&
+          e.getAttribute('aria-readonly') !== 'true' &&
+          (['textbox', 'searchbox', 'spinbutton'].includes(rname) ||
+            (rname === 'combobox' && ['INPUT', 'TEXTAREA'].includes(e.tagName)))
+        const value =
+          'value' in e
+            ? String(e.value)
+            : e.isContentEditable || rname === 'combobox'
+              ? e.innerText.trim()
+              : ''
+        actions.push({ ...base, kind: editable ? 'fill' : 'click', value })
+        if (editable) actions.push({ ...base, kind: 'click', value, label: 'Open ' + base.label })
+        if (editable && e.tagName === 'INPUT' && value) {
+          actions.push({ ...base, kind: 'submit', value, label: 'Submit ' + base.label })
+        }
+      }
+    }
+    const words = []
+    const range = document.createRange()
+    let length = 0
+    for (const root of roots) {
+      const walker = document.createTreeWalker(
+        root === document ? document.body : root,
+        NodeFilter.SHOW_TEXT
+      )
+      let node
+      while ((node = walker.nextNode()) && length < 6000) {
+        const value = node.textContent.trim()
+        const parent = node.parentElement || root.host
+        if (
+          !value ||
+          !parent ||
+          parent.closest('script,style,noscript,template') ||
+          !visible(parent)
+        ) {
+          continue
+        }
+        range.selectNodeContents(node)
+        const r = range.getBoundingClientRect()
+        if (
+          r.width > 0 &&
+          r.height > 0 &&
+          r.bottom > 0 &&
+          r.top < innerHeight &&
+          r.right > 0 &&
+          r.left < innerWidth
+        ) {
+          words.push(value)
+          length += value.length
+        }
+      }
+    }
+    const unsupported = []
+    for (const e of queryAll('iframe,canvas,input[type="password"],input[type="file"]')) {
+      if (visible(e)) unsupported.push(e.tagName === 'INPUT' ? e.type : e.tagName.toLowerCase())
+    }
+    const text = words.join('\n').slice(0, 6000)
+    const height = document.documentElement.scrollHeight
+    const pageKey = cache.pageKey()
+    const guards = {}
+    for (const a of actions) {
+      if (!(a.node in guards)) guards[a.node] = cache.guard(cache.nodes.get(a.node))
+    }
+    // Compare meaning and identity. Geometry is always resolved and hit-tested just before input.
+    const semantics = actions.map(({ rect, ...action }) => action)
+    const marker = [
+      performance.timeOrigin,
+      location.href,
+      scrollX,
+      scrollY,
+      innerWidth,
+      innerHeight,
+      document.title,
+      text,
+      semantics,
+      pageKey[6]
+    ]
+    const omittedActions = Math.max(0, actions.length - 250)
+    actions.splice(250)
+    actions.forEach((a, i) => {
+      a.id = 'e' + (i + 1)
+    })
+    if (scrollY + innerHeight < height - 2) {
+      actions.push({ id: 'scroll_down', kind: 'scroll', label: 'Scroll down', delta: 560 })
+    }
+    if (scrollY > 0) {
+      actions.push({ id: 'scroll_up', kind: 'scroll', label: 'Scroll up', delta: -560 })
+    }
+    actions.push({ id: 'wait', kind: 'wait', label: 'Wait for the page to update' })
+    return {
+      url: location.href,
+      title: document.title,
+      w: innerWidth,
+      h: innerHeight,
+      text,
+      unsupported,
+      scroll: { y: scrollY, height },
+      actions,
+      marker,
+      pageKey,
+      guards,
+      omittedActions
+    }
+  })()
+}