@postfetch/core 0.2.0

package/dist/instagram.d.ts

@@ -0,0 +1,2 @@
+import { type ResolveContext, type PostfetchResult } from "./internal";
+export declare function resolveInstagram(input: ResolveContext): Promise<PostfetchResult>;

package/dist/internal.d.ts

@@ -0,0 +1,34 @@
+export type Platform = "facebook" | "instagram" | "tiktok" | "twitter" | "youtube";
+export type MediaKind = "audio" | "image" | "video";
+export type MediaItem = {
+    filename: string;
+    headers: HeadersInit;
+    id: string;
+    kind: MediaKind;
+    mime: string;
+    platform: Platform;
+    url: string;
+};
+export type PostfetchResult = {
+    archiveFilename: string;
+    id: string;
+    items: MediaItem[];
+    platform: Platform;
+};
+export type Net = (url: string, init?: RequestInit, attempts?: number) => Promise<Response>;
+export type ResolveContext = {
+    net: Net;
+    preferredWidth: number;
+    url: string;
+};
+export declare class PostfetchError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export type Json = Record<string, unknown>;
+export declare function createNet(baseFetch?: typeof fetch): Net;
+export declare function object(value: unknown): value is Json;
+export declare function string(value: unknown): string | null;
+export declare function number(value: unknown): number | null;
+export declare function asUrl(value: string): URL;
+export declare function filename(value: string): string;

package/dist/postfetch.d.ts

@@ -0,0 +1,7 @@
+import { type Platform, type PostfetchResult } from "./internal";
+export type PostfetchOptions = {
+    fetch?: typeof fetch;
+    preferredWidth?: number;
+};
+export declare function postfetch(url: string, options?: PostfetchOptions): Promise<PostfetchResult>;
+export declare function detect(url: string): Platform;

package/dist/tiktok.d.ts

@@ -0,0 +1,2 @@
+import { type ResolveContext, type PostfetchResult } from "./internal";
+export declare function resolveTiktok(input: ResolveContext): Promise<PostfetchResult>;

package/dist/twitter.d.ts

@@ -0,0 +1,2 @@
+import { type ResolveContext, type PostfetchResult } from "./internal";
+export declare function resolveTwitter(input: ResolveContext): Promise<PostfetchResult>;

package/dist/youtube.d.ts

@@ -0,0 +1,3 @@
+import { type ResolveContext, type PostfetchResult } from "./internal";
+export declare function resolveYoutube(input: ResolveContext): Promise<PostfetchResult>;
+export declare function youtubeVideoId(input: string): string | null;

package/dist/zip.d.ts

