@microlink/google 0.0.0 → 0.1.1

package/src/js/main.js

@@ -0,0 +1,397 @@
+const createHeroStats = () => {
+  const stats = document.createElement('div')
+  stats.className = 'hero-stats reveal-on-load'
+  stats.innerHTML = `
+    <div class="hero-stat"><strong>10</strong><span>Google verticals</span></div>
+    <div class="hero-stat"><strong>~1s</strong><span>Typical latency</span></div>
+    <div class="hero-stat hero-stat--serialization"><strong>HTML/MARKDOWN</strong><span>Output serialization</span></div>
+  `
+  return stats
+}
+
+const createVisualBadges = () => {
+  const badges = document.createElement('div')
+  badges.className = 'hero-badges'
+  badges.innerHTML = `
+    <div class="hero-badge top">10 products</div>
+    <div class="hero-badge bottom">&lt;1s response</div>
+  `
+  return badges
+}
+
+const decorateHero = section => {
+  const hero = section.querySelector('div[align="center"]')
+  if (!hero || hero.dataset.enhanced === 'true') return
+
+  hero.dataset.enhanced = 'true'
+  hero.className = 'hero-block'
+
+  const image = hero.querySelector('img')
+  const summary = hero.querySelector('p')
+
+  const copy = document.createElement('div')
+  copy.className = 'hero-copy'
+
+  const eyebrow = document.createElement('div')
+  eyebrow.className = 'hero-eyebrow reveal-on-load'
+  eyebrow.textContent = 'npm i @microlink/google'
+
+  const title = document.createElement('h1')
+  title.innerHTML = 'Structured <span>Google</span><br>API for LLMs.'
+  title.className = 'reveal-on-load'
+
+  copy.append(eyebrow, title)
+
+  if (summary) {
+    summary.classList.add('reveal-on-load')
+    copy.append(summary)
+  }
+
+  const visual = document.createElement('div')
+  visual.className = 'hero-visual reveal-on-load'
+  visual.innerHTML = `
+    <div class="browser-frame">
+      <div class="browser-bar">
+        <span class="browser-dots"><i></i><i></i><i></i></span>
+        <span class="browser-url">https://search.microlink.io</span>
+      </div>
+      <div class="browser-screen"></div>
+    </div>
+  `
+
+  if (image) {
+    image.className = 'hero-banner'
+    visual.querySelector('.browser-screen').append(image)
+  }
+
+  visual.append(createVisualBadges())
+
+  hero.replaceChildren(copy, visual)
+  hero.after(createHeroStats())
+}
+
+const decorateUseCases = section => {
+  const useCasesHeading = [...section.querySelectorAll('h2')].find(
+    node => node.textContent.trim().toLowerCase() === 'common llm use cases'
+  )
+
+  if (!useCasesHeading) return
+
+  const intro = useCasesHeading.nextElementSibling
+  const list = intro?.nextElementSibling
+  if (!list || list.tagName !== 'UL' || list.dataset.enhanced === 'true') return
+
+  list.dataset.enhanced = 'true'
+  list.classList.add('use-case-grid')
+
+  const variants = [
+    'use-case-card--agentic',
+    'use-case-card--rag',
+    'use-case-card--news',
+    'use-case-card--local'
+  ]
+
+  ;[...list.children].forEach((item, index) => {
+    item.classList.add('use-case-card', 'reveal-on-load')
+    if (variants[index]) item.classList.add(variants[index])
+
+    const link = item.querySelector('a')
+    if (link) {
+      const title = link.textContent.trim()
+      const description = item.textContent.replace(title, '').trim()
+      const heading = document.createElement('strong')
+
+      heading.textContent = title
+      link.replaceChildren(heading)
+
+      if (description) {
+        const body = document.createElement('p')
+        body.textContent = description
+        link.append(body)
+      }
+
+      link.classList.add('use-case-link')
+      item.replaceChildren(link)
+    }
+  })
+
+  const heroStats = section.querySelector('.hero-stats')
+  if (heroStats && !section.querySelector('.hero-use-cases')) {
+    const heroUseCases = document.createElement('div')
+    const heroIntro = document.createElement('p')
+
+    heroUseCases.className = 'hero-use-cases reveal-on-load'
+    heroIntro.className = 'hero-use-cases__intro'
+    heroIntro.textContent =
+      'Explore the most common LLM workflows and jump straight to the tutorial that matches your use case.'
+
+    list.classList.add('hero-use-cases__grid')
+
+    heroUseCases.append(heroIntro, list)
+    heroStats.after(heroUseCases)
+  }
+}
+
+const decorateCodeBlocks = section => {
+  section.querySelectorAll('pre').forEach(pre => {
+    if (pre.parentElement?.classList.contains('code-shell')) return
+    const shell = document.createElement('div')
+    const header = document.createElement('div')
+    const code = pre.querySelector('code')
+    const languageClass = [...(code?.classList || [])].find(value =>
+      value.startsWith('language-')
+    )
+    shell.className = 'code-shell'
+    header.className = 'code-shell__header'
+    header.innerHTML = `
+      <span class="code-shell__dots" aria-hidden="true"><i></i><i></i><i></i></span>
+      <span class="code-shell__label">${
+        languageClass ? languageClass.replace('language-', '') : 'code'
+      }</span>
+    `
+    pre.parentNode.insertBefore(shell, pre)
+    shell.append(header, pre)
+  })
+}
+
+const decorateTables = section => {
+  section.querySelectorAll('table').forEach(table => {
+    if (table.parentElement?.classList.contains('table-shell')) return
+    const shell = document.createElement('div')
+    shell.className = 'table-shell'
+    table.parentNode.insertBefore(shell, table)
+    shell.append(table)
+  })
+}
+
+const revealContent = section => {
+  ;[...section.querySelectorAll('h2, h3')].forEach(node =>
+    node.classList.add('reveal-on-load')
+  )
+}
+
+const disableDocsifyDefaultScrollSpy = section => {
+  section
+    .querySelectorAll(':is(h1, h2, h3, h4, h5) > a.anchor[data-id]')
+    .forEach(anchor => {
+      anchor.classList.remove('anchor')
+    })
+}
+
+let teardownNavigationTracking = () => {}
+
+const decodeValue = value => {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+const extractSectionIdFromHref = href => {
+  if (!href) return null
+
+  const value = href.trim()
+  const hashIndex = value.indexOf('#')
+  const hash = hashIndex >= 0 ? value.slice(hashIndex + 1) : value
+
+  if (!hash) return null
+
+  const isRouteHash = hash.startsWith('/')
+  const normalizedHash = isRouteHash ? hash.slice(1) : hash
+  const [, query = ''] = normalizedHash.split('?')
+  const idFromQuery = query ? new URLSearchParams(query).get('id') : null
+
+  if (idFromQuery) return decodeValue(idFromQuery)
+  if (isRouteHash) return null
+
+  const [idCandidate = ''] = normalizedHash.split('?')
+  return idCandidate ? decodeValue(idCandidate) : null
+}
+
+const setupNavigationTracking = section => {
+  const sidebarNav = document.querySelector('.sidebar .sidebar-nav')
+  if (!sidebarNav) return () => {}
+
+  const navLinks = [...sidebarNav.querySelectorAll('a[href]')]
+  const trackedLinks = navLinks
+    .map(link => ({
+      id: extractSectionIdFromHref(link.getAttribute('href')),
+      link
+    }))
+    .filter(entry => entry.id)
+
+  const trackedIds = new Set(trackedLinks.map(entry => entry.id))
+  const headings = [...section.querySelectorAll('h2[id], h3[id]')]
+  const headingsToTrack = headings.filter(heading => trackedIds.has(heading.id))
+  const scopedHeadings = headingsToTrack.length > 0 ? headingsToTrack : headings
+  const firstHeadingId = scopedHeadings[0]?.id || trackedLinks[0]?.id || null
+
+  let activeId = null
+
+  const setActiveLink = id => {
+    navLinks.forEach(link => {
+      link.classList.remove('active')
+      link.classList.remove('is-active')
+      link.removeAttribute('aria-current')
+      link.closest('li')?.classList.remove('active')
+      link.closest('li')?.classList.remove('is-active')
+    })
+
+    const targetId = id || firstHeadingId
+    const activeLink =
+      trackedLinks.find(entry => entry.id === targetId)?.link ||
+      navLinks.find(link => link.closest('li')?.classList.contains('active')) ||
+      navLinks[0]
+
+    if (!activeLink) return
+
+    activeLink.classList.add('active', 'is-active')
+    activeLink.setAttribute('aria-current', 'location')
+    const activeItem = activeLink.closest('li')
+
+    activeItem?.classList.add('active', 'is-active')
+
+    let parentItem = activeItem?.parentElement?.closest('li')
+    while (parentItem) {
+      parentItem.classList.add('active')
+      parentItem = parentItem.parentElement?.closest('li')
+    }
+
+    activeId = extractSectionIdFromHref(activeLink.getAttribute('href'))
+  }
+
+  const getCurrentSectionId = () => {
+    const triggerOffset = Math.max(8, window.innerHeight * 0.03)
+    const threshold = window.scrollY + triggerOffset
+    let currentSectionId = null
+
+    for (const heading of scopedHeadings) {
+      if (heading.offsetTop <= threshold) {
+        currentSectionId = heading.id
+        continue
+      }
+      break
+    }
+
+    return currentSectionId
+  }
+
+  let frameId = null
+
+  const syncActiveLink = () => {
+    frameId = null
+
+    if (scopedHeadings.length === 0) {
+      setActiveLink(null)
+      return
+    }
+
+    const sectionId = getCurrentSectionId()
+    const firstHeadingTop = scopedHeadings[0].offsetTop
+    const nearTopThreshold = Math.max(8, window.innerHeight * 0.03)
+    const isBeforeFirstHeading =
+      window.scrollY + nearTopThreshold < firstHeadingTop
+
+    if (isBeforeFirstHeading) {
+      setActiveLink(firstHeadingId)
+      return
+    }
+
+    if (sectionId) {
+      setActiveLink(sectionId)
+      return
+    }
+
+    if (!activeId) {
+      setActiveLink(firstHeadingId)
+    }
+  }
+
+  const requestSync = () => {
+    if (frameId !== null) return
+    frameId = window.requestAnimationFrame(syncActiveLink)
+  }
+
+  const handleNavClick = event => {
+    const link = event.target.closest('a[href]')
+    if (!link || !sidebarNav.contains(link)) return
+
+    const sectionId = extractSectionIdFromHref(link.getAttribute('href'))
+    if (sectionId) setActiveLink(sectionId)
+  }
+
+  sidebarNav.addEventListener('click', handleNavClick)
+  window.addEventListener('scroll', requestSync, { passive: true })
+  window.addEventListener('resize', requestSync)
+
+  requestSync()
+  window.setTimeout(requestSync, 140)
+
+  return () => {
+    sidebarNav.removeEventListener('click', handleNavClick)
+    window.removeEventListener('scroll', requestSync)
+    window.removeEventListener('resize', requestSync)
+    if (frameId !== null) window.cancelAnimationFrame(frameId)
+  }
+}
+
+const enhancePage = () => {
+  teardownNavigationTracking()
+  teardownNavigationTracking = () => {}
+
+  const section = document.querySelector('.markdown-section')
+  const content = document.querySelector('.content')
+  const sidebar = document.querySelector('.sidebar')
+  if (!section) return
+
+  if (content) {
+    content.id = 'main-content'
+    content.setAttribute('role', 'main')
+    content.setAttribute('tabindex', '-1')
+  }
+
+  if (sidebar) {
+    sidebar.setAttribute('role', 'navigation')
+    sidebar.setAttribute('aria-label', 'Primary navigation')
+  }
+
+  decorateHero(section)
+  decorateUseCases(section)
+  decorateCodeBlocks(section)
+  decorateTables(section)
+  revealContent(section)
+  disableDocsifyDefaultScrollSpy(section)
+  teardownNavigationTracking = setupNavigationTracking(section)
+}
+
+window.$docsify = {
+  name: '@microlink/google',
+  repo: 'microlinkhq/google',
+  logo: '/static/banner.png',
+  externalLinkRel: 'noopener noreferrer',
+  subMaxLevel: 2,
+  auto2top: true,
+  maxLevel: 3,
+  plugins: [
+    hook => {
+      hook.doneEach(() => {
+        enhancePage()
+        const appLink = document.querySelector('.app-name-link')
+        if (appLink && !appLink.dataset.bound) {
+          appLink.dataset.bound = 'true'
+          appLink.onclick = event => {
+            event.preventDefault()
+            const shouldReduceMotion = window.matchMedia(
+              '(prefers-reduced-motion: reduce)'
+            ).matches
+            window.scrollTo({
+              top: 0,
+              behavior: shouldReduceMotion ? 'auto' : 'smooth'
+            })
+          }
+        }
+      })
+    }
+  ]
+}

package/src/main.mjs

@@ -0,0 +1,7 @@
+import createGoogleClient from './index.js'
+
+export const buildPath = createGoogleClient.buildPath
+export const buildUrl = createGoogleClient.buildUrl
+export const DOMAIN = createGoogleClient.DOMAIN
+
+export default createGoogleClient

package/README.md

@@ -1,163 +0,0 @@
-# @microlink/google
-
-![Last version](https://img.shields.io/github/tag/microlinkhq/microlink-google.svg?style=flat-square)
-[![Coverage Status](https://img.shields.io/coveralls/microlinkhq/microlink-google.svg?style=flat-square)](https://coveralls.io/github/microlinkhq/microlink-google)
-[![NPM Status](https://img.shields.io/npm/dm/@microlink/google.svg?style=flat-square)](https://www.npmjs.org/package/@microlink/google)
-
-> Google search results via [Microlink API](https://microlink.io).
-
-## Install
-
-```bash
-npm install @microlink/google
-```
-
-## Usage
-
-Create a client by passing your configuration, then call it with a search query:
-
-```js
-const google = require('@microlink/google')({
-  apiKey: 'YOUR_API_KEY',
-})
-
-const page = await google('Lotus Elise S2')
-
-for (const result of page.results) {
-  console.log(result.title)       // "Lotus Elise - Wikipedia"
-  console.log(result.url)         // "https://en.wikipedia.org/wiki/Lotus_Elise"
-  console.log(result.description) // "The Lotus Elise is a two-seat, ..."
-}
-```
-
-Each result has a lazy `.html()` method that fetches the full page HTML on demand:
-
-```js
-const html = await page.results[0].html()
-```
-
-The SERP page HTML is also available:
-
-```js
-const serpHtml = await page.html()
-```
-
-### Pagination
-
-Results are paginated. Call `.next()` to get the next page:
-
-```js
-const firstPage = await google('node.js frameworks')
-const secondPage = await firstPage.next()
-const thirdPage = await secondPage.next()
-```
-
-The offset is calculated automatically from the number of results in each page.
-
-## API
-
-### google(query, [options])
-
-#### query
-
-*Required*<br>
-Type: `string`
-
-The search query. Spaces are supported naturally. You can use [Google search operators](https://support.google.com/websearch/answer/2466433) for advanced filtering:
-
-```js
-// Only PDF files
-const page = await google('annual report filetype:pdf')
-
-// Results from a specific site
-const page = await google('security updates site:github.com')
-
-// Exclude a site
-const page = await google('node.js tutorials -site:w3schools.com')
-
-// Exact phrase
-const page = await google('"machine learning" site:arxiv.org')
-
-// Combine operators
-const page = await google('site:reddit.com intitle:best "mechanical keyboard"')
-```
-
-#### options
-
-##### limit
-
-Type: `number`
-
-Maximum number of results to return per page.
-
-##### lang
-
-Type: `string`
-
-Country perspective for ranking results ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, e.g. `'us'`, `'de'`, `'jp'`).
-
-```js
-const page = await google('recetas de pasta', { lang: 'es' })
-```
-
-##### device
-
-Type: `string`<br>
-Values: `'desktop'`, `'mobile'`
-Default: `'desktop'`
-
-Device type for SERP layout. Affects how Google renders and ranks results.
-
-```js
-const page = await google('best restaurants', { device: 'mobile' })
-```
-
-##### period
-
-Type: `string`<br>
-Values: `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`
-
-Time-based filter for results.
-
-```js
-const page = await google('tech news', { period: 'week' })
-```
-
-##### domain
-
-Type: `string`<br>
-Default: `'google.com'`
-
-Regional Google domain to query (e.g. `'google.de'`, `'google.co.uk'`, `'google.com.tr'`).
-
-```js
-const page = await google('restaurants', { domain: 'google.co.uk' })
-```
-
-### Page object
-
-The return value from a search call is a page object with the following properties:
-
-| Property | Type | Description |
-|---|---|---|
-| `results` | `Array<Result>` | Array of search results |
-| `html()` | `() => Promise<string>` | Returns the raw SERP HTML |
-| `next()` | `() => Promise<Page>` | Fetches the next page of results |
-
-### Result object
-
-Each result in the `results` array has:
-
-| Property | Type | Description |
-|---|---|---|
-| `title` | `string` | Page title |
-| `url` | `string` | Direct URL to the page |
-| `description` | `string` | Result snippet text |
-| `html()` | `() => Promise<string>` | Fetches the full HTML of this result's URL via Microlink |
-
-## License
-
-**@microlink/google** © [microlink.io](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/microlink-google/blob/master/LICENSE.md) License.<br>
-Authored and maintained by [microlink.io](https://microlink.io) with help from [contributors](https://github.com/microlinkhq/microlink-google/contributors).
-
-> [microlink.io](https://microlink.io) · GitHub [microlink.io](https://github.com/microlinkhq) · Twitter [@microlinkhq](https://twitter.com/microlinkhq)