@unavatar/core 3.25.6 → 3.26.0

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)
@@ -62,29 +65,95 @@
 - [Response Format](#response-format)
 - [Response Headers](#response-headers)
 - [Response Errors](#response-errors)
+- [Contact](#contact)
 
 ---
 
+Last updated on April 29, 2026
+
 ## Introduction
 
 Welcome to **unavatar.io**, the ultimate avatar service that offers everything you need to easily retrieve user avatars:
 
+- **Versatile**: A wide range of platforms and services including [TikTok](https://unavatar.io/docs#tiktok), [Instagram](https://unavatar.io/docs#instagram), [YouTube](https://unavatar.io/docs#youtube), [X/Twitter](https://unavatar.io/docs#xtwitter), [Gravatar](https://unavatar.io/docs#gravatar), etc., meaning you can rule all of them just querying against unavatar.
+
+- **Speed**: Designed to be fast and efficient with a 91% cache hit rate, serving 12.5 TB of data across 382M requests.
+
+- **Optimize**: All the images are not only compressed on-the-fly to reduce their size and save bandwidth, but also optimized to maintain a high-quality ratio. They are ready for immediate use, enhancing the overall optimization of your website or application.
+
+- **Integration**: The service seamlessly incorporates into your current applications or websites with ease. We offer straightforward documentation and comprehensive support to ensure a quick and effortless onboarding experience.
+
 It's proudly powered by [microlink.io](https://microlink.io/), the headless browser API that handles all the heavy lifting behind the scenes to ensure your avatars are always ready.
 
 ## 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)
+```
 
-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).
+**Example**
 
-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).
+```html
+
+  ![Kiko](https://unavatar.io/github/kikobeats)
+
+  ![Joseba](https://unavatar.io/x/josebaseba)
+
+<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.
+
+### Remove attribution
+
+Attribution is only required on the free plan. [Upgrade to the PRO plan](https://unavatar.io/checkout) to remove the requirement.
 
 ## Authentication
 
@@ -98,9 +167,13 @@ curl "https://unavatar.io/github/kikobeats" -H "x-api-key: YOUR_API_KEY"
 
 ```javascript
 await fetch('https://unavatar.io/github/kikobeats', {
+
   headers: {
+
     'x-api-key': 'YOUR_API_KEY'
+
   }
+
 })
 ```
 
@@ -108,8 +181,11 @@ await fetch('https://unavatar.io/github/kikobeats', {
 import requests
 
 response = requests.get(
+
   'https://unavatar.io/github/kikobeats',
+
   headers={'x-api-key': 'YOUR_API_KEY'}
+
 )
 ```
 
@@ -119,24 +195,33 @@ package main
 import "net/http"
 
 func main() {
+
   req, _ := http.NewRequest("GET", "https://unavatar.io/github/kikobeats", nil)
+
   req.Header.Set("x-api-key", "YOUR_API_KEY")
 
   resp, _ := http.DefaultClient.Do(req)
+
   defer resp.Body.Close()
+
 }
 ```
 
 ```ruby
 require 'net/http'
+
 require 'uri'
 
 uri = URI('https://unavatar.io/github/kikobeats')
+
 request = Net::HTTP::Get.new(uri)
+
 request['x-api-key'] = 'YOUR_API_KEY'
 
 response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+
   http.request(request)
+
 end
 ```
 
@@ -144,11 +229,15 @@ end
 $ch = curl_init('https://unavatar.io/github/kikobeats');
 
 curl_setopt($ch, CURLOPT_HTTPHEADER, [
+
   'x-api-key: YOUR_API_KEY',
+
 ]);
+
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
 $response = curl_exec($ch);
+
 curl_close($ch);
 ```
 
@@ -166,7 +255,9 @@ Rate limit status can be verified using these response headers:
 $ curl -I https://unavatar.io/github/kikobeats
 
 x-rate-limit-limit: 25
+
 x-rate-limit-remaining: 24
+
 x-rate-limit-reset: 1744243200
 ```
 
@@ -196,7 +287,9 @@ The proxy tier used is returned in the `x-proxy-tier` response header, and the t
 $ curl -I -H "x-api-key: YOUR_API_KEY" https://unavatar.io/instagram/kikobeats
 
 x-pricing-tier: pro
+
 x-proxy-tier: origin
+
 x-unavatar-cost: 1
 ```
 
@@ -230,6 +323,7 @@ To check the cache status in real requests, inspect these response headers:
 $ curl -I -H "x-api-key: YOUR_API_KEY" "https://unavatar.io/github/kikobeats?ttl=1h"
 
 cache-control: public, max-age=3600
+
 x-cache-status: HIT
 ```
 
@@ -469,6 +563,10 @@ Available inputs:
 - SHA-256 hash, e.g., [unavatar.io/gravatar/b1f507c7a29adfa84eaa521036774b0577c58f23f2f3f42e068d6ac256cffae2](https://unavatar.io/gravatar/b1f507c7a29adfa84eaa521036774b0577c58f23f2f3f42e068d6ac256cffae2)
 - MD5 hash, e.g., [unavatar.io/gravatar/3f293df98a473eae038deabe430a1e30](https://unavatar.io/gravatar/3f293df98a473eae038deabe430a1e30)
 
+When you pass an email address directly in the URL, it is visible in plain text — both in server logs and to any intermediary that inspects the request.
+
+To avoid this, pass a pre-computed `MD5` or `SHA256` hash of the email instead. Unavatar detects the hash automatically and routes it to Gravatar, which natively supports both hash formats.
+
 ### Instagram
 
 Get any Instagram user's profile picture by their username. No authentication or API tokens needed — just pass the username.
@@ -725,11 +823,17 @@ These headers help you understand pricing, limits, and request diagnostics.
 $ curl -I -H "x-api-key: YOUR_API_KEY" https://unavatar.io/github/kikobeats
 
 x-pricing-tier: pro
+
 x-timestamp: 1744209600
+
 x-unavatar-cost: 1
+
 x-proxy-tier: origin
+
 x-rate-limit-limit: 50
+
 x-rate-limit-remaining: 49
+
 x-rate-limit-reset: 1744243200
 ```
 
@@ -770,4 +874,4 @@ Expected errors are known operational cases returned with stable codes.
 
 ## Contact
 
-If you have any suggestion or bug to report, please contact to ust mailing to [hello@unavatar.io](mailto:hello@unavatar.io).
+If you have a suggestion or need to report a bug, contact us at <hello@unavatar.io>.

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.6",
+  "version": "3.26.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -157,7 +157,7 @@
   "devDependencies": {
     "@commitlint/cli": "latest",
     "@commitlint/config-conventional": "latest",
-    "ava": "latest",
+    "ava": "7",
     "c8": "latest",
     "cheerio": "latest",
     "ci-publish": "latest",

package/src/providers/index.js

@@ -35,6 +35,7 @@ const providersBy = {
     'steam',
     'substack',
     'telegram',
+    'thingiverse',
     'threads',
     'tiktok',
     'tumblr',
@@ -85,6 +86,7 @@ module.exports = ctx => {
     steam: require('./steam')(ctx),
     substack: require('./substack')(ctx),
     telegram: require('./telegram')(ctx),
+    thingiverse: require('./thingiverse')(ctx),
     threads: require('./threads')(ctx),
     tiktok: require('./tiktok')(ctx),
     tumblr: require('./tumblr')(ctx),

package/src/providers/thingiverse.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const getProfileUrl = input => `https://www.thingiverse.com/${input}`
+
+const getAvatarUrl = ({ getOgImage, $ }) =>
+  new URL(getOgImage($)).searchParams.get('url')
+
+module.exports = ({ createHtmlProvider, getOgImage }) =>
+  createHtmlProvider({
+    name: 'thingiverse',
+    url: getProfileUrl,
+    getter: $ => getAvatarUrl({ getOgImage, $ })
+  })
+
+module.exports.getAvatarUrl = getProfileUrl
+module.exports.getAvatarUrlFromMarkup = getAvatarUrl