@@ -0,0 +1,5 @@
+export type ZipEntry = {
+    data: Uint8Array;
+    name: string;
+};
+export declare function zip(entries: ZipEntry[]): Uint8Array;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@postfetch/core",
+  "version": "0.2.0",
+  "description": "Zero-dependency typed core that turns Facebook, Instagram, TikTok, X and YouTube post URLs into media files.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chelokot/postfetch.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/chelokot/postfetch/tree/main/packages/core#readme",
+  "keywords": [
+    "cobalt",
+    "downloader",
+    "facebook",
+    "instagram",
+    "media",
+    "tiktok",
+    "twitter",
+    "youtube",
+    "zero-dependency"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/download.ts

@@ -0,0 +1,74 @@
+import { createNet, PostfetchError, type MediaItem, type PostfetchResult } from "./internal";
+import { zip } from "./zip";
+
+export type DownloadOptions = {
+  fetch?: typeof fetch;
+};
+
+export type Archive = {
+  bytes: Uint8Array;
+  filename: string;
+  mime: "application/zip";
+};
+
+export async function download(item: MediaItem, options: DownloadOptions = {}): Promise<Response> {
+  const net = createNet(options.fetch ?? globalThis.fetch);
+  const response = await net(item.url, { headers: item.headers });
+  if (!response.ok || !response.body) {
+    throw new PostfetchError(502, `download failed: ${response.status}`);
+  }
+  return response;
+}
+
+export async function archive(result: PostfetchResult, options: DownloadOptions = {}): Promise<Archive> {
+  const net = createNet(options.fetch ?? globalThis.fetch);
+  const files = await Promise.all(
+    result.items.map(async (item) => {
+      const response = await net(item.url, { headers: item.headers });
+      if (!response.ok) {
+        throw new PostfetchError(502, `download failed: ${response.status}`);
+      }
+      return { data: new Uint8Array(await response.arrayBuffer()), name: item.filename };
+    }),
+  );
+  return { bytes: zip(files), filename: result.archiveFilename, mime: "application/zip" };
+}
+
+export async function toResponse(result: PostfetchResult, options: DownloadOptions = {}): Promise<Response> {
+  if (result.items.length === 1) {
+    return singleResponse(result.items[0], options);
+  }
+  return archiveResponse(result, options);
+}
+
+async function singleResponse(item: MediaItem, options: DownloadOptions): Promise<Response> {
+  const media = await download(item, options);
+  const headers = new Headers({
+    "content-disposition": `attachment; filename="${item.filename}"`,
+    "content-type": media.headers.get("content-type") ?? item.mime,
+    "x-media-count": "1",
+    "x-media-id": item.id,
+    "x-media-kind": item.kind,
+    "x-media-platform": item.platform,
+  });
+  const length = media.headers.get("content-length");
+  if (length) {
+    headers.set("content-length", length);
+  }
+  return new Response(media.body, { headers });
+}
+
+async function archiveResponse(result: PostfetchResult, options: DownloadOptions): Promise<Response> {
+  const { bytes, filename } = await archive(result, options);
+  const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+  return new Response(body, {
+    headers: {
+      "content-disposition": `attachment; filename="${filename}"`,
+      "content-length": String(bytes.length),
+      "content-type": "application/zip",
+      "x-media-count": String(result.items.length),
+      "x-media-id": result.id,
+      "x-media-platform": result.platform,
+    },
+  });
+}

package/src/facebook.ts

@@ -0,0 +1,73 @@
+import { asUrl, filename, 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 id = facebookId(canonical) ?? facebookId(input.url) ?? "video";
+  const url = await embedVideo(input.net, canonical);
+  if (!url) {
+    throw new Error("Facebook video not found");
+  }
+  const item: MediaItem = {
+    filename: filename(`facebook_${id}.mp4`),
+    headers: { "user-agent": browserUserAgent() },
+    id,
+    kind: "video",
+    mime: "video/mp4",
+    platform: "facebook",
+    url,
+  };
+  return { archiveFilename: filename(`facebook_${id}.zip`), id, items: [item], platform: "facebook" };
+}
+
+function navigationHeaders(): Record<string, string> {
+  return {
+    "accept-language": "en-US,en;q=0.9",
+    "sec-fetch-mode": "navigate",
+    "user-agent": browserUserAgent(),
+  };
+}
+
+// Share and fb.watch links redirect to the canonical /reel/<id> or /<page>/videos/<id>
+// URL, which the public embed player needs. We only read the resolved location, not the
+// (login-walled) page body.
+async function canonicalUrl(net: Net, input: string): Promise<string> {
+  const response = await net(input, { headers: navigationHeaders() });
+  const resolved = asUrl(response.url);
+  return `${resolved.origin}${resolved.pathname}`;
+}
+
+// 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> {
+  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");
+}
+
+function source(html: string, key: string): string | null {
+  const match = html.match(new RegExp(`"${key}":("(?:\\\\.|[^"\\\\])*")`));
+  if (!match) {
+    return null;
+  }
+  const decoded: Json | string | null = JSON.parse(match[1]);
+  return typeof decoded === "string" && decoded.length > 0 ? decoded : null;
+}
+
+function facebookId(input: string): string | null {
+  const url = asUrl(input);
+  const fromQuery = url.searchParams.get("v");
+  if (fromQuery && /^\d+$/.test(fromQuery)) {
+    return fromQuery;
+  }
+  const numeric = url.pathname.match(/\/(?:reel|videos?|watch)\/(\d+)/);
+  if (numeric) {
+    return numeric[1];
+  }
+  const token = url.pathname.match(/\/(?:share\/[a-z]\/|posts\/|videos\/)?([A-Za-z0-9]+)\/?$/);
+  return token ? token[1] : null;
+}

