@unavatar/core 3.25.5 → 3.25.7

package/README.md

@@ -4,6 +4,9 @@
 
 - [Introduction](#introduction)
 - [Quick start](#quick-start)
+- [Attribution](#attribution)
+  - [How to add attribution](#how-to-add-attribution)
+  - [Remove attribution](#remove-attribution)
 - [Authentication](#authentication)
 - [Pricing](#pricing)
 - [Cache](#cache)
@@ -73,18 +76,70 @@ It's proudly powered by [microlink.io](https://microlink.io/), the headless brow
 
 ## Quick start
 
-The service is exposed in **unavatar.io** via provider endpoints:
+The service is exposed in **unavatar.io** via endpoints.
 
-- an **email (auto-detect)**: [unavatar.io/hello@microlink.io](https://unavatar.io/hello@microlink.io) — tries Gravatar, then GitHub
-- an **email** via Gravatar: [unavatar.io/gravatar/hello@microlink.io](https://unavatar.io/gravatar/hello@microlink.io)
-- a **Gravatar SHA-256** (same email, pre-hashed): [unavatar.io/gravatar/b1f507c7a29adfa84eaa521036774b0577c58f23f2f3f42e068d6ac256cffae2](https://unavatar.io/gravatar/b1f507c7a29adfa84eaa521036774b0577c58f23f2f3f42e068d6ac256cffae2)
-- an **email** via GitHub: [unavatar.io/github/sindresorhus@gmail.com](https://unavatar.io/github/sindresorhus@gmail.com)
+An endpoint determines how the avatar is looked up and what parameters are required.
+
+For example, you can get an avatar for:
+
+- an **email**: [unavatar.io/email/hello@microlink.io](https://unavatar.io/email/hello@microlink.io)
 - an **username**: [unavatar.io/github/kikobeats](https://unavatar.io/github/kikobeats)
-- a **domain**: [unavatar.io/google/reddit.com](https://unavatar.io/google/reddit.com)
+- a **domain**: [unavatar.io/domain/reddit.com](https://unavatar.io/domain/reddit.com)
+
+Read [providers](https://unavatar.io/docs#providers) to know more. Each provider can accept different parameters.
+
+## Attribution
+
+Free plans require attribution. Upgrade to any paid plan to remove this requirement.
+
+Attribution ensures proper domain verification and helps us keep unavatar.io free for the community.
+
+Your attribution link:
+
+- Must be on your production site (not staging or localhost).
+- Must be publicly accessible and viewable in browsers.
+- Must not use rel="nofollow", redirects, or obfuscation.
+
+### How to add attribution
+
+Add this link on any page or surface displaying unavatar.io avatars:
+
+```html
+[Avatars provided by Unavatar](https://unavatar.io)
+```
+
+**Example**
+
+```html
+
+  <img src="https://unavatar.io/github/kikobeats" alt="Kiko" />
+  <img src="https://unavatar.io/x/josebaseba" alt="Joseba" />
+
+<p class="attribution">
+  [Avatars provided by Unavatar](https://unavatar.io)
+</p>
+```
+
+**Valid placements**
+
+Site footer, about page, credits page, or any page that renders avatars.
+
+**Mobile apps and non-web products**
+
+If avatars are displayed in a mobile app, desktop app, browser extension, email, or any non-web surface, add the attribution link on your app's marketing site, app store listing description, or credits screen.
+
+**Requirements for attribution to be valid**
+
+We reserve the right to revoke free-tier access for any website or product that does not comply with the attribution requirements described in this document:
+
+- Double-check the href. It must point to [https://unavatar.io](https://unavatar.io/) directly — no redirects, no URL shorteners, no tracking wrappers.
+- Make sure it's crawlable. The link must be present in the rendered HTML and not blocked by robots.txt, authentication, or region gating.
+- Avoid nofollow or noindex. We need a standard, followable link.
+- target="\_blank" is allowed.
 
-Use `/:provider/:key` for provider-specific lookups, or pass an email as the only path segment for automatic resolution. You can read more in [Email avatars](https://unavatar.io/email) and [providers](https://unavatar.io/docs#providers).
+### Remove attribution
 
-For **Gravatar**, `key` can be a plain email or a precomputed identifier: emails are trimmed, lowercased, and hashed with **SHA-256** before calling Gravatar. Values that already look like a **64-character hex SHA-256** or **32-character hex MD5** are sent as-is (hex is normalized to lowercase).
+Attribution is only required on the free plan. [Upgrade to the PRO plan](https://unavatar.io/checkout) to remove the requirement.
 
 ## Authentication
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@unavatar/core",
   "description": "Get unified user avatar from social networks, including Instagram, SoundCloud, Telegram, Twitter, YouTube & more.",
   "homepage": "https://unavatar.io",
-  "version": "3.25.5",
+  "version": "3.25.7",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -206,6 +206,7 @@
   },
   "nano-staged": {
     "*.js": [
+      "npx -y @kikobeats/prettier-standard",
       "standard --fix"
     ],
     "package.json": [

package/src/index.js

@@ -2,7 +2,12 @@
 
 const DEFAULTS = require('./constant')
 
-module.exports = ({ constants: userConstants, redis, onFetchHTML } = {}) => {
+module.exports = ({
+  constants: userConstants,
+  redis,
+  onFetchHTML,
+  userAgent
+} = {}) => {
   const constants = { ...DEFAULTS, ...userConstants }
 
   if (userConstants?.REQUEST_TIMEOUT && !userConstants?.PROXY_TIMEOUT) {
@@ -33,7 +38,8 @@ module.exports = ({ constants: userConstants, redis, onFetchHTML } = {}) => {
     require('./util/html-provider')({
       ...constants,
       getHTML,
-      onFetchHTML
+      onFetchHTML,
+      userAgent
     })
 
   const providerCtx = {
@@ -61,7 +67,8 @@ module.exports = ({ constants: userConstants, redis, onFetchHTML } = {}) => {
     unavatar[name] = input => getAvatar(providers[name], name, input, {})
   })
 
-  const createTypedAutoResolver = inputType => input => auto(inputType)(input, {})
+  const createTypedAutoResolver = inputType => input =>
+    auto(inputType)(input, {})
 
   unavatar.email = createTypedAutoResolver('email')
   unavatar.domain = createTypedAutoResolver('domain')

package/src/util/html-provider.js

@@ -4,7 +4,6 @@ const { normalizeUrl } = require('@metascraper/helpers')
 const debug = require('debug-logfmt')('html-provider')
 const isAntibot = require('is-antibot')
 
-const randomCrawlerAgent = require('./crawler-agent')
 const getOgImage = require('./get-og-image')
 const httpStatus = require('./http-status')
 const ExtendableError = require('./error')
@@ -34,7 +33,12 @@ const createErrorCause = ({ html, headers, statusCode }) => ({
   statusCode
 })
 
-module.exports = ({ PROXY_TIMEOUT, getHTML, onFetchHTML }) => {
+module.exports = ({
+  PROXY_TIMEOUT,
+  getHTML,
+  onFetchHTML,
+  userAgent = require('./crawler-agent')
+}) => {
   /**
    * @param {object} opts
    * @param {string} opts.name - Provider identifier used in logs and metrics.
@@ -55,13 +59,13 @@ module.exports = ({ PROXY_TIMEOUT, getHTML, onFetchHTML }) => {
         const defaultOpts = {
           ...providerOpts,
           headers: {
-            'user-agent': randomCrawlerAgent(),
+            'user-agent': userAgent({ provider: name }),
             ...providerOpts.headers
           },
           timeout: PROXY_TIMEOUT
         }
         const fetchOpts = { ...defaultOpts, ...gotOpts }
-        const userAgent = fetchOpts.headers['user-agent']
+        const resolvedUserAgent = fetchOpts.headers['user-agent']
         const tier = fetchOpts.tier ?? 'origin'
 
         const log = debug.duration({ provider: name, input, providerUrl, tier })
@@ -151,7 +155,7 @@ module.exports = ({ PROXY_TIMEOUT, getHTML, onFetchHTML }) => {
             statusCode,
             status: 'blocked',
             antibot: antibotProvider ?? undefined,
-            userAgent
+            userAgent: resolvedUserAgent
           })
 
           throw error
@@ -167,7 +171,7 @@ module.exports = ({ PROXY_TIMEOUT, getHTML, onFetchHTML }) => {
         log.error({
           statusCode,
           antibot: antibotProvider ?? undefined,
-          userAgent
+          userAgent: resolvedUserAgent
         })
 
         throw error