@microlink/google 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2026 microlink.io <hello@microlink.io> (microlink.io)
+
+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,163 @@
+# @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)

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@microlink/google",
+  "description": "Google search integration for Microlink",
+  "homepage": "https://github.com/microlinkhq/microlink-google",
+  "version": "0.0.0",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "author": {
+    "email": "hello@microlink.io",
+    "name": "microlink.io",
+    "url": "https://microlink.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microlinkhq/microlink-google.git"
+  },
+  "bugs": {
+    "url": "https://github.com/microlinkhq/microlink-google/issues"
+  },
+  "keywords": [
+    "google",
+    "integration",
+    "microlink",
+    "search",
+    "search",
+    "serp"
+  ],
+  "dependencies": {
+    "@microlink/mql": "latest"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "latest",
+    "@commitlint/config-conventional": "latest",
+    "@ksmithut/prettier-standard": "latest",
+    "ava": "latest",
+    "c8": "latest",
+    "finepack": "latest",
+    "git-authors-cli": "latest",
+    "github-generate-release": "latest",
+    "nano-staged": "latest",
+    "simple-git-hooks": "latest",
+    "standard": "latest",
+    "standard-markdown": "latest",
+    "standard-version": "latest"
+  },
+  "engines": {
+    "node": ">= 24"
+  },
+  "files": [
+    "src"
+  ],
+  "license": "MIT",
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ],
+    "rules": {
+      "body-max-line-length": [
+        0
+      ]
+    }
+  },
+  "nano-staged": {
+    "*.js": [
+      "prettier-standard",
+      "standard --fix"
+    ],
+    "*.md": [
+      "standard-markdown"
+    ],
+    "package.json": [
+      "finepack"
+    ]
+  },
+  "simple-git-hooks": {
+    "commit-msg": "npx commitlint --edit",
+    "pre-commit": "npx nano-staged"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules",
+    "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
+    "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
+    "lint": "standard-markdown README.md && standard",
+    "postrelease": "pnpm release:tags && pnpm release:github && pnpm publish",
+    "pretest": "pnpm lint",
+    "release": "standard-version -a",
+    "release:github": "github-generate-release",
+    "release:tags": "git push --follow-tags origin HEAD:master",
+    "test": "c8 ava"
+  }
+}

package/src/index.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const mql = require('@microlink/mql')
+
+const DOMAIN = 'microlink.google'
+
+const buildPath = (query, limit, lang) =>
+  [encodeURIComponent(query).replace(/%20/g, '+'), limit, lang]
+    .filter(v => v !== undefined)
+    .join('/')
+
+const buildUrl = (query, { limit, lang, device, period, domain } = {}) => {
+  const url = new URL(`https://${DOMAIN}/${buildPath(query, limit, lang)}`)
+  if (device) url.searchParams.set('device', device)
+  if (period) url.searchParams.set('period', period)
+  if (domain) url.searchParams.set('domain', domain)
+  return url
+}
+
+const fetchPage = async (url, mqlOpts, offset) => {
+  url.searchParams.set('start', String(offset))
+  const { data } = await mql(url.toString(), mqlOpts)
+  const { results, html } = data
+
+  return {
+    html: () => Promise.resolve(html),
+    results: results.map(result => ({
+      ...result,
+      html: async () => {
+        const { data } = await mql(result.url, {
+          ...mqlOpts,
+          data: { content: { attr: 'html' } }
+        })
+        return data.content
+      }
+    })),
+    next: () =>
+      fetchPage(new URL(url.toString()), mqlOpts, offset + results.length)
+  }
+}
+
+module.exports = ctxOpts => {
+  return async (
+    query,
+    { limit, lang, device, period, domain, ...opts } = {}
+  ) => {
+    const url = buildUrl(query, { limit, lang, device, period, domain })
+    return fetchPage(url, { ...ctxOpts, ...opts }, 0)
+  }
+}
+
+module.exports.buildPath = buildPath
+module.exports.buildUrl = buildUrl
+module.exports.DOMAIN = DOMAIN