package/src/fingerprint.ts

@@ -0,0 +1,75 @@
+// Every outbound request rotates a fresh, internally-consistent client fingerprint.
+// A single hardcoded user-agent / header set is the fastest way to get the whole
+// fleet blocked at once, so each component is drawn from a pool and the pieces are
+// kept consistent with each other (a Chrome UA always carries a matching Chrome
+// `sec-ch-ua` and the right platform token).
+
+function pick<Value>(values: readonly Value[]): Value {
+  return values[Math.floor(Math.random() * values.length)] as Value;
+}
+
+const chromeVersions = ["128", "129", "130", "131", "132", "133"] as const;
+const firefoxVersions = ["140", "143", "146", "148"] as const;
+
+const desktopPlatforms = [
+  { chPlatform: "Windows", uaToken: "Windows NT 10.0; Win64; x64" },
+  { chPlatform: "macOS", uaToken: "Macintosh; Intel Mac OS X 10_15_7" },
+  { chPlatform: "Linux", uaToken: "X11; Linux x86_64" },
+] as const;
+
+const acceptLanguages = ["en-US,en;q=0.9", "en-GB,en;q=0.9", "en;q=0.9", "en-US,en;q=0.8"] as const;
+
+const instagramAppUserAgents = [
+  "Instagram 275.0.0.27.98 Android (33/13; 280dpi; 720x1423; Xiaomi; Redmi 7; onclite; qcom; en_US; 458229237)",
+  "Instagram 301.1.0.33.110 Android (34/14; 420dpi; 1080x2340; samsung; SM-G991B; o1s; exynos2100; en_US; 521879118)",
+  "Instagram 309.0.0.40.113 Android (33/13; 440dpi; 1080x2280; OnePlus; HD1913; OnePlus7TPro; qcom; en_US; 537291984)",
+] as const;
+
+export type BrowserFingerprint = {
+  acceptLanguage: string;
+  secChUa: string;
+  secChUaPlatform: string;
+  userAgent: string;
+};
+
+export function browserFingerprint(): BrowserFingerprint {
+  const version = pick(chromeVersions);
+  const platform = pick(desktopPlatforms);
+  return {
+    acceptLanguage: pick(acceptLanguages),
+    secChUa: `"Chromium";v="${version}", "Google Chrome";v="${version}", "Not_A Brand";v="24"`,
+    secChUaPlatform: `"${platform.chPlatform}"`,
+    userAgent: `Mozilla/5.0 (${platform.uaToken}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${version}.0.0.0 Safari/537.36`,
+  };
+}
+
+export function navigationHeaders(): Record<string, string> {
+  const fingerprint = browserFingerprint();
+  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,
+    "sec-fetch-dest": "document",
+    "sec-fetch-mode": "navigate",
+    "sec-fetch-site": "none",
+    "sec-fetch-user": "?1",
+    "upgrade-insecure-requests": "1",
+    "user-agent": fingerprint.userAgent,
+  };
+}
+
+export function browserUserAgent(): string {
+  return browserFingerprint().userAgent;
+}
+
+export function firefoxUserAgent(): string {
+  const platform = pick(desktopPlatforms);
+  const version = pick(firefoxVersions);
+  return `Mozilla/5.0 (${platform.uaToken}; rv:${version}.0) Gecko/20100101 Firefox/${version}.0`;
+}
+
+export function instagramAppUserAgent(): string {
+  return pick(instagramAppUserAgents);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { postfetch, detect, type PostfetchOptions } from "./postfetch";
+export { download, archive, toResponse, type Archive, type DownloadOptions } from "./download";
+export { PostfetchError } from "./internal";
+export type { MediaItem, MediaKind, Platform, PostfetchResult } from "./internal";