@postfetch/core 0.5.2 → 0.7.0

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
 /** A platform that {@link postfetch} can resolve. */
-export type Platform = "facebook" | "instagram" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
+export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "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. */
@@ -99,6 +99,17 @@ export type TiktokExtra = {
 export type TwitterExtra = {
     /** BCP 47 language tag detected for the tweet. */
     lang?: string;
+    /** The post quoted by this post, when X includes it in the resolved payload. */
+    quotedTweet?: TwitterQuotedTweet;
+};
+/** A quoted X post and its normalized metadata. */
+export type TwitterQuotedTweet = {
+    /** Status id of the quoted post. */
+    id: string;
+    /** Metadata belonging to the quoted post rather than the outer post. */
+    metadata: PostMetadata & {
+        extra?: TwitterExtra;
+    };
 };
 /** Instagram-specific metadata. */
 export type InstagramExtra = {
@@ -137,7 +148,7 @@ export type PinterestExtra = {
     outboundLink?: string;
 };
 /** The result of resolving a post: its platform, id, media items and metadata. */
-export type PostfetchResult = PlatformResult<"facebook", never> | PlatformResult<"instagram", InstagramExtra> | 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<"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/linkedin.d.ts

@@ -0,0 +1,3 @@
+import { type Json, type PostMetadata, type PostfetchResult, type ResolveContext } from "./internal";
+export declare function resolveLinkedin(input: ResolveContext): Promise<PostfetchResult>;
+export declare function linkedinMetadata(post: Json): PostMetadata;

package/dist/postfetch.d.ts

@@ -5,16 +5,24 @@ export type PostfetchOptions = {
     fetch?: typeof fetch;
     /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
     preferredWidth?: number;
+    /**
+     * Soft file-size cap in bytes. The normal rendition is resolved and probed
+     * with HEAD; when it exceeds the cap, a smaller available rendition is
+     * returned. If size discovery or the smaller rendition is unavailable, the
+     * normal result is returned unchanged.
+     */
+    tryMaxBytes?: number;
 };
 /**
  * Resolve a public social post URL to its media.
  *
  * Detects the platform from the URL host, then returns the post's media as typed
  * {@link MediaItem}s — direct CDN URLs plus the headers needed to fetch them. It
- * performs no side effects beyond the lookup; use {@link download}, {@link archive}
- * or {@link toResponse} to turn the result into bytes or a `Response`.
+ * performs no side effects beyond the lookup; use {@link download},
+ * {@link downloadBlob}, {@link archive} or {@link toResponse} to turn the result
+ * into bytes, a `Blob` or a `Response`.
  *
- * @param url A post URL from Instagram, TikTok, YouTube, Facebook or X.
+ * @param url A post URL from a supported platform.
  * @param options See {@link PostfetchOptions}.
  * @returns The resolved post and its media items.
  * @throws {PostfetchError} If the URL is empty or its host is unsupported.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@postfetch/core",
-  "version": "0.5.2",
-  "description": "Zero-dependency typed core that turns Facebook, Instagram, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
+  "version": "0.7.0",
+  "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -30,6 +30,7 @@
     "downloader",
     "facebook",
     "instagram",
+    "linkedin",
     "media",
     "pinterest",
     "reddit",

package/src/download.ts

@@ -54,6 +54,38 @@ export async function download(item: MediaItem, options: DownloadOptions = {}):
   return response;
 }
 
+/**
+ * Download an already-resolved media URL as a Blob.
+ *
+ * This is useful for consumers that need to upload media themselves instead of
+ * passing its URL to a third party. When the resolved {@link MediaItem} carries
+ * required CDN headers, pass them as the second argument.
+ *
+ * @param url A direct media URL returned by a resolver.
+ * @param headers Headers required by the resolved media URL.
+ * @param options Fetch options.
+ * @returns The downloaded media as a Blob.
+ *
+ * @example Upload a video with FormData
+ * ```ts
+ * const [media] = (await postfetch(sourceUrl)).items;
+ * const blob = await downloadBlob(media.url, media.headers);
+ * form.append("video", blob, media.filename);
+ * ```
+ */
+export async function downloadBlob(
+  url: string,
+  headers: HeadersInit = {},
+  options: DownloadOptions = {},
+): Promise<Blob> {
+  const net = createNet(options.fetch ?? globalThis.fetch);
+  const response = await net(url, { headers });
+  if (!response.ok || !response.body) {
+    throw new PostfetchError(502, `download failed: ${response.status}`);
+  }
+  return response.blob();
+}
+
 /**
  * Download every item of a result and zip them in-process (store mode).
  *

package/src/facebook.ts

@@ -1,16 +1,16 @@
-import { asUrl, count, filename, isoFromEpochSeconds, type PostMetadata, type ResolveContext, type Json, type Net, type PostfetchResult, type MediaItem } from "./internal";
+import { asUrl, count, filename, isoFromEpochSeconds, PostfetchError, type PostMetadata, type ResolveContext, type Json, type Net, type PostfetchResult, type MediaItem } from "./internal";
 import { browserUserAgent } from "./fingerprint";
 
 export async function resolveFacebook(input: ResolveContext): Promise<PostfetchResult> {
-  const canonical = await canonicalUrl(input.net, input.url);
+  const canonical = await canonicalUrl(input.net, normalizedInputUrl(input.url));
   const id = facebookId(canonical) ?? facebookId(input.url) ?? "video";
   // The embed player only exposes /share/v/ videos; reels (and anything it
   // misses) come from the watch page, which the &_rdr flag serves logged-out.
-  const embed = await embedVideo(input.net, canonical);
-  const watch = !embed && /^\d+$/.test(id) ? await watchVideo(input.net, id) : null;
+  const embed = await embedVideo(input.net, canonical, input.preferredWidth);
+  const watch = !embed && /^\d+$/.test(id) ? await watchVideo(input.net, id, input.preferredWidth) : null;
   const url = embed ?? watch?.url ?? null;
   if (!url) {
-    throw new Error("Facebook video not found");
+    throw new PostfetchError(404, "Facebook video not found", "notFound");
   }
   const item: MediaItem = {
     filename: filename(`facebook_${id}.mp4`),
@@ -24,6 +24,16 @@ export async function resolveFacebook(input: ResolveContext): Promise<PostfetchR
   return { archiveFilename: filename(`facebook_${id}.zip`), id, items: [item], metadata: watch?.metadata, platform: "facebook" };
 }
 
+// Facebook share links are opaque shortlinks. Messaging apps sometimes append
+// selected text to the copied URL as another path segment; Facebook returns 404
+// for that form even though the share token is still intact. Strip everything
+// after the token before following the redirect.
+function normalizedInputUrl(input: string): string {
+  const url = asUrl(input);
+  const share = url.pathname.match(/^\/share\/([a-z])\/([A-Za-z0-9]+)/i);
+  return share ? `${url.origin}/share/${share[1]}/${share[2]}/` : input;
+}
+
 function navigationHeaders(): Record<string, string> {
   return {
     "accept-language": "en-US,en;q=0.9",
@@ -43,19 +53,19 @@ async function canonicalUrl(net: Net, input: string): Promise<string> {
 
 // The logged-out watch page is fingerprint-walled, but the public embed player
 // (plugins/video.php) still exposes the progressive hd_src/sd_src URLs.
-async function embedVideo(net: Net, canonical: string): Promise<string | null> {
+async function embedVideo(net: Net, canonical: string, preferredWidth: number): Promise<string | null> {
   const embed = `https://www.facebook.com/plugins/video.php?href=${encodeURIComponent(canonical)}`;
   const response = await net(embed, { headers: navigationHeaders() });
   if (!response.ok) {
     return null;
   }
   const html = await response.text();
-  return source(html, "hd_src") ?? source(html, "sd_src");
+  return preferredSource(preferredWidth, source(html, "hd_src"), source(html, "sd_src"));
 }
 
 // The logged-out watch page (with &_rdr) embeds the progressive video URLs in
 // its ScheduledServerJS blocks; these are the same fields yt-dlp reads.
-async function watchVideo(net: Net, id: string): Promise<{ url: string; metadata: PostMetadata } | null> {
+async function watchVideo(net: Net, id: string, preferredWidth: number): Promise<{ url: string; metadata: PostMetadata } | null> {
   // Without the document Accept header Facebook serves a JS shell without the
   // media JSON, so ask for HTML explicitly here.
   const headers = { ...navigationHeaders(), accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" };
@@ -64,14 +74,18 @@ async function watchVideo(net: Net, id: string): Promise<{ url: string; metadata
     return null;
   }
   const html = await response.text();
-  const url =
-    source(html, "playable_url_quality_hd") ??
-    source(html, "browser_native_hd_url") ??
-    source(html, "playable_url") ??
-    source(html, "browser_native_sd_url");
+  const hd = source(html, "playable_url_quality_hd") ?? source(html, "browser_native_hd_url");
+  const sd = source(html, "playable_url") ?? source(html, "browser_native_sd_url");
+  const url = preferredSource(preferredWidth, hd, sd);
   return url ? { url, metadata: watchMetadata(html) } : null;
 }
 
+// Facebook labels its two progressive renditions as 720p HD and 360p SD. Pick
+// the one closest to the requested width, preferring HD on the 540px midpoint.
+function preferredSource(preferredWidth: number, hd: string | null, sd: string | null): string | null {
+  return preferredWidth >= 540 ? hd ?? sd : sd ?? hd;
+}
+
 // Only the fields that can be read unambiguously from the flat page: the
 // caption (creation_story) and the reaction/comment/share counts appear in
 // shapes shared with related videos and comment threads, so they are skipped

package/src/fingerprint.ts

@@ -32,6 +32,10 @@ export type BrowserFingerprint = {
   userAgent: string;
 };
 
+export type NavigationHeaders = Record<string, string> & {
+  "user-agent": string;
+};
+
 export function browserFingerprint(): BrowserFingerprint {
   const version = pick(chromeVersions);
   const platform = pick(desktopPlatforms);
@@ -43,20 +47,26 @@ export function browserFingerprint(): BrowserFingerprint {
   };
 }
 
-export function navigationHeaders(): Record<string, string> {
-  const fingerprint = browserFingerprint();
+function baseNavigationHeaders(userAgent: string, acceptLanguage: string): NavigationHeaders {
   return {
     accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
-    "accept-language": fingerprint.acceptLanguage,
-    "sec-ch-ua": fingerprint.secChUa,
-    "sec-ch-ua-mobile": "?0",
-    "sec-ch-ua-platform": fingerprint.secChUaPlatform,
+    "accept-language": acceptLanguage,
     "sec-fetch-dest": "document",
     "sec-fetch-mode": "navigate",
     "sec-fetch-site": "none",
     "sec-fetch-user": "?1",
     "upgrade-insecure-requests": "1",
-    "user-agent": fingerprint.userAgent,
+    "user-agent": userAgent,
+  };
+}
+
+export function navigationHeaders(): NavigationHeaders {
+  const fingerprint = browserFingerprint();
+  return {
+    ...baseNavigationHeaders(fingerprint.userAgent, fingerprint.acceptLanguage),
+    "sec-ch-ua": fingerprint.secChUa,
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": fingerprint.secChUaPlatform,
   };
 }
 
@@ -70,6 +80,10 @@ export function firefoxUserAgent(): string {
   return `Mozilla/5.0 (${platform.uaToken}; rv:${version}.0) Gecko/20100101 Firefox/${version}.0`;
 }
 
+export function firefoxNavigationHeaders(userAgent = firefoxUserAgent()): NavigationHeaders {
+  return baseNavigationHeaders(userAgent, pick(acceptLanguages));
+}
+
 export function instagramAppUserAgent(): string {
   return pick(instagramAppUserAgents);
 }

package/src/index.ts

@@ -1,12 +1,12 @@
 /**
  * Turn a public social post URL into its media.
  *
- * {@link postfetch} resolves Instagram, TikTok, YouTube, Facebook and X (Twitter)
+ * {@link postfetch} resolves Instagram, LinkedIn, TikTok, YouTube, Facebook and X (Twitter)
  * URLs to typed {@link MediaItem}s. 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 archive} and {@link toResponse} helpers turn a result
- * into bytes or a `Response`.
+ * {@link download}, {@link downloadBlob}, {@link archive} and {@link toResponse}
+ * helpers turn a result into bytes, a `Blob`, or a `Response`.
  *
  * @example Resolve a reel and save the video
  * ```ts
@@ -20,7 +20,14 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
-export { download, archive, toResponse, type Archive, type DownloadOptions } from "./download";
+export {
+  download,
+  downloadBlob,
+  archive,
+  toResponse,
+  type Archive,
+  type DownloadOptions,
+} from "./download";
 export { PostfetchError } from "./internal";
 export type {
   InstagramExtra,
@@ -37,5 +44,6 @@ export type {
   SoundcloudExtra,
   TiktokExtra,
   TwitterExtra,
+  TwitterQuotedTweet,
   YoutubeExtra,
 } from "./internal";

package/src/instagram.ts

@@ -58,11 +58,21 @@ function embedHeaders(): Record<string, string> {
 
 export async function resolveInstagram(input: ResolveContext): Promise<PostfetchResult> {
   const code = shortcode(input.url);
-  const media =
-    (await pageMedia(input.net, code, input.preferredWidth)) ??
-    (await mobileMedia(input.net, code, input.preferredWidth)) ??
-    (await embedMedia(input.net, code)) ??
-    (await graphqlMedia(input.net, code));
+  const videoRequired = /\/(?:reel|reels|tv)\//.test(asUrl(input.url).pathname);
+  const resolvers: Array<() => Promise<Json | null>> = [
+    () => pageMedia(input.net, code, input.preferredWidth),
+    () => mobileMedia(input.net, code, input.preferredWidth),
+    () => embedMedia(input.net, code),
+    () => graphqlMedia(input.net, code),
+  ];
+  let media: Json | null = null;
+  for (const resolve of resolvers) {
+    const candidate = await resolve();
+    if (candidate && (!videoRequired || mediaItems(candidate, code, input.preferredWidth).some((item) => item.kind === "video"))) {
+      media = candidate;
+      break;
+    }
+  }
   if (!media) {
     throw await instagramUnavailable(input.net, code);
   }
@@ -301,23 +311,20 @@ async function graphqlMedia(net: Net, code: string): Promise<Json | null> {
   }
   const body = new URLSearchParams({
     ...params.body,
-    doc_id: "8845758582119845",
+    av: "0",
+    doc_id: "26130443479876713",
     fb_api_caller_class: "RelayModern",
-    fb_api_req_friendly_name: "PolarisPostActionLoadPostQueryQuery",
+    fb_api_req_friendly_name: "PolarisPostRootQuery",
     server_timestamps: "true",
-    variables: JSON.stringify({
-      fetch_tagged_user_count: null,
-      hoisted_comment_id: null,
-      hoisted_reply_id: null,
-      shortcode: code,
-    }),
+    variables: JSON.stringify({ shortcode: code }),
   });
   const response = await net("https://www.instagram.com/graphql/query", {
     body,
     headers: {
       ...embedHeaders(),
       ...params.headers,
-      "X-FB-Friendly-Name": "PolarisPostActionLoadPostQueryQuery",
+      "X-FB-Friendly-Name": "PolarisPostRootQuery",
+      "X-Requested-With": "XMLHttpRequest",
       "content-type": "application/x-www-form-urlencoded",
     },
     method: "POST",
@@ -344,14 +351,14 @@ async function graphqlParams(net: Net, code: string): Promise<{ body: Record<str
   const push = entryObject("InstagramWebPushInfo", html);
   const lsd = entryObject("LSD", html)?.token ?? randomToken();
   const csrf = entryObject("InstagramSecurityConfig", html)?.csrf_token;
-  const cookie = [
-    csrf && `csrftoken=${csrf}`,
-    polaris?.device_id && `ig_did=${polaris.device_id}`,
-    polaris?.machine_id && `mid=${polaris.machine_id}`,
-    "wd=1280x720",
-    "dpr=2",
-    "ig_nrcb=1",
-  ].filter((value): value is string => typeof value === "string" && value.length > 0).join("; ");
+  const cookie = instagramCookies(response.headers, {
+    csrftoken: string(csrf),
+    dpr: "2",
+    ig_did: string(polaris?.device_id),
+    ig_nrcb: "1",
+    mid: string(polaris?.machine_id),
+    wd: "1280x720",
+  });
   return {
     headers: {
       "X-CSRFToken": string(csrf) ?? "",
@@ -386,6 +393,12 @@ async function graphqlParams(net: Net, code: string): Promise<{ body: Record<str
 }
 
 function gqlShortcodeMedia(data: Json): Json | null {
+  const webInfo = object(data.xdt_api__v1__media__shortcode__web_info) ? data.xdt_api__v1__media__shortcode__web_info : null;
+  const webItems = webInfo && Array.isArray(webInfo.items) ? webInfo.items : [];
+  const webMedia = webItems[0];
+  if (object(webMedia)) {
+    return webMedia;
+  }
   const media = data.gql_data && object(data.gql_data)
     ? data.gql_data.shortcode_media ?? data.gql_data.xdt_shortcode_media
     : data.shortcode_media ?? data.xdt_shortcode_media;
@@ -411,6 +424,25 @@ function mediaItems(media: Json, code: string, preferredWidth: number): MediaIte
   return instagramItem(media, code, null, preferredWidth);
 }
 
+function instagramCookies(headers: Headers, fallback: Record<string, string | null>): string {
+  const getter = (headers as Headers & { getSetCookie?: () => string[] }).getSetCookie;
+  const raw = typeof getter === "function" ? getter.call(headers) : headers.get("set-cookie")?.split(/,(?=[^;]+?=)/) ?? [];
+  const cookies = new Map<string, string>();
+  for (const value of raw) {
+    const pair = value.split(";", 1)[0]?.trim();
+    const separator = pair?.indexOf("=") ?? -1;
+    if (pair && separator > 0) {
+      cookies.set(pair.slice(0, separator), pair.slice(separator + 1));
+    }
+  }
+  for (const [name, value] of Object.entries(fallback)) {
+    if (value && !cookies.has(name)) {
+      cookies.set(name, value);
+    }
+  }
+  return [...cookies].map(([name, value]) => `${name}=${value}`).join("; ");
+}
+
 function instagramItem(media: Json, code: string, index: number | null, preferredWidth: number): MediaItem[] {
   const video = selectVersion(media.video_versions, preferredWidth) ?? string(media.video_url);
   const suffix = index === null ? "" : `_${index}`;

package/src/internal.ts

@@ -1,5 +1,5 @@
 /** A platform that {@link postfetch} can resolve. */
-export type Platform = "facebook" | "instagram" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
+export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
 
 /** The kind of a {@link MediaItem}. */
 export type MediaKind = "audio" | "image" | "video";
@@ -103,6 +103,16 @@ export type TiktokExtra = {
 export type TwitterExtra = {
   /** BCP 47 language tag detected for the tweet. */
   lang?: string;
+  /** The post quoted by this post, when X includes it in the resolved payload. */
+  quotedTweet?: TwitterQuotedTweet;
+};
+
+/** A quoted X post and its normalized metadata. */
+export type TwitterQuotedTweet = {
+  /** Status id of the quoted post. */
+  id: string;
+  /** Metadata belonging to the quoted post rather than the outer post. */
+  metadata: PostMetadata & { extra?: TwitterExtra };
 };
 
 /** Instagram-specific metadata. */
@@ -149,6 +159,7 @@ export type PinterestExtra = {
 export type PostfetchResult =
   | PlatformResult<"facebook", never>
   | PlatformResult<"instagram", InstagramExtra>
+  | PlatformResult<"linkedin", never>
   | PlatformResult<"pinterest", PinterestExtra>
   | PlatformResult<"reddit", RedditExtra>
   | PlatformResult<"soundcloud", SoundcloudExtra>