From 5a22fc33f68b73d990bc7027baad03e138b50a69 Mon Sep 17 00:00:00 2001
From: Kiko Beats <josefrancisco.verdu@gmail.com>
Date: Thu, 9 Nov 2023 13:07:42 +0100
Subject: [PATCH] feat(logo-favicon): granular control (#667)

---
 package.json                                  |   2 +-
 packages/metascraper-logo-favicon/README.md   |  21 +++++
 packages/metascraper-logo-favicon/index.js    |  85 ++++++++++++------
 .../metascraper-logo-favicon/test/favicon.js  |  10 +++
 .../metascraper-logo-favicon/test/get-logo.js |  17 ++++
 .../metascraper-logo-favicon/test/google.js   |  29 ++++++
 .../test/root-favicon.js                      |  42 +++++++++
 .../test/snapshots/index.js.md                |   2 +-
 .../test/snapshots/index.js.snap              | Bin 727 -> 725 bytes
 .../test/snapshots/index.js.md                |   2 +-
 .../test/snapshots/index.js.snap              | Bin 1387 -> 1389 bytes
 11 files changed, 180 insertions(+), 30 deletions(-)
 create mode 100644 packages/metascraper-logo-favicon/test/favicon.js
 create mode 100644 packages/metascraper-logo-favicon/test/get-logo.js
 create mode 100644 packages/metascraper-logo-favicon/test/google.js
 create mode 100644 packages/metascraper-logo-favicon/test/root-favicon.js

diff --git a/package.json b/package.json
index 11f59d9a5..33a86647b 100644
--- a/package.json
+++ b/package.json
@@ -178,7 +178,7 @@
       "standard-markdown"
     ],
     "package.json": [
-      "finepack --sort-ignore-object-at ava"
+      "finepack"
     ]
   },
   "simple-git-hooks": {
diff --git a/packages/metascraper-logo-favicon/README.md b/packages/metascraper-logo-favicon/README.md
index 17f802f9b..38d27ad6e 100644
--- a/packages/metascraper-logo-favicon/README.md
+++ b/packages/metascraper-logo-favicon/README.md
@@ -20,6 +20,27 @@ $ npm install metascraper-logo-favicon --save
 
 #### options
 
+##### google
+
+Type: `boolean`<br>
+Default: `true`
+
+It enables logo resolution using Google API.
+
+##### favicon
+
+Type: `boolean`<br>
+Default: `true`
+
+It tries to resolve `favicon.ico` of the url.
+
+##### rootFavicon
+
+Type: `boolean`|`regexp`<br>
+Default: `true`
+
+It tries to resolve `favicon.ico` of the url when the URL is a subdomain.
+
 ##### pickFn
 
 Type: `function`
diff --git a/packages/metascraper-logo-favicon/index.js b/packages/metascraper-logo-favicon/index.js
index 2e2bdbe99..c183cdd5c 100644
--- a/packages/metascraper-logo-favicon/index.js
+++ b/packages/metascraper-logo-favicon/index.js
@@ -105,38 +105,69 @@ const pickBiggerSize = sizes => {
 pickBiggerSize.sortBySize = collection =>
   orderBy(collection, ['size.priority'], ['desc'])
 
-const createGetLogo = ({ gotOpts, keyvOpts }) => {
-  const getLogo = async url => {
-    const faviconUrl = logo('/favicon.ico', { url })
-    if (!faviconUrl) return
+const favicon = async (url, { gotOpts } = {}) => {
+  const faviconUrl = logo('/favicon.ico', { url })
+  if (!faviconUrl) return undefined
+  const response = await reachableUrl(faviconUrl, gotOpts)
+  return reachableUrl.isReachable(response) &&
+    response.headers['content-type']?.startsWith('image')
+    ? faviconUrl
+    : undefined
+}
 
-    let response = await reachableUrl(faviconUrl, gotOpts)
+const google = async (url, { gotOpts } = {}) => {
+  const response = await reachableUrl(google.url(url), gotOpts)
+  return reachableUrl.isReachable(response) ? response.url : undefined
+}
 
-    if (
-      reachableUrl.isReachable(response) &&
-      response.headers['content-type']?.startsWith('image')
-    ) {
-      return faviconUrl
-    }
+google.url = (url, size = 128) =>
+  `https://www.google.com/s2/favicons?domain_url=${url}&sz=${size}`
 
-    response = await reachableUrl(
-      `https://www.google.com/s2/favicons?domain_url=${url}&sz=128`,
-      gotOpts
+const createGetLogo = ({ withGoogle, withFavicon, gotOpts, keyvOpts }) => {
+  const getLogo = async url => {
+    const providers = [withFavicon && favicon, withGoogle && google].filter(
+      Boolean
     )
 
-    return reachableUrl.isReachable(response) ? response.url : undefined
+    for (const provider of providers) {
+      const logoUrl = await provider(url, { gotOpts })
+      if (logoUrl) return logoUrl
+    }
   }
 
-  return memoize(getLogo, keyvOpts, {
+  const fn = memoize(getLogo, keyvOpts, {
     value: value => (value === undefined ? null : value)
   })
+
+  return (...args) =>
+    fn(...args).then(value => (value === null ? undefined : value))
 }
 
-const castNull = value => (value === null ? undefined : value)
+const createRootFavicon = ({ getLogo, withRootFavicon = true } = {}) => {
+  if (withRootFavicon === false) return undefined
+  return ({ url }) => {
+    const urlObj = new URL(url)
+    const domain = parseUrl(url).domain
+
+    if (withRootFavicon instanceof RegExp && withRootFavicon.test(domain)) {
+      return undefined
+    }
 
-module.exports = ({ gotOpts, keyvOpts, pickFn = pickBiggerSize } = {}) => {
-  const getLogo = createGetLogo({ gotOpts, keyvOpts })
+    urlObj.hostname = domain
+    return getLogo(normalizeUrl(urlObj))
+  }
+}
 
+module.exports = ({
+  google: withGoogle = true,
+  favicon: withFavicon = true,
+  rootFavicon: withRootFavicon = true,
+  gotOpts,
+  keyvOpts,
+  pickFn = pickBiggerSize
+} = {}) => {
+  const getLogo = createGetLogo({ withGoogle, withFavicon, gotOpts, keyvOpts })
+  const rootFavicon = createRootFavicon({ getLogo, withRootFavicon })
   return {
     logo: [
       toUrl($ => {
@@ -144,13 +175,13 @@ module.exports = ({ gotOpts, keyvOpts, pickFn = pickBiggerSize } = {}) => {
         const size = pickFn(sizes, pickBiggerSize)
         return get(size, 'url')
       }),
-      async ({ url }) => castNull(await getLogo(normalizeUrl(url))),
-      async ({ url }) => {
-        const urlObj = new URL(url)
-        urlObj.hostname = parseUrl(url).domain
-        const result = await getLogo(normalizeUrl(urlObj))
-        return castNull(result)
-      }
-    ]
+      ({ url }) => getLogo(normalizeUrl(url)),
+      rootFavicon
+    ].filter(Boolean)
   }
 }
+
+module.exports.favicon = favicon
+module.exports.google = google
+module.exports.createRootFavicon = createRootFavicon
+module.exports.createGetLogo = createGetLogo
diff --git a/packages/metascraper-logo-favicon/test/favicon.js b/packages/metascraper-logo-favicon/test/favicon.js
new file mode 100644
index 000000000..f56b462b1
--- /dev/null
+++ b/packages/metascraper-logo-favicon/test/favicon.js
@@ -0,0 +1,10 @@
+'use strict'
+
+const test = require('ava')
+
+const { favicon } = require('..')
+
+test('with { contentType: \'image/vnd.microsoft.icon\' }', async t => {
+  const url = 'https://microlink.io/'
+  t.is(await favicon(url), 'https://microlink.io/favicon.ico')
+})
diff --git a/packages/metascraper-logo-favicon/test/get-logo.js b/packages/metascraper-logo-favicon/test/get-logo.js
new file mode 100644
index 000000000..8f88b6038
--- /dev/null
+++ b/packages/metascraper-logo-favicon/test/get-logo.js
@@ -0,0 +1,17 @@
+'use strict'
+
+const test = require('ava')
+
+const { createGetLogo } = require('..')
+
+test('serialize null correctly', async t => {
+  const cache = new Map()
+  const keyvOpts = { store: cache }
+  const getLogo = createGetLogo({
+    keyvOpts,
+    withGoogle: false,
+    withFavicon: false
+  })
+  t.is(await getLogo('https://example.com'), undefined)
+  t.is(JSON.parse(cache.get('https://example.com')).value, null)
+})
diff --git a/packages/metascraper-logo-favicon/test/google.js b/packages/metascraper-logo-favicon/test/google.js
new file mode 100644
index 000000000..da3b2a960
--- /dev/null
+++ b/packages/metascraper-logo-favicon/test/google.js
@@ -0,0 +1,29 @@
+'use strict'
+
+const test = require('ava')
+const got = require('got')
+
+const { google } = require('..')
+
+test('return undefined under no logo', async t => {
+  const url = 'https://idontexist.lol'
+  t.is(await google(url), undefined)
+})
+
+test('return logo when URL is reachable', async t => {
+  const url = 'https://microlink.io/'
+  const logoUrl = await google(url)
+  t.true(typeof logoUrl === 'string')
+
+  const fallbackUrl = google.url()
+  const [logo, fallback] = await Promise.all(
+    [logoUrl, fallbackUrl].map(url =>
+      got(url, {
+        responseType: 'buffer',
+        resolveBodyOnly: true,
+        throwHttpErrors: false
+      })
+    )
+  )
+  t.true(logo.length !== fallback.length)
+})
diff --git a/packages/metascraper-logo-favicon/test/root-favicon.js b/packages/metascraper-logo-favicon/test/root-favicon.js
new file mode 100644
index 000000000..fedf04989
--- /dev/null
+++ b/packages/metascraper-logo-favicon/test/root-favicon.js
@@ -0,0 +1,42 @@
+'use strict'
+
+const test = require('ava')
+const got = require('got')
+
+const { createGetLogo, createRootFavicon, google } = require('..')
+
+test('enable it by default', async t => {
+  const getLogo = createGetLogo({ withGoogle: true, withFavicon: true })
+  const rootFavicon = createRootFavicon({ getLogo })
+  const url = 'https://geolocation-indol.vercel.app/'
+  const logoUrl = await rootFavicon({ url })
+  const domainLogoUrl = google.url('https://vercel.app/')
+
+  const [logo, domainLogo] = await Promise.all(
+    [logoUrl, domainLogoUrl].map(url =>
+      got(url, {
+        responseType: 'buffer',
+        resolveBodyOnly: true,
+        throwHttpErrors: false
+      })
+    )
+  )
+
+  t.is(logo.length, domainLogo.length)
+})
+
+test('exclude certain subdomains', async t => {
+  const getLogo = createGetLogo({ withGoogle: true, withFavicon: true })
+  const rootFavicon = createRootFavicon({
+    getLogo,
+    withRootFavicon: /^vercel\.app/
+  })
+  const url = 'https://geolocation-indol.vercel.app/'
+  const logoUrl = await rootFavicon({ url })
+  t.is(logoUrl, undefined)
+})
+
+test('disable it when \'{ withRootFavicon: false}\'', async t => {
+  const rootFavicon = createRootFavicon({ withRootFavicon: false })
+  t.is(rootFavicon, undefined)
+})
diff --git a/packages/metascraper-manifest/test/snapshots/index.js.md b/packages/metascraper-manifest/test/snapshots/index.js.md
index f01812f93..3d6746c66 100644
--- a/packages/metascraper-manifest/test/snapshots/index.js.md
+++ b/packages/metascraper-manifest/test/snapshots/index.js.md
@@ -88,5 +88,5 @@ Generated by [AVA](https://avajs.dev).
     {
       description: 'Get breaking news, politics, trending music, world events, sports scores, and the latest global news stories as they unfold - all with less data.',
       lang: null,
-      publisher: 'Twitter',
+      publisher: 'X',
     }
diff --git a/packages/metascraper-manifest/test/snapshots/index.js.snap b/packages/metascraper-manifest/test/snapshots/index.js.snap
index d89a52807d9ccdf3614b71e23aa73cb300b4f7f7..4a9e4fea6f92cf577d090dfcd15aa62d63c7797d 100644
GIT binary patch
literal 725
zcmV;`0xJDMRzV<BZeeh9Xm4~Nb~6eC0QPuAUPhdiZnp4f6Nfp+n768zLRjeWflI40
z(X}QnK_80<00000000Bsmc4G&KoG~hxqJXoL?U>AEuf3fxg)udh=LA^NFctHRA_CF
z?ai&d*3SCwQc%#*($R*epyeHS0!m71kQn>yB;@0A-3cs>cD=JZ^8EI{vp$Y|rGq|x
z_zYHB1tT}qfIQPSky*@T#8Z*U2+;D^FZQ^sT-<;N65%V5n28({ZSnna7z!))zqFhs
zr+nBAwy;a>V=|xY9oZ+cJ8W@{Ek5%PA+U^{bXQkb9k$}Id57JmIdgYe%V7&^Y&irB
zjLfanSvA&LIX7coi7dX#rDJ`$>t<f~N@4=0_BQ}}=K;t-XUHQ7D&)eR@~Bzl1`slP
zk;K=3lLU<{?G-5)i8YcmGCJjDPP{PkLZS!k)}%~-%q&xSd7fCC<F4oRjfj+RX<10y
z>c*WNz3B(?(6t7#0NMjE0jRdfbFbWQkLDRIL$`c!J3HMGSv$|-X;pOpyowrprEF56
zB5hI#|G(pNSc437dWlf(P0H@qEQR7XLJ^2yv3;6`CsPrFSL8~I&>M8NwjXpid)<c{
z9vzF!dXX4ZiW#ps5l)cMp#gWR(;bmrFC7|Ld{c#}N%j%qlnTqGDEEI)BKd8WBzGH<
zXTE>T5F1wb_wm~9j<%;GwDfWuvq5yE3tRYbh1!-UG5S7BMo$|?!{M+UqZL*L6{k8O
z;uU+o85gS)h1KobsmoDG>_8W<C}Km*4yCnVt{}E?hS+?M+DBwR$yV64v|88ET3DO=
z=sW?-efoXqmt`@7A+GaWD@plNudKyo#yl-h2J3vN4c)mgpdBYK=Gs`~7-+h2*EzxA
zHUX}LEpOvkX<w)+BuA@_r1C4UoN>g9EYcLn<w7Y=01~bMu`0>!>38rVT(<uQaH30&
HKM4Q;N?cq?

literal 727
zcmV;|0x11KRzV<BZeeh9Xm4~Nb~6eC0Ksm_4ts+vX|VDYHTAeXE^AbZpZb~Sn)|Bv
z&eH>wO&^O000000000BsmcMV*Fcinnz5W2IidOIkcz~_Ba7TMbD+V?gDuJM&c0x|_
zlDOx@k)LyS9T?bH*;vb8!OH)@U%<%73=%K7q%H0BdfN#iJ=yWIpYlHb`Z*_|r?lV4
z51+wGt6<~=8jz>j#xjk#40$3_83J1V`sE&%rHdO7ek?o%5>t_3tS!Dj2?Alo!Ix%Z
zrBOWW23y*t_6eCs_Kxfm*&VjL!IqzUN8nq=PP^;t>kYQnV2cfQo8~OsWz7a#+F+{z
zpl@VmrB2JS=GuiBi%O)?RW2Rr$*!AO?kR~en95%R=w1XMeVrl?C8&T4d&Z+;kr_Zp
z?PU^Q|4kA!va**aU?f&ZlF;ac7di3V$V-VHvRl(K{V}&p>E%UiZHBw9+czRq!l7jW
zZL1Ttcl4I$%Ol4cNPTDx!1$nABFo%jzg?PVv<#f$#cA(!Mr5rljb>HR{fjE9@fEU3
zgbKAuAo%}|&rt=^*U1E-+?$r&uXzf^tA!#E!D8zy4Ob>20yoc;7J)lxZ}%Q{wz{21
z4_rDHsdYm!C>1kaaVi`?rb7eHcDpkoyIwjpviznDQIYH;L<tp^i6{?#Pb2wlo+Ni`
zlIOmE%n)l<`1kSZbw<6}2(7#t$E*<@>)hrZT%oqrX^g(llhL!9(Qr6yMQDYUe#xmy
zh<HV=XU4_qRAE*7cII+a5IfZQK1HmF*`c%+%oW7C=ZGzKseMfLlWdJ$ORISut)-2H
zkBz5bxktYb{h}<UFvLxsX(cIt>J_!P$e1TNN`I3NwV^u~2DIbk#Y`KE9DPkU?j|QV
z+{VC_u*Gd0DeVbWhU93qkyL&K7Bh}{o`#wNIb0~k2|&yhAeJS$HTw=ufV)4Y`3I4Q
J*1$yx002lgU3CBe

diff --git a/packages/metascraper-spotify/test/snapshots/index.js.md b/packages/metascraper-spotify/test/snapshots/index.js.md
index 4bfbdc0c6..47a73451d 100644
--- a/packages/metascraper-spotify/test/snapshots/index.js.md
+++ b/packages/metascraper-spotify/test/snapshots/index.js.md
@@ -317,7 +317,7 @@ Generated by [AVA](https://avajs.dev).
       author: 'Syntax - Tasty Web Development Treats',
       date: '2020-01-06T14:00:00.000Z',
       description: 'In this Hasty Treat, Scott and Wes talk about modules in Node — what are they, how they’re different from browser modules, and more! Sentry - Sponsor If you want to know what’s happening with your errors, track them with Sentry. Sentry is open-source error tracking that helps developers monitor and…',
-      image: 'https://i.scdn.co/image/ab6765630000ba8a6c0e28e162c68d0e67bc10d5',
+      image: 'https://i.scdn.co/image/ab6765630000ba8ab84c022aff150c336f73b395',
       lang: 'en',
       publisher: 'Spotify',
       title: 'Hasty Treat - Modules in Node',
diff --git a/packages/metascraper-spotify/test/snapshots/index.js.snap b/packages/metascraper-spotify/test/snapshots/index.js.snap
index 1bfde2d7444b9a6078d51161f902012ec97ea268..3d58d45e3086cef44eb4e52e1204b96661d2c5bc 100644
GIT binary patch
literal 1389
zcmV-z1(NzfRzV<BZeeh9Xm4~Nb~6eC0BSFb{8k#<&r%0S*l%rU<@^lRk-+>W{XJMR
zGU}nPULT7H00000000B+nagh5Mihoc-_rEzpj~uRbXvfRR+dTKDBDGmDpnFXh@?1D
zU@JwD49TH57Rg~|hL#kdK#D#=foy`JXp==Bp^GkxpnZVu`T$-PeTp7QkrAg7<;Gc9
z01f|;L>|rz`Tgh2kbG<#E;HNW;S(aMbV)bwNEwJtRb>J3*F?Z1wR>wO^Hl5_p{EwM
z_Hny$yW82mvd(C?RweqSz@Wm%fpC}<-#oS~EOAr$aXxV_(f?CkQ(mvaX9Ls){Q!Cj
z`Umv3l1QXMP0-h%ca^0J%2LhPC#F=Cqp!=$%L(PJgmONiyaO?F?<w;MW$}Wth(n9A
z(XS;TIrUpF#4O=ZI*dmLEx?#bbjTYP5hkaBq|A?wT%;auO=)ex#eOR~<a`hsE)@=$
zGWNv*xagSqkh?ELjDYKtfpbZPRMV}ST1)ISZL06HUM+38K|!y^#AlZH?nL5H3b3m-
zu?T&}X|h742raB`Ih^?{+2FL*B0O2EH`HRX4(yZ6PHu53s8G{-dW<E$8)u0F&?C^V
zphM6C*kA=z0kP9sV!;nxH`);6LXO#CT);RpjEg&Ng|S^dZ-j9HFK2^sEk&5%%hQ`6
zS)#&BX4GQO#VeVDNH!ee5p_Km8)1fwkeO%%K`=L+XVbt+wphZpOx_6ncFcE%_)cEX
zNsi67n%lEk`+&OLa<R6vXZyRQjX>Lpr}vqi-q$Ar4_w@H`%5}~|Av0qJScYVRolWe
zOYLo<J9}f8e;>vCH_+dpH-U2sbPLowE6h)t+OLTCt4r_y%{w)bcPI!~9SV647kI_Y
zt{8eYuH7?KyFWb{+CP4Yxy}^V)o8Aw*Y<mDRY=S^v0}0_MD~+tvXU{0UDt=J5@Veq
ztS4AgY1d`Go^!5Z?#SDoykEFfZIF0PHJfXy^oi3ruF^A@&RZkA#50I>jPJ#e)6bu6
z*c{v;Z=U!LIWn`Kp5@Fw`5p3f>}NZ(Kbx4@11~&#D3WKw6jo_Rs|Nd`(F(5SjP3P$
zjC>}MPkREUH}7#)Wu+$BDb{XP0?VV`MkR(lld!ER@2|7cxR%8mp?T|)ymxJ{c~xu}
zJFSZjZ8<JTzEJyLjW^;|-I?&lQ6cCr+E4Q+JT3%hA9i8#L?2MWETZbUM(t)f+jU7;
zN_R~Eis0q+<@n9V%)a^fxJ4wo``pRhMK)(1DmN<Ek%xIZ4E{@Z{;zR#|4j4=CK6@P
zlR5Y?pGbTNDuceAKPBC-j_MGz?x#%VOXACsMNP{ePFMXSRMVw_P;-`f%`EI*sWiOH
zyDWd*qX)%&Zm{!CKBsG%b|=44$Y|P{7i6PNvr_N*5_eGwHL#F9v`Y+BA_v4}fd`{N
z4NkBWQJ#7~qh+*|mQHDUBc0pSH27bGA>5wsvbnsn?IY<>fy#s42feMLy2+$O*tcLf
z0>Q0y8)1Wm5_!xDUD!l@RE3m9hYud2j)NhV6KIF@R*}OxgKviq9>F$?+BV_+6B&><
zIP1U-`>37OK_4FD<ResvAl`%PP!E_d7)RSS>ah@YFdQryYWvV|zb|N5AO{CfM!;*R
zL#5LX<cM(2IJ7yKJo;ns20MTMY1s7Is0%pTeho?qILIW!!-fa-+mrp%afllTWDPkG
zE?|s4l@JEwJ$&$UWLADLauZz>L-VME{VF!}f}Yp2z(zChIyTmGrk2TI+fL^-Gn>`z
vLe|J`<fHO=j`&k^`CNVI+{k49;5p!M(JRNnM&$U**71J<+3Kn?+9&`35iGD{

literal 1387
zcmV-x1(f<hRzV<BZeeh9Xm4~Nb~6eC03B<kxN)L2pv!QHdn*Bb^Pu8VLQ_``ba%Zm
zZ#ja{Tpx=F00000000B+nN5$|L>R~IeJka)6&$!A2BbYeHf!h2$u2@A-L%bCP10>r
z?WPE|V|x<M#`d@~<4sZtsfbU2)JugBv<E%{2M(x$55SENuqVW);7QU{-I6#<w}*}7
z)&7;lempbw@BchAwjZ@jmsuV0;4zU@x}=wLqzuHSrm=wd>mp#1w)*Q9^EB+5p{M1y
z_Hn0itJmGWTwt_Us}kd4U{c}ZKsZc_Zywn;mbj_@xTu^_27l^n>g!ebY=C;8A3#q)
z|A5|B6(t2~g1!d5tFD|^S8C=yv81X#`+Dx&IYoU-QO_#sI}o$*p1P>0%jeZ)9NLtP
zf2|0~so#DfW(9}RVLUo$3C2vKL*B57us97QWqx$zGWBqKMr%th_S?}RXM@mmsc^`Q
zu`dt7MaL|L+<hTp4BVIwoJ%UCmTKS7+hV8LqQ*Y!*HX3{<c(@fd~S*FP9+Yd0J~Zf
zi_mABCMr~l(8k)9!<o+#4Nlu_!V|T6Ln|igz&^oRi7ieA6<W$jO|ZmwlPqxndI<Uz
zbO>4k8?1sVAa+tqEcv19MjK*M$PqhC3YcVuNpVN5FtMxWjW8+T<!msir3e#zd2$mZ
zN>o^hv{vl9cr~3DiH1Wwq7|~S5$4DU>8VB#1ar%IIt{F5iY45ViR+=?iTTbE-{}iF
z$+6YZvU@GoIiPN@T&(Tvwfx=EMxgJ+)BD^`?}e$r0~hz*!II9{ziwQz4vO8o)sC>N
zQfHeO&fWy(-$yb34fHqYP2ija-30Yd3-jZq_A4U(>eBmv^G;6X9SXuVheDpi1zxo>
ztEQ2OYxf-0?oW@0_K#m;u5-n8Et;$7cl>@w6B2Vy?3nBvk^Ll^tYl1L*Y)A5#8~GD
z>oL|;`ZbxWXPqmUJMxw%@8vI68zf#+&F7jbb?h{btMnYE^VS$I@l0YL;d>$E^z)}1
zHivh}o5#LGj?C;Qr#Z8ae}_C9`{~Z?&!%Sf&<jr=isYEEgk9RvtHHi#w1X>IbGuNF
zk<TUaSx>->=3UOJtkfhs#oEnEV0+ZtsKl`661F|#{dGo~S2K7cv~FIMcdza>uZRtE
zr+vYpZN~-47i#~j@kYF=I~Cq|RtN@*_LDpcj|;)+hn=53(Fas8n`lP1QM*yj^js2_
zQeDfxEO<F}DSq=Yw{Jc^ZWD>_Ja=+;P>VAUl^d07$iuu72LGkI_}3)5e<}llic$tW
zUVtBqit-_-4ElEQgmk}pR)?5<FKIDf5?_ujYT5p1x*8mzSuPEPmbI;`R(|(#rQu!L
zWw~n}Jt*d~!=1NtSwq+L+qsQ=TG!XTAQNqx)q3BTxQCLcfrad&U1FjVIUp_zJQxLP
zaDt_X^3?ljJ*_A8R8lt@sqCh%!~Z%A;nr-IE#%Z~A4!J_R37#|>}?IzEhZ(xz74|>
z2yU%A2%9XF$YXZs!Y1mYDx@qry#D}o9SpIYKs%(rh8)%%emlJX5VqO0)gpXwB17^f
zXI;2qAGfnM?89T6e1z%{#QSg^>H+fw<7m5u`Yc3U3<pbwIzBW!=nEPa$iV@W5%3!7
zQt1o=IU<}h4s8x6kHHwc;m+TG8a2H>?gGwsP=k^J4zkGTu+c$-_T=Dn9O4E7*&_~w
z3mBtMC4|9v5AXjRnU!CR-9*>L$UNF`zlKdCZ{&;&u+dFiz=oxhbb+Ldv}F`*ofvu3
tO6hhkDxVjKKQoul)JM*ZOy&=s0}dCxaujStj=yXj{})XBi=Nsj0053+u(SXG