@adriangalilea/utils 2.10.0 → 2.12.0

package/README.md

@@ -101,28 +101,58 @@ money(100, 'EUR')   // "€100.00"
 
 ### URL (`url`)
 
-Tracking-parameter stripping and canonical cache keys, on the WHATWG URL API.
-The knowledge of WHICH params are tracking is vendored from
+URLs, from user-typed text to cache identity. The whole funnel — *is there a
+URL? which resource? whose content? what identity?* — answered once, on one
+object. Each concern rides its state of the art instead of hand-rolls:
+detection is [linkifyjs](https://linkify.js.org) (scanner-based, TLD-aware);
+parsing is the WHATWG URL API, never regexes; the knowledge of WHICH params
+are tracking is vendored from
 [@protontech/tidy-url](https://www.npmjs.com/package/@protontech/tidy-url)
 (Proton's maintained fork of DrKain/tidy-url, MIT; refresh with
-`pnpm update-url-rules`) plus a small tested overlay: global rules only for
-unambiguous trackers (utm_*, fbclid, gclid, …), ambiguous names per-host —
+`pnpm update-url-rules`) plus a small tested overlay; per-site content
+identity is an adapter registry (YouTube built in). Global rules only for
+unambiguous trackers (utm_*, fbclid, gclid, …); ambiguous names stay per-host —
 `si` is junk on YouTube/Spotify but `ref` on GitHub names a branch and
-survives. Two verbs for two jobs:
+survives.
 
 ```typescript
-import { cleanUrl, urlKey } from '@adriangalilea/utils/url'
-
-// The SAME resource minus tracking — safe to fetch, share, display.
-// Keeps scheme, www., param order, and the fragment (a real anchor).
-cleanUrl('https://www.youtube.com/watch?v=abc&t=120s&si=junk&utm_source=x')
+import { urlsIn, urlOf, cleanUrl, urlKey, hostOf, hostMatches,
+         youtubeVideoId, youtubeUrl, youtubeThumbnailUrl } from '@adriangalilea/utils/url'
+
+// Every http(s) URL in free text, in order, fully resolved:
+urlsIn('watch youtu.be/dQw4w9WgXcQ?si=junk and https://a.com/x?utm_source=t')
+// [{ raw: 'youtu.be/dQw4w9WgXcQ?si=junk', start: 6, end: 34, hadScheme: false,
+//    href: 'https://youtu.be/dQw4w9WgXcQ',          // cleaned — fetch/share this
+//    host: 'youtu.be', site: 'youtube', id: 'dQw4w9WgXcQ',
+//    key:  'youtube:dQw4w9WgXcQ' },                  // THE cache/dedupe identity
+//  { …, href: 'https://a.com/x', site: null, id: null, key: 'a.com/x' }]
+
+// One pasted token → one resolved Url (or null). Punctuation, brackets,
+// emails-are-not-URLs: the scanner's problem, not yours.
+urlOf('<https://example.com/a?utm_source=x>,')?.href  // 'https://example.com/a'
+urlOf('example.com/a', { requireScheme: true })       // null (bare domains opt-out)
+
+// `key` is the point: every spelling of one resource collides.
+// Recognized sites collapse to their native content id —
+urlKey('https://music.youtube.com/watch?v=dQw4w9WgXcQ&si=x')  // 'youtube:dQw4w9WgXcQ'
+urlKey('https://www.youtube.com/shorts/dQw4w9WgXcQ')          // 'youtube:dQw4w9WgXcQ'
+// — everything else canonicalizes generically:
+urlKey('https://www.theverge.com/2026/story/?utm_source=x#c') // 'theverge.com/2026/story'
+
+// The SAME resource minus tracking — keeps scheme, www., order, fragment.
+cleanUrl('https://www.youtube.com/watch?v=abc&t=120s&si=junk')
 // 'https://www.youtube.com/watch?v=abc&t=120s'
 
-// The resource's IDENTITY — for cache keys and dedupe. Scheme-agnostic,
-// www-less lowercase host, no trailing slash, params stripped + sorted,
-// fragment dropped: every spelling of one page collides, different pages never do.
-urlKey('https://www.theverge.com/2026/1/1/story/?utm_source=twitter#comments')
-// 'theverge.com/2026/1/1/story'
+// YouTube identity from ANY spelling (watch, youtu.be, shorts, live, embed,
+// music., nocookie, redirect wrappers, bare 11-char id):
+youtubeVideoId('https://www.youtube.com/attribution_link?u=%2Fwatch%3Fv%3DdQw4w9WgXcQ')
+// 'dQw4w9WgXcQ'
+youtubeUrl('dQw4w9WgXcQ')           // 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+youtubeThumbnailUrl('dQw4w9WgXcQ')  // 'https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg'
+
+hostOf('https://www.theverge.com/a')            // 'theverge.com'
+hostMatches('music.youtube.com', 'youtube.com') // true (RFC 6265 domain-match)
+hostMatches('notyoutube.com', 'youtube.com')    // false
 
 // App-specific junk rides along per call
 urlKey(url, { strip: ['session_id'] })

package/dist/universal/url/index.d.ts

@@ -1,18 +1,61 @@
 export { TIDY_RULES, TIDY_VERSION, type TrackingProvider } from "./tidy-rules.js";
 export { OVERLAY_RULES } from "./overlay.js";
+export { SITES, siteFor, youtubeThumbnailUrl, youtubeUrl, youtubeVideoId, type SiteAdapter } from "./sites.js";
 export interface StripOptions {
     /** Extra param names to strip (compared lowercased), for app-specific junk. */
     strip?: readonly string[];
 }
+export interface UrlsInOptions extends StripOptions {
+    /** Drop scheme-less matches (`example.com/x`) instead of coercing them to https://. */
+    requireScheme?: boolean;
+}
+/** One URL resolved from text: every layer of the funnel, answered once. */
+export interface Url {
+    /** Exactly the text that matched (punctuation and tracking still on it). */
+    raw: string;
+    /** Span of the raw match in the input text (cut links out of a message). */
+    start: number;
+    end: number;
+    /** False when the scanner inferred the link from a bare domain (`example.com/x`). */
+    hadScheme: boolean;
+    /** The cleaned absolute URL — fetch, share, and display this. */
+    href: string;
+    /** The www-less host. */
+    host: string;
+    /** The recognized service owning the host ("youtube"), or null. */
+    site: string | null;
+    /** The service's native content id (a YouTube video id), or null. */
+    id: string | null;
+    /** Canonical identity for caches/dedupe: every spelling of one resource collides. */
+    key: string;
+}
+/**
+ * Every http(s) URL in free text, in order, fully resolved. Duplicate
+ * spellings are kept (spans matter); dedupe is one line on `key`.
+ */
+export declare function urlsIn(text: string, opts?: UrlsInOptions): Url[];
+/** One pasted token / URL string as a resolved {@link Url}, or null. */
+export declare function urlOf(token: string, opts?: UrlsInOptions): Url | null;
+/** A URL's host without a leading www., or the input unchanged if it won't parse. */
+export declare function hostOf(url: string): string;
+/**
+ * True if `host` IS `domain` or a subdomain of it — never a lookalike suffix
+ * (`notyoutube.com` doesn't match `youtube.com`). RFC 6265 §5.1.3 domain-
+ * matching semantics, the same rule cookies use.
+ */
+export declare function hostMatches(host: string, domain: string): boolean;
 /**
  * The same URL minus tracking params: safe to fetch, share, and display.
  * Unparseable or non-http(s) input is returned unchanged.
  */
 export declare function cleanUrl(url: string, opts?: StripOptions): string;
 /**
- * A canonical identity for the resource behind `url` — `host/path?sortedQuery`
- * — for cache keys and dedupe. Unparseable or non-http(s) input is returned
- * unchanged so it still keys consistently.
+ * A canonical identity for the resource behind `url`, for cache keys and
+ * dedupe. A recognized site's content collapses to its native id
+ * ("youtube:dQw4w9WgXcQ" — watch, youtu.be, shorts, live, embed, all one
+ * key); everything else canonicalizes to `host/path?sortedQuery`,
+ * scheme-agnostic, www-less, tracking-stripped, fragment-free. Unparseable
+ * or non-http(s) input is returned unchanged so it still keys consistently.
  */
 export declare function urlKey(url: string, opts?: StripOptions): string;
 /**

package/dist/universal/url/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/universal/url/index.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAKjE;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAU/D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,OAAO,CAUhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/universal/url/index.ts"],"names":[],"mappings":"AA4CA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/G,MAAM,WAAW,YAAY;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IAClD,uFAAuF;IACvF,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,GAAG;IACnB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,SAAS,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,qEAAqE;IACrE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,GAAG,EAAE,CAahE;AAED,wEAAwE;AACxE,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,GAAG,GAAG,IAAI,CAErE;AAED,qFAAqF;AACrF,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM1C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAKjE;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAY/D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,OAAO,CAUhE"}

package/dist/universal/url/index.js

@@ -1,31 +1,92 @@
 /**
- * URL hygiene: tracking-parameter stripping and canonical cache keys.
- * Pure and dependency-free — safe in Node, Workers, and browsers.
+ * URLs, from user-typed text to cache identity. Safe in Node, Workers, and
+ * browsers. The whole funnel every consumer walks — is there a URL? which
+ * resource? whose content? what identity? — answered ONCE, on one object:
  *
- * Two verbs for two jobs:
- *  - `cleanUrl(url)`: the SAME resource, minus tracking params. Safe to fetch,
- *    share, and display. Keeps scheme, www., remaining param order, and the
- *    fragment (a fragment can be a real anchor).
- *  - `urlKey(url)`: the resource's IDENTITY, for cache keys and dedupe.
- *    Scheme-agnostic, lowercase host without www. or a trailing dot, no
- *    trailing slash, tracking params stripped, surviving params sorted,
- *    fragment dropped. Two spellings of one page collide; two different
- *    pages never do.
+ *   Url {
+ *     raw, start, end   what they typed, and where in the text
+ *     hadScheme         typed https:// vs inferred from a bare domain
+ *     href              cleaned absolute URL — fetch, share, display this
+ *     host              www-less host
+ *     site              recognized service ("youtube") or null
+ *     id                the service's native content id, or null
+ *     key               canonical identity for caches/dedupe:
+ *                       "youtube:dQw4w9WgXcQ" | "theverge.com/2026/story"
+ *   }
  *
- * The knowledge of WHICH params are tracking is not ours: it's vendored from
- * @protontech/tidy-url (Proton's maintained fork of DrKain/tidy-url, MIT; see
- * tidy-rules.ts, refresh with `pnpm update-url-rules`) plus a small tested
- * overlay for gaps (overlay.ts). URLs are parsed with the WHATWG URL API,
- * never regexes; the dataset's per-provider matchers select which rules apply
- * to a host, and param names are compared literally (lowercased).
+ * Two verbs, one per input shape:
+ *   urlsIn(text)  → Url[]        every URL in free text, in order, with spans
+ *   urlOf(token)  → Url | null   one pasted token / URL string
  *
- * Unparseable or non-http(s) input passes through unchanged: these are hygiene
- * functions over user-pasted text, not validators.
+ * The `key` is the point: every spelling of one resource collides (scheme,
+ * www., trailing slash, tracking params, and for recognized sites every URL
+ * shape of the same content id), and two different resources never do.
+ *
+ * Each concern rides its state of the art instead of hand-rolls:
+ *  - detection in free text: linkifyjs (scanner-based, TLD-aware, MIT) — it
+ *    owns the messy boundaries (trailing punctuation, brackets, emails);
+ *  - parsing/serialization: the WHATWG URL API, never regexes;
+ *  - which params are tracking: vendored from @protontech/tidy-url (Proton's
+ *    maintained fork of DrKain/tidy-url, MIT; see tidy-rules.ts, refresh with
+ *    `pnpm update-url-rules`) plus a small tested overlay (overlay.ts) —
+ *    param names compare literally (lowercased), per host;
+ *  - per-site content identity: the adapter registry (sites.ts).
+ *
+ * The low-level verbs (`cleanUrl`, `urlKey`, `hostOf`, `hostMatches`,
+ * `isTrackingParam`, the youtube helpers) stay exported for surgical use.
+ * Unparseable or non-http(s) input passes through unchanged: these are
+ * hygiene functions over user-pasted text, not validators.
  */
+import { find } from "linkifyjs";
 import { OVERLAY_RULES } from "./overlay.js";
+import { siteFor } from "./sites.js";
 import { TIDY_RULES } from "./tidy-rules.js";
 export { TIDY_RULES, TIDY_VERSION } from "./tidy-rules.js";
 export { OVERLAY_RULES } from "./overlay.js";
+export { SITES, siteFor, youtubeThumbnailUrl, youtubeUrl, youtubeVideoId } from "./sites.js";
+/**
+ * Every http(s) URL in free text, in order, fully resolved. Duplicate
+ * spellings are kept (spans matter); dedupe is one line on `key`.
+ */
+export function urlsIn(text, opts) {
+    const out = [];
+    for (const link of find(text, "url", { defaultProtocol: "https" })) {
+        // href === value exactly when the text already carried a scheme; otherwise
+        // the scanner built href by prepending defaultProtocol onto the bare match.
+        const hadScheme = link.href === link.value;
+        if (!hadScheme && opts?.requireScheme)
+            continue;
+        const u = parseHttp(link.href);
+        if (!u)
+            continue; // a non-http scheme the scanner knows; not our job
+        deleteTracking(u, opts);
+        out.push(resolveUrl(u, { raw: link.value, start: link.start, end: link.end, hadScheme }));
+    }
+    return out;
+}
+/** One pasted token / URL string as a resolved {@link Url}, or null. */
+export function urlOf(token, opts) {
+    return urlsIn(token, opts)[0] ?? null;
+}
+/** A URL's host without a leading www., or the input unchanged if it won't parse. */
+export function hostOf(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * True if `host` IS `domain` or a subdomain of it — never a lookalike suffix
+ * (`notyoutube.com` doesn't match `youtube.com`). RFC 6265 §5.1.3 domain-
+ * matching semantics, the same rule cookies use.
+ */
+export function hostMatches(host, domain) {
+    const h = host.toLowerCase().replace(/^www\./, "").replace(/\.$/, "");
+    const d = domain.toLowerCase();
+    return h === d || h.endsWith(`.${d}`);
+}
 /**
  * The same URL minus tracking params: safe to fetch, share, and display.
  * Unparseable or non-http(s) input is returned unchanged.
@@ -38,21 +99,27 @@ export function cleanUrl(url, opts) {
     return u.toString();
 }
 /**
- * A canonical identity for the resource behind `url` — `host/path?sortedQuery`
- * — for cache keys and dedupe. Unparseable or non-http(s) input is returned
- * unchanged so it still keys consistently.
+ * A canonical identity for the resource behind `url`, for cache keys and
+ * dedupe. A recognized site's content collapses to its native id
+ * ("youtube:dQw4w9WgXcQ" — watch, youtu.be, shorts, live, embed, all one
+ * key); everything else canonicalizes to `host/path?sortedQuery`,
+ * scheme-agnostic, www-less, tracking-stripped, fragment-free. Unparseable
+ * or non-http(s) input is returned unchanged so it still keys consistently.
  */
 export function urlKey(url, opts) {
     const u = parseHttp(url);
     if (!u)
         return url;
+    const site = siteFor(normalizedHost(u));
+    const id = site?.id(u);
+    if (site && id)
+        return site.key(id);
     deleteTracking(u, opts);
     u.searchParams.sort();
-    const host = u.hostname.toLowerCase().replace(/^www\./, "").replace(/\.$/, "");
     const port = u.port ? `:${u.port}` : ""; // default ports never survive URL parsing
     const path = u.pathname.replace(/\/+$/, "") || "/";
     const query = u.searchParams.toString();
-    return `${host}${port}${path}${query ? `?${query}` : ""}`;
+    return `${normalizedHost(u)}${port}${path}${query ? `?${query}` : ""}`;
 }
 /**
  * True if `name` is a tracking param — globally, or on `host` specifically.
@@ -72,6 +139,25 @@ export function isTrackingParam(name, host = "") {
     }
     return doomed.has(n) && !allowed.has(n);
 }
+// ── internals ───────────────────────────────────────────────────────────────
+/** Assemble a {@link Url} from an already-cleaned parsed URL + its text facts. */
+function resolveUrl(u, text) {
+    const host = normalizedHost(u);
+    const site = siteFor(host);
+    const id = site?.id(u) ?? null;
+    return {
+        ...text,
+        href: u.toString(),
+        host,
+        site: site?.name ?? null,
+        id,
+        key: site && id ? site.key(id) : urlKey(u.toString()),
+    };
+}
+/** Lowercased hostname without a leading www. or a trailing dot. */
+function normalizedHost(u) {
+    return u.hostname.toLowerCase().replace(/^www\./, "").replace(/\.$/, "");
+}
 let cache = null;
 /** All providers (vendored + overlay), matchers compiled once per process. */
 function compiled() {

package/dist/universal/url/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/universal/url/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/universal/url/index.ts"],"names":[],"mappings":"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"}

package/dist/universal/url/sites.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The site registry: per-service identity knowledge, one adapter per service
+ * (the same knowledge-as-data pattern as tidy-rules.ts). An adapter answers
+ * "is this host yours?" and "what's the native content id in this URL?", and
+ * from the id derives the canonical URL and the cache-identity key — so every
+ * spelling of one video (watch, youtu.be, shorts, live, embed, music.,
+ * nocookie, nested redirects) collapses to ONE identity.
+ *
+ * Extraction is WHATWG-URL based, nested-redirect aware, and percent-decode
+ * tolerant — no regex URL parsing. Adding a service (spotify, vimeo, …) is
+ * one more adapter entry.
+ */
+export interface SiteAdapter {
+    /** The service name, and the prefix of its identity keys ("youtube"). */
+    name: string;
+    /** Whether this (lowercased, www-less) host belongs to the service. */
+    matches(host: string): boolean;
+    /** The service's native content id in this URL, or null. */
+    id(url: URL): string | null;
+    /** The canonical URL for a content id. */
+    canonicalUrl(id: string): string;
+    /** The cache-identity key for a content id ("youtube:dQw4w9WgXcQ"). */
+    key(id: string): string;
+}
+/**
+ * The 11-char video id from ANY YouTube URL spelling or a bare id; null if
+ * the input isn't one. Percent-encoded input gets one decode attempt so a
+ * copied-from-HTML link still resolves.
+ */
+export declare function youtubeVideoId(input: string): string | null;
+/** The canonical watch URL for a video id or any YouTube URL spelling; null if neither. */
+export declare function youtubeUrl(idOrUrl: string): string | null;
+/**
+ * A public thumbnail URL for a video id or any YouTube URL spelling; null if
+ * neither. Uses `hqdefault`, which exists for every valid video (unlike
+ * `maxresdefault`, which 404s for many).
+ */
+export declare function youtubeThumbnailUrl(idOrUrl: string): string | null;
+export declare const SITES: readonly SiteAdapter[];
+/** The adapter owning this (lowercased, www-less) host, or null. */
+export declare function siteFor(host: string): SiteAdapter | null;
+//# sourceMappingURL=sites.d.ts.map

package/dist/universal/url/sites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites.d.ts","sourceRoot":"","sources":["../../../src/universal/url/sites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC3B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,EAAE,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAgED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY3D;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAID,eAAO,MAAM,KAAK,EAAE,SAAS,WAAW,EAAc,CAAC;AAEvD,oEAAoE;AACpE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAExD"}

package/dist/universal/url/sites.js

@@ -0,0 +1,130 @@
+/**
+ * The site registry: per-service identity knowledge, one adapter per service
+ * (the same knowledge-as-data pattern as tidy-rules.ts). An adapter answers
+ * "is this host yours?" and "what's the native content id in this URL?", and
+ * from the id derives the canonical URL and the cache-identity key — so every
+ * spelling of one video (watch, youtu.be, shorts, live, embed, music.,
+ * nocookie, nested redirects) collapses to ONE identity.
+ *
+ * Extraction is WHATWG-URL based, nested-redirect aware, and percent-decode
+ * tolerant — no regex URL parsing. Adding a service (spotify, vimeo, …) is
+ * one more adapter entry.
+ */
+// ── youtube ─────────────────────────────────────────────────────────────────
+const YOUTUBE_ID = /^[a-zA-Z0-9_-]{11}$/;
+const YOUTUBE_PATH_KINDS = new Set(["embed", "v", "shorts", "live"]);
+function isYouTubeHost(host) {
+    return (host === "youtube.com" ||
+        host.endsWith(".youtube.com") ||
+        host === "youtube-nocookie.com" ||
+        host.endsWith(".youtube-nocookie.com"));
+}
+function validYouTubeId(value) {
+    return value && YOUTUBE_ID.test(value) ? value : null;
+}
+function youtubeIdFromUrl(url) {
+    const host = url.hostname.toLowerCase().replace(/^www\./, "");
+    if (host === "youtu.be") {
+        return validYouTubeId(url.pathname.split("/").filter(Boolean)[0]);
+    }
+    if (!isYouTubeHost(host))
+        return null;
+    const queryId = validYouTubeId(url.searchParams.get("v") ?? url.searchParams.get("video_id"));
+    if (queryId)
+        return queryId;
+    const [kind, id] = url.pathname.split("/").filter(Boolean);
+    if (YOUTUBE_PATH_KINDS.has(kind)) {
+        const pathId = validYouTubeId(id);
+        if (pathId)
+            return pathId;
+    }
+    // Redirect wrappers (attribution_link?u=/watch%3Fv%3D…, redirect?q=…): the
+    // nested value may be relative, so resolve it against the outer URL.
+    for (const param of ["u", "url", "q"]) {
+        const nested = url.searchParams.get(param);
+        if (!nested)
+            continue;
+        let nestedUrl;
+        try {
+            nestedUrl = new URL(nested, url);
+        }
+        catch {
+            continue;
+        }
+        if (nestedUrl.href === url.href)
+            continue;
+        const nestedId = youtubeIdFromUrl(nestedUrl);
+        if (nestedId)
+            return nestedId;
+    }
+    return null;
+}
+const youtube = {
+    name: "youtube",
+    matches: (host) => host === "youtu.be" || isYouTubeHost(host),
+    id: youtubeIdFromUrl,
+    canonicalUrl: (id) => `https://www.youtube.com/watch?v=${id}`,
+    key: (id) => `youtube:${id}`,
+};
+/**
+ * The 11-char video id from ANY YouTube URL spelling or a bare id; null if
+ * the input isn't one. Percent-encoded input gets one decode attempt so a
+ * copied-from-HTML link still resolves.
+ */
+export function youtubeVideoId(input) {
+    const trimmed = input.trim();
+    if (YOUTUBE_ID.test(trimmed))
+        return trimmed;
+    for (const candidate of [trimmed, safeDecode(trimmed)]) {
+        const url = parseLoose(candidate);
+        if (url) {
+            const id = youtubeIdFromUrl(url);
+            if (id)
+                return id;
+        }
+    }
+    return null;
+}
+/** The canonical watch URL for a video id or any YouTube URL spelling; null if neither. */
+export function youtubeUrl(idOrUrl) {
+    const id = youtubeVideoId(idOrUrl);
+    return id ? youtube.canonicalUrl(id) : null;
+}
+/**
+ * A public thumbnail URL for a video id or any YouTube URL spelling; null if
+ * neither. Uses `hqdefault`, which exists for every valid video (unlike
+ * `maxresdefault`, which 404s for many).
+ */
+export function youtubeThumbnailUrl(idOrUrl) {
+    const id = youtubeVideoId(idOrUrl);
+    return id ? `https://i.ytimg.com/vi/${id}/hqdefault.jpg` : null;
+}
+// ── the registry ────────────────────────────────────────────────────────────
+export const SITES = [youtube];
+/** The adapter owning this (lowercased, www-less) host, or null. */
+export function siteFor(host) {
+    return SITES.find((s) => s.matches(host)) ?? null;
+}
+// ── internals ───────────────────────────────────────────────────────────────
+function parseLoose(input) {
+    try {
+        return new URL(input);
+    }
+    catch {
+        try {
+            return new URL(`https://${input}`);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function safeDecode(input) {
+    try {
+        return decodeURIComponent(input);
+    }
+    catch {
+        return input;
+    }
+}
+//# sourceMappingURL=sites.js.map

package/dist/universal/url/sites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites.js","sourceRoot":"","sources":["../../../src/universal/url/sites.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.10.0",
+	"version": "2.12.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -220,17 +220,17 @@
 		"zod": "^4.4.3"
 	},
 	"peerDependencies": {
+		"@ai-sdk/anthropic": "^4.0.0",
+		"@ai-sdk/openai-compatible": "^3.0.0",
 		"@gramio/format": ">=0.8.0",
 		"@gramio/session": ">=0.2.0",
+		"@gramio/split": "^0.0.1",
 		"@gramio/storage": ">=2.0.0",
+		"@openrouter/ai-sdk-provider": "^3.0.0",
+		"ai": "^7.0.0",
 		"gramio": "^0.12.0",
 		"marked": ">=12",
-		"zod": ">=3.22",
-		"ai": "^7.0.0",
-		"@ai-sdk/anthropic": "^4.0.0",
-		"@ai-sdk/openai-compatible": "^3.0.0",
-		"@openrouter/ai-sdk-provider": "^3.0.0",
-		"@gramio/split": "^0.0.1"
+		"zod": ">=3.22"
 	},
 	"peerDependenciesMeta": {
 		"@gramio/format": {
@@ -279,5 +279,8 @@
 		"url": "https://github.com/adriangalilea/ts-utils/issues"
 	},
 	"homepage": "https://github.com/adriangalilea/ts-utils#readme",
-	"sideEffects": false
+	"sideEffects": false,
+	"dependencies": {
+		"linkifyjs": "^4.3.3"
+	}
 }