@postfetch/core 0.12.4 → 0.13.0

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
 /** A platform that {@link postfetch} can resolve. */
-export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
+export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "spotify" | "tiktok" | "twitter" | "youtube";
 /** The kind of a {@link MediaItem}. */
 export type MediaKind = "audio" | "image" | "video";
 /** A single resolved media file: a direct URL plus everything needed to fetch and name it. */
@@ -33,6 +33,8 @@ export type MediaItem = {
     mime: string;
     /** The platform this item came from. */
     platform: Platform;
+    /** Website preview image, displayed below the post's content rather than in its attachment gallery. */
+    role?: "linkPreview";
     /** Direct CDN URL of the media. */
     url: string;
 };
@@ -142,6 +144,15 @@ export type SoundcloudExtra = {
     /** Track duration in seconds. */
     durationSeconds?: number;
 };
+/** Spotify track metadata, with the YouTube source selected for downloading. */
+export type SpotifyExtra = {
+    /** Artists credited on Spotify, in order. */
+    artists: string[];
+    /** Spotify track duration in seconds, when available. */
+    durationSeconds?: number;
+    /** Public watch URL passed to the existing YouTube resolver. */
+    youtubeUrl: string;
+};
 /** Pinterest-specific metadata. */
 export type PinterestExtra = {
     /** Times the pin was saved (repinned). */
@@ -163,7 +174,7 @@ export type PostComment = {
     items: MediaItem[];
 };
 /** The result of resolving a post: its platform, id, media items and metadata. */
-export type PostfetchResult = PlatformResult<"facebook", never> | PlatformResult<"instagram", InstagramExtra> | PlatformResult<"linkedin", never> | PlatformResult<"pinterest", PinterestExtra> | PlatformResult<"reddit", RedditExtra> | PlatformResult<"soundcloud", SoundcloudExtra> | PlatformResult<"tiktok", TiktokExtra> | PlatformResult<"twitter", TwitterExtra> | PlatformResult<"youtube", YoutubeExtra>;
+export type PostfetchResult = PlatformResult<"facebook", never> | PlatformResult<"instagram", InstagramExtra> | PlatformResult<"linkedin", never> | PlatformResult<"pinterest", PinterestExtra> | PlatformResult<"reddit", RedditExtra> | PlatformResult<"soundcloud", SoundcloudExtra> | PlatformResult<"spotify", SpotifyExtra> | PlatformResult<"tiktok", TiktokExtra> | PlatformResult<"twitter", TwitterExtra> | PlatformResult<"youtube", YoutubeExtra>;
 /** One platform's variant of a {@link PostfetchResult}, carrying that platform's `extra` metadata shape. */
 export type PlatformResult<P extends Platform, Extra> = {
     /** Suggested filename when zipping every item. */

package/dist/spotify.d.ts

@@ -0,0 +1,3 @@
+import { type PlatformResult, type ResolveContext, type SpotifyExtra } from "./internal";
+/** Resolve Spotify track metadata and a matching video through YouTube. */
+export declare function resolveSpotify(input: ResolveContext): Promise<PlatformResult<"spotify", SpotifyExtra>>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@postfetch/core",
-  "version": "0.12.4",
-  "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
+  "version": "0.13.0",
+  "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, Spotify, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -35,6 +35,7 @@
     "pinterest",
     "reddit",
     "soundcloud",
+    "spotify",
     "tiktok",
     "twitter",
     "youtube",

package/src/download.ts

@@ -185,10 +185,16 @@ export async function archive(result: PostfetchResult, options: DownloadOptions
  * @returns A `Response` a server or edge function can return directly.
  */
 export async function toResponse(result: PostfetchResult, options: DownloadOptions = {}): Promise<Response> {
-  if (result.items.length === 1) {
-    return singleResponse(result.items[0], options);
+  const response = result.items.length === 1
+    ? await singleResponse(result.items[0], options)
+    : await archiveResponse(result, options);
+  if (result.platform === "spotify") {
+    response.headers.set("x-media-platform", result.platform);
+    response.headers.set("x-media-id", result.id);
+    const youtubeUrl = result.metadata?.extra?.youtubeUrl;
+    if (youtubeUrl) response.headers.set("x-media-youtube-url", youtubeUrl);
   }
-  return archiveResponse(result, options);
+  return response;
 }
 
 async function singleResponse(item: MediaItem, options: DownloadOptions): Promise<Response> {

package/src/index.ts

@@ -1,8 +1,9 @@
 /**
  * Turn a public social post URL into its media.
  *
- * {@link postfetch} resolves Instagram, LinkedIn, TikTok, YouTube, Facebook and X (Twitter)
- * URLs to typed {@link MediaItem}s. Zero dependencies, only Web-standard APIs
+ * {@link postfetch} resolves public social post and Spotify track URLs to typed
+ * {@link MediaItem}s. Spotify tracks are matched to YouTube videos.
+ * Zero dependencies, only Web-standard APIs
  * (`fetch`, `Response`, `URL`, `crypto`) — so it runs on Deno, Node, Bun,
  * Cloudflare Workers and browsers alike. It only resolves the media; the
  * {@link download}, {@link downloadBlob}, {@link archive} and {@link toResponse}
@@ -46,6 +47,7 @@ export type {
   PostMetadata,
   RedditExtra,
   SoundcloudExtra,
+  SpotifyExtra,
   TiktokExtra,
   TwitterExtra,
   TwitterQuotedTweet,

package/src/internal.ts

@@ -1,5 +1,5 @@
 /** A platform that {@link postfetch} can resolve. */
-export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
+export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "spotify" | "tiktok" | "twitter" | "youtube";
 
 /** The kind of a {@link MediaItem}. */
 export type MediaKind = "audio" | "image" | "video";
@@ -32,6 +32,8 @@ export type MediaItem = {
   mime: string;
   /** The platform this item came from. */
   platform: Platform;
+  /** Website preview image, displayed below the post's content rather than in its attachment gallery. */
+  role?: "linkPreview";
   /** Direct CDN URL of the media. */
   url: string;
 };
@@ -149,6 +151,16 @@ export type SoundcloudExtra = {
   durationSeconds?: number;
 };
 
+/** Spotify track metadata, with the YouTube source selected for downloading. */
+export type SpotifyExtra = {
+  /** Artists credited on Spotify, in order. */
+  artists: string[];
+  /** Spotify track duration in seconds, when available. */
+  durationSeconds?: number;
+  /** Public watch URL passed to the existing YouTube resolver. */
+  youtubeUrl: string;
+};
+
 /** Pinterest-specific metadata. */
 export type PinterestExtra = {
   /** Times the pin was saved (repinned). */
@@ -179,6 +191,7 @@ export type PostfetchResult =
   | PlatformResult<"pinterest", PinterestExtra>
   | PlatformResult<"reddit", RedditExtra>
   | PlatformResult<"soundcloud", SoundcloudExtra>
+  | PlatformResult<"spotify", SpotifyExtra>
   | PlatformResult<"tiktok", TiktokExtra>
   | PlatformResult<"twitter", TwitterExtra>
   | PlatformResult<"youtube", YoutubeExtra>;

package/src/postfetch.ts

@@ -5,6 +5,7 @@ import { resolveLinkedin } from "./linkedin";
 import { resolvePinterest } from "./pinterest";
 import { resolveReddit } from "./reddit";
 import { resolveSoundcloud } from "./soundcloud";
+import { resolveSpotify } from "./spotify";
 import { resolveTiktok } from "./tiktok";
 import { resolveTwitter } from "./twitter";
 import { resolveYoutube } from "./youtube";
@@ -85,6 +86,8 @@ async function resolve(context: ResolveContext): Promise<PostfetchResult> {
       return resolveReddit(context);
     case "soundcloud":
       return resolveSoundcloud(context);
+    case "spotify":
+      return resolveSpotify(context);
     case "tiktok":
       return resolveTiktok(context);
     case "twitter":
@@ -180,6 +183,9 @@ export function detect(url: string): Platform {
   if (host.includes("soundcloud.com") || host === "snd.sc") {
     return "soundcloud";
   }
+  if (host === "open.spotify.com") {
+    return "spotify";
+  }
   if (host.includes("youtube.com") || host === "youtu.be") {
     return "youtube";
   }
@@ -189,5 +195,5 @@ export function detect(url: string): Platform {
   if (host === "x.com" || host.endsWith(".x.com") || host.includes("twitter.com")) {
     return "twitter";
   }
-  throw new PostfetchError(400, "only Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube URLs are supported");
+  throw new PostfetchError(400, "only Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, Spotify, TikTok, X and YouTube URLs are supported");
 }

package/src/spotify.ts

@@ -0,0 +1,170 @@
+import { browserUserAgent } from "./fingerprint";
+import { asUrl, filename, number, object, PostfetchError, string, type Json, type PlatformResult, type ResolveContext, type SpotifyExtra } from "./internal";
+import { resolveYoutube } from "./youtube";
+
+type Track = { title: string; artists: string[]; durationSeconds?: number };
+
+/** Resolve Spotify track metadata and a matching video through YouTube. */
+export async function resolveSpotify(input: ResolveContext): Promise<PlatformResult<"spotify", SpotifyExtra>> {
+  const url = asUrl(input.url);
+  const id = url.pathname.match(/^\/(?:intl-[a-z-]+\/)?(?:embed\/)?track\/([A-Za-z0-9]{22})\/?$/i)?.[1];
+  if (!id) {
+    throw new PostfetchError(400, "Spotify requires an open.spotify.com track URL");
+  }
+  const track = await spotifyTrack(input, id);
+  const youtubeUrl = await matchYoutube(input, track);
+  // Keep YouTube's media, filenames, separate audio and client fallback intact.
+  const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+  return {
+    archiveFilename: filename(`spotify_${id}.zip`),
+    comments: [],
+    id,
+    items: youtube.items,
+    platform: "spotify",
+    metadata: {
+      title: track.title,
+      author: { name: track.artists.join(", ") },
+      extra: { artists: track.artists, durationSeconds: track.durationSeconds, youtubeUrl },
+    },
+  };
+}
+
+async function spotifyTrack(input: ResolveContext, id: string): Promise<Track> {
+  const response = await input.net(`https://open.spotify.com/embed/track/${id}`, {
+    headers: { "user-agent": browserUserAgent() },
+  });
+  if (!response.ok) {
+    throw new PostfetchError(response.status === 404 ? 404 : 502, `Spotify track lookup failed: ${response.status}`);
+  }
+  const html = await response.text();
+  const raw = html.match(/<script\b[^>]*\bid=["']__NEXT_DATA__["'][^>]*>([\s\S]*?)<\/script>/i)?.[1];
+  const payload = parseJson(raw);
+  const props = payload && object(payload.props) ? payload.props : null;
+  const page = props && object(props.pageProps) ? props.pageProps : null;
+  const state = page && object(page.state) ? page.state : null;
+  const data = state && object(state.data) ? state.data : null;
+  const entity = data && object(data.entity) ? data.entity : null;
+  const title = entity && (string(entity.title) ?? string(entity.name));
+  const artists = entity && Array.isArray(entity.artists)
+    ? entity.artists.filter(object).map((artist) => string(artist.name)).filter((name): name is string => name !== null)
+    : [];
+  if (!entity || entity.type !== "track" || entity.id !== id || !title || artists.length === 0) {
+    throw new PostfetchError(502, "Spotify track metadata not found");
+  }
+  const duration = number(entity.duration);
+  return { title, artists, durationSeconds: duration !== null && duration > 0 ? duration / 1000 : undefined };
+}
+
+async function matchYoutube(input: ResolveContext, track: Track): Promise<string> {
+  const url = new URL("https://www.youtube.com/results");
+  url.searchParams.set("search_query", `${track.artists.join(" ")} ${track.title} audio`);
+  url.searchParams.set("hl", "en");
+  const response = await input.net(url.href, {
+    headers: { "accept-language": "en-US,en;q=0.9", cookie: "SOCS=CAI", "user-agent": browserUserAgent() },
+  });
+  if (!response.ok) {
+    throw new PostfetchError(502, `YouTube search failed: ${response.status}`);
+  }
+  const html = await response.text();
+  // Read the JSON assignment up to the end of its script, without evaluating JS.
+  // The balanced JSON object is extracted before parsing; trailing JS is ignored.
+  const raw = html.match(/(?:\bytInitialData|window\[["']ytInitialData["']\])\s*=\s*(\{[\s\S]*?)<\/script>/)?.[1];
+  const payload = parseAssignment(raw);
+  if (!payload || !object(payload.contents)) {
+    throw new PostfetchError(502, "YouTube search results not found");
+  }
+  const candidates = videoRenderers(payload.contents);
+  const ranked = candidates.map((candidate, index) => ({ candidate, score: matchScore(track, candidate) - index / 1000 }))
+    .filter(({ score }) => Number.isFinite(score))
+    .sort((left, right) => right.score - left.score);
+  const id = ranked[0]?.candidate.videoId;
+  if (typeof id !== "string") {
+    throw new PostfetchError(404, "No matching YouTube video found for this Spotify track", "notFound");
+  }
+  return `https://www.youtube.com/watch?v=${id}`;
+}
+
+function videoRenderers(value: unknown): Json[] {
+  if (Array.isArray(value)) return value.flatMap(videoRenderers);
+  if (!object(value)) return [];
+  if (object(value.videoRenderer)) return [value.videoRenderer];
+  return Object.values(value).flatMap(videoRenderers);
+}
+
+function text(value: unknown): string {
+  if (!object(value)) return "";
+  return string(value.simpleText) ?? (Array.isArray(value.runs)
+    ? value.runs.filter(object).map((run) => typeof run.text === "string" ? run.text : "").join("")
+    : "");
+}
+
+function normalize(value: string): string {
+  return value.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+function contains(haystack: string, needle: string): boolean {
+  return needle.length > 0 && ` ${haystack} `.includes(` ${needle} `);
+}
+
+function durationSeconds(value: string): number | null {
+  if (!/^\d+(?::\d{2}){1,2}$/.test(value)) return null;
+  return value.split(":").reduce((seconds, part) => seconds * 60 + Number(part), 0);
+}
+
+function matchScore(track: Track, candidate: Json): number {
+  if (typeof candidate.videoId !== "string" || !/^[A-Za-z0-9_-]{11}$/.test(candidate.videoId)) return -Infinity;
+  const title = normalize(text(candidate.title));
+  const author = normalize(text(candidate.ownerText) || text(candidate.longBylineText) || text(candidate.shortBylineText));
+  const expected = normalize(track.title.replace(/\s*[([](?:feat\.?|ft\.?).*?[)\]]/gi, ""));
+  const tokens = expected.split(" ").filter(Boolean);
+  if (tokens.length === 0) return -Infinity;
+  const coverage = tokens.filter((token) => contains(title, token)).length / tokens.length;
+  if (coverage < (tokens.length <= 3 ? 1 : 0.8)) return -Infinity;
+  if (tokens.length <= 3 && !contains(title, expected)) return -Infinity;
+  const artists = track.artists.map(normalize);
+  if (!contains(`${title} ${author}`, artists[0])) return -Infinity;
+  const duration = durationSeconds(text(candidate.lengthText));
+  if (duration === null || duration <= 0) return -Infinity; // Excludes live streams and upcoming videos.
+  const tolerance = Math.min(30, Math.max(12, (track.durationSeconds ?? duration) * 0.08));
+  const delta = track.durationSeconds === undefined ? 0 : Math.abs(duration - track.durationSeconds);
+  if (delta > tolerance) return -Infinity;
+  // Do not silently substitute a different recording or speed edit. Artist names
+  // are removed first so e.g. a band called "Live" is not treated as a live edit.
+  let recordingTitle = title;
+  for (const artist of artists) recordingTitle = recordingTitle.replace(artist, "");
+  for (const version of [/\bremix\b/, /\bcover\b/, /\bkaraoke\b/, /\binstrumental\b/, /\bslowed\b/, /\b(?:sped|speed) up\b/, /\bnightcore\b/, /\blive\b/, /\bacoustic\b/]) {
+    if (version.test(recordingTitle) !== version.test(expected)) return -Infinity;
+  }
+  const artistUpload = contains(author, artists[0]);
+  const credited = artists.filter((artist) => contains(`${title} ${author}`, artist)).length / artists.length;
+  return coverage * 10 + (artistUpload ? 8 : 0) + credited * 2 + (contains(title, "official") ? 2 : 0) + 3 * (1 - delta / tolerance);
+}
+
+function parseJson(value: string | undefined): Json | null {
+  try {
+    const parsed: unknown = JSON.parse(value ?? "");
+    return object(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseAssignment(value: string | undefined): Json | null {
+  if (!value) return null;
+  // Balance braces outside JSON strings so titles containing `};` cannot truncate
+  // the payload, and trailing statements in the same script are ignored.
+  let depth = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') quoted = false;
+    } else if (character === '"') quoted = true;
+    else if (character === "{") depth += 1;
+    else if (character === "}" && --depth === 0) return parseJson(value.slice(0, index + 1));
+  }
+  return null;
+}

package/src/twitter.ts

@@ -33,13 +33,20 @@ export async function resolveTwitter(input: ResolveContext): Promise<PostfetchRe
     throw new Error("Tweet is unavailable or age-restricted");
   }
   await expandTwitterText(input.net, tweet, id);
-  const groups = twitterTweets(tweet, id).flatMap(({ id: postId, tweet: post }) => {
+  const posts = twitterTweets(tweet, id);
+  const groups = posts.flatMap(({ id: postId, tweet: post }) => {
     const media = Array.isArray(post.mediaDetails) ? post.mediaDetails.filter(object) : [];
     return media.flatMap((entry, index) => {
       const candidates = twitterCandidates(entry, postId, index + 1);
       return candidates.length > 0 ? [candidates] : [];
     });
   });
+  // Quotes nest inside their containing post, so append each card as we unwind
+  // the quote chain. Download order then matches the displayed post order.
+  for (const { id: postId, tweet: post } of posts.toReversed()) {
+    const card = twitterCardImage(post, postId);
+    if (card) groups.push([{ bitrate: 0, item: card }]);
+  }
   const items = input.tryMaxBytes === undefined ? groups.map((group) => group[0].item) : await sizeLimitedItems(input, groups);
   // A text-only tweet is a valid result with metadata and no media. Syndication
   // has already failed or returned a tombstone when the tweet is unavailable,
@@ -213,6 +220,41 @@ function twitterCandidates(entry: Json, id: string, index: number): TwitterCandi
     : [];
 }
 
+function twitterCardImage(tweet: Json, id: string): MediaItem | null {
+  const card = object(tweet.card) ? tweet.card : null;
+  if (!card || (card.name !== "summary" && card.name !== "summary_large_image")) return null;
+  const bindings = object(card.binding_values) ? card.binding_values : {};
+  const images = Object.entries(bindings).flatMap(([key, value]) => {
+    // Select a single preview, excluding site icons and unrelated card assets.
+    if (!/^(photo_image_full_size|summary_photo_image|thumbnail_image)(_(original|x_large|large|small))?$/.test(key)
+      || !object(value) || !object(value.image_value)) return [];
+    const image = value.image_value;
+    const rawUrl = string(image.url);
+    if (!rawUrl) return [];
+    try {
+      const url = new URL(rawUrl);
+      if (url.protocol !== "https:" && url.protocol !== "http:") return [];
+      const format = (url.searchParams.get("format") ?? url.pathname.match(/\.(jpe?g|png|webp|gif)$/i)?.[1] ?? "jpg").toLowerCase();
+      const extension = format === "jpeg" ? "jpg" : format;
+      if (!["jpg", "png", "webp", "gif"].includes(extension)) return [];
+      return [{
+        url: url.href, extension,
+        original: key.endsWith("_original") ? 1 : 0,
+        area: Math.max(0, number(image.width) ?? 0) * Math.max(0, number(image.height) ?? 0),
+      }];
+    } catch {
+      return [];
+    }
+  }).sort((a, b) => b.original - a.original || b.area - a.area);
+  const image = images[0];
+  return image ? {
+    filename: filename(`twitter_${id}_preview.${image.extension}`),
+    headers: { "user-agent": browserUserAgent() },
+    id, kind: "image", mime: `image/${image.extension === "jpg" ? "jpeg" : image.extension}`,
+    platform: "twitter", role: "linkPreview", url: image.url,
+  } : null;
+}
+
 function videoVariants(entry: Json): Array<{ bitrate: number; url: string }> {
   const info = object(entry.video_info) ? entry.video_info : null;
   const variants = info && Array.isArray(info.variants) ? info.variants.filter(object) : [];