@postfetch/core 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -22,4 +22,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";
+export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, YoutubeExtra, } from "./internal";

package/dist/index.js

@@ -1,9 +1,11 @@
 // src/internal.ts
 class PostfetchError extends Error {
   status;
-  constructor(status, message) {
+  reason;
+  constructor(status, message, reason) {
     super(message);
     this.status = status;
+    this.reason = reason;
     this.name = "PostfetchError";
   }
 }
@@ -41,6 +43,29 @@ function string(value) {
 function number(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function bool(value) {
+  return typeof value === "boolean" ? value : undefined;
+}
+function count(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+    return value;
+  }
+  if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+    return Number(value.trim());
+  }
+  return;
+}
+function isoFromEpochSeconds(value) {
+  const seconds = count(value);
+  return seconds === undefined ? undefined : new Date(seconds * 1000).toISOString();
+}
+function isoFromDateString(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? undefined : new Date(time).toISOString();
+}
 function asUrl(value) {
   try {
     return new URL(value);
@@ -227,13 +252,89 @@ async function resolveInstagram(input) {
   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);
   if (!media) {
-    throw new Error("Instagram media not found");
+    throw await instagramUnavailable(input.net, code);
   }
   const items = mediaItems(media, code, input.preferredWidth);
   if (items.length === 0) {
     throw new Error("Instagram media url not found");
   }
-  return { archiveFilename: filename(`instagram_${code}.zip`), id: code, items, platform: "instagram" };
+  return { archiveFilename: filename(`instagram_${code}.zip`), id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
+}
+async function instagramUnavailable(net, code) {
+  const url = new URL("https://i.instagram.com/api/v1/oembed/");
+  url.searchParams.set("url", `https://www.instagram.com/p/${code}/`);
+  const response = await net(url.href, { headers: mobileHeaders() }, 1).catch(() => null);
+  const body = response ? await response.text().catch(() => "") : "";
+  const reason = instagramUnavailableReason(response?.status ?? 0, body);
+  return new PostfetchError(reasonStatus(reason), `Instagram post unavailable: ${reason}`, reason);
+}
+function instagramUnavailableReason(status, body) {
+  if (status === 404) {
+    return "notFound";
+  }
+  if (status !== 0 && status < 400) {
+    return "unavailable";
+  }
+  if (/MIN_AGE_ACCOUNT|under 18/i.test(body)) {
+    return "ageRestricted";
+  }
+  if (/private account|"is_private":\s*true|account is private/i.test(body)) {
+    return "private";
+  }
+  if (/log in|login_required|not logged/i.test(body)) {
+    return "loginRequired";
+  }
+  return "unavailable";
+}
+function reasonStatus(reason) {
+  switch (reason) {
+    case "ageRestricted":
+      return 451;
+    case "private":
+      return 403;
+    case "loginRequired":
+      return 401;
+    case "rateLimited":
+      return 429;
+    default:
+      return 404;
+  }
+}
+function instagramMetadata(media) {
+  const user = object(media.user) ? media.user : object(media.owner) ? media.owner : null;
+  const countsHidden = bool(media.like_and_view_counts_disabled);
+  return {
+    text: instagramCaption(media),
+    author: user ? {
+      handle: string(user.username) ?? undefined,
+      name: string(user.full_name) ?? undefined,
+      verified: bool(user.is_verified)
+    } : undefined,
+    createdAt: isoFromEpochSeconds(media.taken_at ?? media.taken_at_timestamp),
+    likeCount: countsHidden ? undefined : count(media.like_count) ?? edgeCount(media.edge_media_preview_like) ?? edgeCount(media.edge_liked_by),
+    commentCount: count(media.comment_count) ?? edgeCount(media.edge_media_to_comment) ?? edgeCount(media.edge_media_to_parent_comment),
+    viewCount: countsHidden ? undefined : count(media.play_count) ?? count(media.view_count) ?? count(media.video_view_count),
+    extra: {
+      productType: string(media.product_type) ?? undefined,
+      countsHidden,
+      location: object(media.location) ? string(media.location.name) ?? undefined : undefined
+    }
+  };
+}
+function instagramCaption(media) {
+  if (object(media.caption)) {
+    return string(media.caption.text) ?? undefined;
+  }
+  const direct = string(media.caption);
+  if (direct) {
+    return direct;
+  }
+  const edges = object(media.edge_media_to_caption) && Array.isArray(media.edge_media_to_caption.edges) ? media.edge_media_to_caption.edges : [];
+  const node = object(edges[0]) && object(edges[0].node) ? edges[0].node : null;
+  return node ? string(node.text) ?? undefined : undefined;
+}
+function edgeCount(value) {
+  return object(value) ? count(value.count) : undefined;
 }
 function shortcode(input) {
   const path = asUrl(input).pathname.split("/").filter(Boolean);
@@ -692,7 +793,24 @@ async function resolvePinterest(input) {
   if (items.length === 0) {
     throw new Error("Pinterest media not found");
   }
-  return { archiveFilename: filename(`pinterest_${id}.zip`), id, items, platform: "pinterest" };
+  return { archiveFilename: filename(`pinterest_${id}.zip`), id, items, metadata: pinterestMetadata(pin), platform: "pinterest" };
+}
+function pinterestMetadata(pin) {
+  const pinner = object(pin.pinner) ? pin.pinner : null;
+  const reactions = object(pin.reaction_counts) ? Object.values(pin.reaction_counts).reduce((sum, value) => sum + (count(value) ?? 0), 0) : undefined;
+  return {
+    title: string(pin.title) ?? string(pin.grid_title) ?? undefined,
+    text: string(pin.description) ?? undefined,
+    author: pinner ? { handle: string(pinner.username) ?? undefined, name: string(pinner.full_name) ?? undefined } : undefined,
+    createdAt: isoFromDateString(pin.created_at),
+    likeCount: reactions,
+    commentCount: count(pin.comment_count),
+    extra: {
+      saveCount: count(pin.repin_count),
+      dominantColor: string(pin.dominant_color) ?? undefined,
+      outboundLink: string(pin.link) ?? undefined
+    }
+  };
 }
 async function pinId(net, input) {
   const direct = parsePin(input);
@@ -893,7 +1011,25 @@ async function resolveReddit(input) {
   if (items.length === 0) {
     throw new Error("Reddit media not found");
   }
-  return { archiveFilename: filename(`reddit_${id}.zip`), id, items, platform: "reddit" };
+  return { archiveFilename: filename(`reddit_${id}.zip`), id, items, metadata: redditMetadata(post), platform: "reddit" };
+}
+function redditMetadata(post) {
+  const author = string(post.author);
+  return {
+    title: string(post.title) ?? undefined,
+    text: string(post.selftext) ?? undefined,
+    author: author ? { handle: author } : undefined,
+    createdAt: isoFromEpochSeconds(post.created_utc),
+    likeCount: count(post.ups),
+    commentCount: count(post.num_comments),
+    nsfw: bool(post.over_18),
+    extra: {
+      subreddit: string(post.subreddit) ?? undefined,
+      score: number(post.score) ?? undefined,
+      upvoteRatio: number(post.upvote_ratio) ?? undefined,
+      permalink: string(post.permalink) ?? undefined
+    }
+  };
 }
 async function postId(net, input) {
   const direct = parseId(input);
@@ -1133,7 +1269,26 @@ async function resolveSoundcloud(input) {
   const track = await resolveTrack(input.net, url, clientId);
   const id = trackId(track);
   const item = await audioItem(input.net, track, id, clientId);
-  return { archiveFilename: filename(`soundcloud_${id}.zip`), id, items: [item], platform: "soundcloud" };
+  return { archiveFilename: filename(`soundcloud_${id}.zip`), id, items: [item], metadata: soundcloudMetadata(track), platform: "soundcloud" };
+}
+function soundcloudMetadata(track) {
+  const user = object(track.user) ? track.user : null;
+  const durationMs = count(track.duration);
+  return {
+    title: string(track.title) ?? undefined,
+    text: string(track.description) ?? undefined,
+    author: user ? { handle: string(user.username) ?? undefined, name: string(user.full_name) ?? undefined } : undefined,
+    createdAt: isoFromDateString(track.created_at),
+    likeCount: count(track.likes_count),
+    commentCount: count(track.comment_count),
+    shareCount: count(track.reposts_count),
+    viewCount: count(track.playback_count),
+    extra: {
+      genre: string(track.genre) ?? undefined,
+      license: string(track.license) ?? undefined,
+      durationSeconds: durationMs === undefined ? undefined : Math.round(durationMs / 1000)
+    }
+  };
 }
 async function canonicalUrl2(net, input) {
   const host = asUrl(input).hostname;
@@ -1255,7 +1410,33 @@ async function resolveTiktok(input) {
   if (items.length === 0) {
     throw new Error("TikTok media not found");
   }
-  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, platform: "tiktok" };
+  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
+}
+function tiktokMetadata(item) {
+  const user = object(item.author) ? item.author : null;
+  const stats = object(item.stats) ? item.stats : null;
+  const music = object(item.music) ? item.music : null;
+  const video = object(item.video) ? item.video : null;
+  return {
+    text: string(item.desc) ?? undefined,
+    author: user ? {
+      handle: string(user.uniqueId) ?? undefined,
+      name: string(user.nickname) ?? undefined,
+      verified: bool(user.verified)
+    } : undefined,
+    createdAt: isoFromEpochSeconds(item.createTime),
+    likeCount: stats ? count(stats.diggCount) : undefined,
+    commentCount: stats ? count(stats.commentCount) : undefined,
+    shareCount: stats ? count(stats.shareCount) : undefined,
+    viewCount: stats ? count(stats.playCount) : undefined,
+    extra: {
+      saveCount: stats ? count(stats.collectCount) : undefined,
+      musicTitle: music ? string(music.title) ?? undefined : undefined,
+      musicAuthor: music ? string(music.authorName) ?? undefined : undefined,
+      region: string(item.locationCreated) ?? undefined,
+      durationSeconds: video ? count(video.duration) : undefined
+    }
+  };
 }
 async function fetchVideoPage(net, id, userAgent) {
   const page = await net(`https://www.tiktok.com/@i/video/${id}`, {
@@ -1398,7 +1579,25 @@ async function resolveTwitter(input) {
   if (items.length === 0) {
     throw new Error("Twitter media not found");
   }
-  return { archiveFilename: filename(`twitter_${id}.zip`), id, items, platform: "twitter" };
+  return { archiveFilename: filename(`twitter_${id}.zip`), id, items, metadata: twitterMetadata(tweet), platform: "twitter" };
+}
+function twitterMetadata(tweet) {
+  const user = object(tweet.user) ? tweet.user : null;
+  return {
+    text: string(tweet.text) ?? string(tweet.full_text) ?? undefined,
+    author: user ? {
+      handle: string(user.screen_name) ?? undefined,
+      name: string(user.name) ?? undefined,
+      verified: bool(user.verified) ?? bool(user.is_blue_verified)
+    } : undefined,
+    createdAt: isoFromDateString(tweet.created_at),
+    likeCount: count(tweet.favorite_count),
+    commentCount: count(tweet.conversation_count),
+    shareCount: count(tweet.retweet_count),
+    viewCount: count(tweet.view_count),
+    nsfw: bool(tweet.possibly_sensitive),
+    extra: { lang: string(tweet.lang) ?? undefined }
+  };
 }
 async function syndication(net, id) {
   const url = `https://cdn.syndication.twimg.com/tweet-result?id=${id}&lang=en&token=${syndicationToken(id)}`;
@@ -1483,7 +1682,25 @@ async function resolveYoutube(input) {
     url: streams.video,
     ...streams.audio ? { audio: { headers, url: streams.audio } } : {}
   };
-  return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], platform: "youtube" };
+  return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
+}
+function youtubeMetadata(payload) {
+  const details = object(payload) && object(payload.videoDetails) ? payload.videoDetails : null;
+  const renderer = object(payload) && object(payload.microformat) && object(payload.microformat.playerMicroformatRenderer) ? payload.microformat.playerMicroformatRenderer : null;
+  const author2 = details ? string(details.author) : null;
+  const keywords = details && Array.isArray(details.keywords) ? details.keywords.filter((keyword) => typeof keyword === "string") : [];
+  return {
+    title: details ? string(details.title) ?? undefined : undefined,
+    text: details ? string(details.shortDescription) ?? undefined : undefined,
+    author: author2 ? { name: author2 } : undefined,
+    createdAt: renderer ? isoFromDateString(renderer.publishDate) : undefined,
+    viewCount: details ? count(details.viewCount) : undefined,
+    extra: {
+      channelId: details ? string(details.channelId) ?? undefined : undefined,
+      durationSeconds: details ? count(details.lengthSeconds) : undefined,
+      keywords: keywords.length > 0 ? keywords : undefined
+    }
+  };
 }
 function selectStreams(payload, preferredWidth) {
   const adaptive = adaptiveFormats(payload);
@@ -1896,10 +2113,10 @@ function writeCentral(view, target, offset, file, localOffset) {
   target.set(file.name, offset + 46);
   return offset + 46 + file.name.length;
 }
-function writeEnd(view, offset, count, centralSize, centralStart) {
+function writeEnd(view, offset, count2, centralSize, centralStart) {
   view.setUint32(offset, 101010256, true);
-  view.setUint16(offset + 8, count, true);
-  view.setUint16(offset + 10, count, true);
+  view.setUint16(offset + 8, count2, true);
+  view.setUint16(offset + 10, count2, true);
   view.setUint32(offset + 12, centralSize, true);
   view.setUint32(offset + 16, centralStart, true);
 }

package/dist/instagram.d.ts

@@ -1,2 +1,6 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type InstagramExtra, type PostMetadata, type PostfetchReason, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolveInstagram(input: ResolveContext): Promise<PostfetchResult>;
+export declare function instagramUnavailableReason(status: number, body: string): PostfetchReason;
+export declare function instagramMetadata(media: Json): PostMetadata & {
+    extra?: InstagramExtra;
+};

package/dist/internal.d.ts

@@ -36,8 +36,110 @@ export type MediaItem = {
     /** Direct CDN URL of the media. */
     url: string;
 };
-/** The result of resolving a post: its platform, id and one or more media items. */
-export type PostfetchResult = {
+/** The author of a post, normalized across platforms. */
+export type PostAuthor = {
+    /** Account handle (the `@username`), where the platform exposes one. */
+    handle?: string;
+    /** Display name, where it differs from the handle. */
+    name?: string;
+    /** Whether the account is verified, where the platform reports it. */
+    verified?: boolean;
+};
+/**
+ * Post metadata normalized across platforms. Every field is optional: an absent
+ * field means the platform did not expose it in the payload already fetched to
+ * resolve the media (never a fabricated default — a missing count is `undefined`,
+ * not `0`). All counts are non-negative. Platform-specific fields live in `extra`.
+ */
+export type PostMetadata = {
+    /** Short headline, where the platform has one distinct from the body (Reddit, YouTube, Pinterest, SoundCloud). */
+    title?: string;
+    /** Body text: caption, tweet, description or self-text. */
+    text?: string;
+    /** Who posted it. */
+    author?: PostAuthor;
+    /** Publication time as an ISO 8601 string. */
+    createdAt?: string;
+    /** Positive reactions (likes, upvotes, favorites, diggs). */
+    likeCount?: number;
+    /** Number of comments or replies. */
+    commentCount?: number;
+    /** Genuine reshares (TikTok shares, retweets, reposts) — not saves. */
+    shareCount?: number;
+    /** Views or plays. */
+    viewCount?: number;
+    /** Whether the post is marked not-safe-for-work, where the platform reports it. */
+    nsfw?: boolean;
+};
+/** Reddit-specific metadata. */
+export type RedditExtra = {
+    /** Subreddit the post belongs to, without the `r/` prefix. */
+    subreddit?: string;
+    /** Net score (upvotes minus downvotes); can be negative. */
+    score?: number;
+    /** Fraction of votes that are upvotes, from 0 to 1. */
+    upvoteRatio?: number;
+    /** Path of the post on reddit.com, starting with `/r/`. */
+    permalink?: string;
+};
+/** TikTok-specific metadata. */
+export type TiktokExtra = {
+    /** Times the video was added to favorites. */
+    saveCount?: number;
+    /** Title of the sound used. */
+    musicTitle?: string;
+    /** Author of the sound used. */
+    musicAuthor?: string;
+    /** Two-letter region the video was created in. */
+    region?: string;
+    /** Video duration in seconds. */
+    durationSeconds?: number;
+};
+/** X (Twitter)-specific metadata. */
+export type TwitterExtra = {
+    /** BCP 47 language tag detected for the tweet. */
+    lang?: string;
+};
+/** Instagram-specific metadata. */
+export type InstagramExtra = {
+    /** Product type, e.g. `clips` for a reel or `feed` for a feed post. */
+    productType?: string;
+    /** Whether the account hid its like and view counts. */
+    countsHidden?: boolean;
+    /** Tagged location name, when present. */
+    location?: string;
+};
+/** YouTube-specific metadata. */
+export type YoutubeExtra = {
+    /** Channel id (`UC…`) of the uploader. */
+    channelId?: string;
+    /** Video duration in seconds. */
+    durationSeconds?: number;
+    /** Video keywords. */
+    keywords?: string[];
+};
+/** SoundCloud-specific metadata. */
+export type SoundcloudExtra = {
+    /** Track genre, when set. */
+    genre?: string;
+    /** Track license, e.g. `all-rights-reserved`. */
+    license?: string;
+    /** Track duration in seconds. */
+    durationSeconds?: number;
+};
+/** Pinterest-specific metadata. */
+export type PinterestExtra = {
+    /** Times the pin was saved (repinned). */
+    saveCount?: number;
+    /** Dominant color of the pin image, as a hex string. */
+    dominantColor?: string;
+    /** Outbound link the pin points to, when set. */
+    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>;
+/** 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. */
     archiveFilename: string;
     /** Platform post/media id. */
@@ -45,7 +147,12 @@ export type PostfetchResult = {
     /** The post's media, in order. */
     items: MediaItem[];
     /** The platform the post came from. */
-    platform: Platform;
+    platform: P;
+    /** Normalized post metadata, when any was available. */
+    metadata?: PostMetadata & {
+        /** Platform-specific metadata not covered by the normalized fields. */
+        extra?: Extra;
+    };
 };
 export type Net = (url: string, init?: RequestInit, attempts?: number) => Promise<Response>;
 export type ResolveContext = {
@@ -53,24 +160,39 @@ export type ResolveContext = {
     preferredWidth: number;
     url: string;
 };
+/**
+ * Why a post could not be resolved, when the platform makes the cause knowable.
+ * Lets callers tell a user-facing limitation (age-gated, private, removed) apart
+ * from a transient/technical failure.
+ */
+export type PostfetchReason = "ageRestricted" | "private" | "loginRequired" | "deleted" | "notFound" | "rateLimited" | "unavailable";
 /** An error carrying an HTTP status, so adapters can map failures onto responses. */
 export declare class PostfetchError extends Error {
     /** HTTP status that best describes the failure. */
     readonly status: number;
+    /** Machine-readable cause, when the platform makes it knowable. */
+    readonly reason?: PostfetchReason | undefined;
     /**
      * Create an error tagged with an HTTP status.
      *
      * @param status HTTP status that best describes the failure.
      * @param message Human-readable message.
+     * @param reason Machine-readable cause, when the platform makes it knowable.
      */
     constructor(
     /** HTTP status that best describes the failure. */
-    status: number, message: string);
+    status: number, message: string, 
+    /** Machine-readable cause, when the platform makes it knowable. */
+    reason?: PostfetchReason | undefined);
 }
 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 bool(value: unknown): boolean | undefined;
+export declare function count(value: unknown): number | undefined;
+export declare function isoFromEpochSeconds(value: unknown): string | undefined;
+export declare function isoFromDateString(value: unknown): string | undefined;
 export declare function asUrl(value: string): URL;
 export declare function filename(value: string): string;

package/dist/pinterest.d.ts

@@ -1,2 +1,5 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type PinterestExtra, type PostMetadata, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolvePinterest(input: ResolveContext): Promise<PostfetchResult>;
+export declare function pinterestMetadata(pin: Json): PostMetadata & {
+    extra?: PinterestExtra;
+};

package/dist/reddit.d.ts

@@ -1,2 +1,5 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type PostMetadata, type RedditExtra, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolveReddit(input: ResolveContext): Promise<PostfetchResult>;
+export declare function redditMetadata(post: Json): PostMetadata & {
+    extra?: RedditExtra;
+};

package/dist/soundcloud.d.ts

@@ -1,2 +1,5 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type PostMetadata, type SoundcloudExtra, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolveSoundcloud(input: ResolveContext): Promise<PostfetchResult>;
+export declare function soundcloudMetadata(track: Json): PostMetadata & {
+    extra?: SoundcloudExtra;
+};

package/dist/tiktok.d.ts

@@ -1,3 +1,6 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type PostMetadata, type TiktokExtra, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolveTiktok(input: ResolveContext): Promise<PostfetchResult>;
+export declare function tiktokMetadata(item: Json): PostMetadata & {
+    extra?: TiktokExtra;
+};
 export declare function isShortlinkHost(hostname: string): boolean;

package/dist/twitter.d.ts

@@ -1,3 +1,6 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type PostMetadata, type TwitterExtra, type ResolveContext, type Json, type PostfetchResult } from "./internal";
 export declare function resolveTwitter(input: ResolveContext): Promise<PostfetchResult>;
+export declare function twitterMetadata(tweet: Json): PostMetadata & {
+    extra?: TwitterExtra;
+};
 export declare function tweetId(input: string): string | null;

package/dist/youtube.d.ts

@@ -1,3 +1,6 @@
-import { type ResolveContext, type PostfetchResult } from "./internal";
+import { type PostMetadata, type YoutubeExtra, type ResolveContext, type PostfetchResult } from "./internal";
 export declare function resolveYoutube(input: ResolveContext): Promise<PostfetchResult>;
+export declare function youtubeMetadata(payload: unknown): PostMetadata & {
+    extra?: YoutubeExtra;
+};
 export declare function youtubeVideoId(input: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Zero-dependency typed core that turns Facebook, Instagram, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -22,4 +22,20 @@
 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";
+export type {
+  InstagramExtra,
+  MediaItem,
+  MediaKind,
+  PinterestExtra,
+  Platform,
+  PlatformResult,
+  PostAuthor,
+  PostfetchReason,
+  PostfetchResult,
+  PostMetadata,
+  RedditExtra,
+  SoundcloudExtra,
+  TiktokExtra,
+  TwitterExtra,
+  YoutubeExtra,
+} from "./internal";

package/src/instagram.ts

@@ -1,9 +1,16 @@
 import {
   asUrl,
+  bool,
+  count,
   filename,
+  isoFromEpochSeconds,
   number,
   object,
+  PostfetchError,
   string,
+  type InstagramExtra,
+  type PostMetadata,
+  type PostfetchReason,
   type ResolveContext,
   type Net,
   type Json,
@@ -57,13 +64,103 @@ export async function resolveInstagram(input: ResolveContext): Promise<Postfetch
     (await embedMedia(input.net, code)) ??
     (await graphqlMedia(input.net, code));
   if (!media) {
-    throw new Error("Instagram media not found");
+    throw await instagramUnavailable(input.net, code);
   }
   const items = mediaItems(media, code, input.preferredWidth);
   if (items.length === 0) {
     throw new Error("Instagram media url not found");
   }
-  return { archiveFilename: filename(`instagram_${code}.zip`), id: code, items, platform: "instagram" };
+  return { archiveFilename: filename(`instagram_${code}.zip`), id: code, items, metadata: instagramMetadata(media), platform: "instagram" };
+}
+
+async function instagramUnavailable(net: Net, code: string): Promise<PostfetchError> {
+  const url = new URL("https://i.instagram.com/api/v1/oembed/");
+  url.searchParams.set("url", `https://www.instagram.com/p/${code}/`);
+  const response = await net(url.href, { headers: mobileHeaders() }, 1).catch(() => null);
+  const body = response ? await response.text().catch(() => "") : "";
+  const reason = instagramUnavailableReason(response?.status ?? 0, body);
+  return new PostfetchError(reasonStatus(reason), `Instagram post unavailable: ${reason}`, reason);
+}
+
+// Classifies why the post is gone from the oembed endpoint, which returns a
+// telling status and body (404 when removed; 400 with a MIN_AGE_ACCOUNT block
+// for 18+ accounts) while the media endpoints just come back empty.
+export function instagramUnavailableReason(status: number, body: string): PostfetchReason {
+  if (status === 404) {
+    return "notFound";
+  }
+  if (status !== 0 && status < 400) {
+    return "unavailable";
+  }
+  if (/MIN_AGE_ACCOUNT|under 18/i.test(body)) {
+    return "ageRestricted";
+  }
+  if (/private account|"is_private":\s*true|account is private/i.test(body)) {
+    return "private";
+  }
+  if (/log in|login_required|not logged/i.test(body)) {
+    return "loginRequired";
+  }
+  return "unavailable";
+}
+
+function reasonStatus(reason: PostfetchReason): number {
+  switch (reason) {
+    case "ageRestricted":
+      return 451;
+    case "private":
+      return 403;
+    case "loginRequired":
+      return 401;
+    case "rateLimited":
+      return 429;
+    default:
+      return 404;
+  }
+}
+
+export function instagramMetadata(media: Json): PostMetadata & { extra?: InstagramExtra } {
+  const user = object(media.user) ? media.user : object(media.owner) ? media.owner : null;
+  const countsHidden = bool(media.like_and_view_counts_disabled);
+  return {
+    text: instagramCaption(media),
+    author: user
+      ? {
+          handle: string(user.username) ?? undefined,
+          name: string(user.full_name) ?? undefined,
+          verified: bool(user.is_verified),
+        }
+      : undefined,
+    createdAt: isoFromEpochSeconds(media.taken_at ?? media.taken_at_timestamp),
+    likeCount: countsHidden ? undefined : count(media.like_count) ?? edgeCount(media.edge_media_preview_like) ?? edgeCount(media.edge_liked_by),
+    commentCount: count(media.comment_count) ?? edgeCount(media.edge_media_to_comment) ?? edgeCount(media.edge_media_to_parent_comment),
+    viewCount: countsHidden ? undefined : count(media.play_count) ?? count(media.view_count) ?? count(media.video_view_count),
+    extra: {
+      productType: string(media.product_type) ?? undefined,
+      countsHidden,
+      location: object(media.location) ? string(media.location.name) ?? undefined : undefined,
+    },
+  };
+}
+
+// Caption arrives as an object ({ text }), a bare string, or the GraphQL
+// edge_media_to_caption edge list, depending on which endpoint resolved the post.
+function instagramCaption(media: Json): string | undefined {
+  if (object(media.caption)) {
+    return string(media.caption.text) ?? undefined;
+  }
+  const direct = string(media.caption);
+  if (direct) {
+    return direct;
+  }
+  const edges =
+    object(media.edge_media_to_caption) && Array.isArray(media.edge_media_to_caption.edges) ? media.edge_media_to_caption.edges : [];
+  const node = object(edges[0]) && object(edges[0].node) ? edges[0].node : null;
+  return node ? string(node.text) ?? undefined : undefined;
+}
+
+function edgeCount(value: unknown): number | undefined {
+  return object(value) ? count(value.count) : undefined;
 }
 
 function shortcode(input: string): string {

package/src/internal.ts

@@ -36,8 +36,128 @@ export type MediaItem = {
   url: string;
 };
 
-/** The result of resolving a post: its platform, id and one or more media items. */
-export type PostfetchResult = {
+/** The author of a post, normalized across platforms. */
+export type PostAuthor = {
+  /** Account handle (the `@username`), where the platform exposes one. */
+  handle?: string;
+  /** Display name, where it differs from the handle. */
+  name?: string;
+  /** Whether the account is verified, where the platform reports it. */
+  verified?: boolean;
+};
+
+/**
+ * Post metadata normalized across platforms. Every field is optional: an absent
+ * field means the platform did not expose it in the payload already fetched to
+ * resolve the media (never a fabricated default — a missing count is `undefined`,
+ * not `0`). All counts are non-negative. Platform-specific fields live in `extra`.
+ */
+export type PostMetadata = {
+  /** Short headline, where the platform has one distinct from the body (Reddit, YouTube, Pinterest, SoundCloud). */
+  title?: string;
+  /** Body text: caption, tweet, description or self-text. */
+  text?: string;
+  /** Who posted it. */
+  author?: PostAuthor;
+  /** Publication time as an ISO 8601 string. */
+  createdAt?: string;
+  /** Positive reactions (likes, upvotes, favorites, diggs). */
+  likeCount?: number;
+  /** Number of comments or replies. */
+  commentCount?: number;
+  /** Genuine reshares (TikTok shares, retweets, reposts) — not saves. */
+  shareCount?: number;
+  /** Views or plays. */
+  viewCount?: number;
+  /** Whether the post is marked not-safe-for-work, where the platform reports it. */
+  nsfw?: boolean;
+};
+
+/** Reddit-specific metadata. */
+export type RedditExtra = {
+  /** Subreddit the post belongs to, without the `r/` prefix. */
+  subreddit?: string;
+  /** Net score (upvotes minus downvotes); can be negative. */
+  score?: number;
+  /** Fraction of votes that are upvotes, from 0 to 1. */
+  upvoteRatio?: number;
+  /** Path of the post on reddit.com, starting with `/r/`. */
+  permalink?: string;
+};
+
+/** TikTok-specific metadata. */
+export type TiktokExtra = {
+  /** Times the video was added to favorites. */
+  saveCount?: number;
+  /** Title of the sound used. */
+  musicTitle?: string;
+  /** Author of the sound used. */
+  musicAuthor?: string;
+  /** Two-letter region the video was created in. */
+  region?: string;
+  /** Video duration in seconds. */
+  durationSeconds?: number;
+};
+
+/** X (Twitter)-specific metadata. */
+export type TwitterExtra = {
+  /** BCP 47 language tag detected for the tweet. */
+  lang?: string;
+};
+
+/** Instagram-specific metadata. */
+export type InstagramExtra = {
+  /** Product type, e.g. `clips` for a reel or `feed` for a feed post. */
+  productType?: string;
+  /** Whether the account hid its like and view counts. */
+  countsHidden?: boolean;
+  /** Tagged location name, when present. */
+  location?: string;
+};
+
+/** YouTube-specific metadata. */
+export type YoutubeExtra = {
+  /** Channel id (`UC…`) of the uploader. */
+  channelId?: string;
+  /** Video duration in seconds. */
+  durationSeconds?: number;
+  /** Video keywords. */
+  keywords?: string[];
+};
+
+/** SoundCloud-specific metadata. */
+export type SoundcloudExtra = {
+  /** Track genre, when set. */
+  genre?: string;
+  /** Track license, e.g. `all-rights-reserved`. */
+  license?: string;
+  /** Track duration in seconds. */
+  durationSeconds?: number;
+};
+
+/** Pinterest-specific metadata. */
+export type PinterestExtra = {
+  /** Times the pin was saved (repinned). */
+  saveCount?: number;
+  /** Dominant color of the pin image, as a hex string. */
+  dominantColor?: string;
+  /** Outbound link the pin points to, when set. */
+  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>;
+
+/** 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. */
   archiveFilename: string;
   /** Platform post/media id. */
@@ -45,7 +165,12 @@ export type PostfetchResult = {
   /** The post's media, in order. */
   items: MediaItem[];
   /** The platform the post came from. */
-  platform: Platform;
+  platform: P;
+  /** Normalized post metadata, when any was available. */
+  metadata?: PostMetadata & {
+    /** Platform-specific metadata not covered by the normalized fields. */
+    extra?: Extra;
+  };
 };
 
 export type Net = (url: string, init?: RequestInit, attempts?: number) => Promise<Response>;
@@ -56,6 +181,20 @@ export type ResolveContext = {
   url: string;
 };
 
+/**
+ * Why a post could not be resolved, when the platform makes the cause knowable.
+ * Lets callers tell a user-facing limitation (age-gated, private, removed) apart
+ * from a transient/technical failure.
+ */
+export type PostfetchReason =
+  | "ageRestricted"
+  | "private"
+  | "loginRequired"
+  | "deleted"
+  | "notFound"
+  | "rateLimited"
+  | "unavailable";
+
 /** An error carrying an HTTP status, so adapters can map failures onto responses. */
 export class PostfetchError extends Error {
   /**
@@ -63,11 +202,14 @@ export class PostfetchError extends Error {
    *
    * @param status HTTP status that best describes the failure.
    * @param message Human-readable message.
+   * @param reason Machine-readable cause, when the platform makes it knowable.
    */
   constructor(
     /** HTTP status that best describes the failure. */
     readonly status: number,
     message: string,
+    /** Machine-readable cause, when the platform makes it knowable. */
+    readonly reason?: PostfetchReason,
   ) {
     super(message);
     this.name = "PostfetchError";
@@ -114,6 +256,33 @@ export function number(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+export function bool(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+export function count(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+    return value;
+  }
+  if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+    return Number(value.trim());
+  }
+  return undefined;
+}
+
+export function isoFromEpochSeconds(value: unknown): string | undefined {
+  const seconds = count(value);
+  return seconds === undefined ? undefined : new Date(seconds * 1000).toISOString();
+}
+
+export function isoFromDateString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? undefined : new Date(time).toISOString();
+}
+
 export function asUrl(value: string): URL {
   try {
     return new URL(value);

package/src/pinterest.ts

@@ -1,9 +1,13 @@
 import {
   asUrl,
+  count,
   filename,
+  isoFromDateString,
   number,
   object,
   string,
+  type PinterestExtra,
+  type PostMetadata,
   type ResolveContext,
   type Json,
   type Net,
@@ -20,7 +24,29 @@ export async function resolvePinterest(input: ResolveContext): Promise<Postfetch
   if (items.length === 0) {
     throw new Error("Pinterest media not found");
   }
-  return { archiveFilename: filename(`pinterest_${id}.zip`), id, items, platform: "pinterest" };
+  return { archiveFilename: filename(`pinterest_${id}.zip`), id, items, metadata: pinterestMetadata(pin), platform: "pinterest" };
+}
+
+export function pinterestMetadata(pin: Json): PostMetadata & { extra?: PinterestExtra } {
+  const pinner = object(pin.pinner) ? pin.pinner : null;
+  const reactions = object(pin.reaction_counts)
+    ? Object.values(pin.reaction_counts).reduce<number>((sum, value) => sum + (count(value) ?? 0), 0)
+    : undefined;
+  return {
+    title: (string(pin.title) ?? string(pin.grid_title)) ?? undefined,
+    text: string(pin.description) ?? undefined,
+    author: pinner
+      ? { handle: string(pinner.username) ?? undefined, name: string(pinner.full_name) ?? undefined }
+      : undefined,
+    createdAt: isoFromDateString(pin.created_at),
+    likeCount: reactions,
+    commentCount: count(pin.comment_count),
+    extra: {
+      saveCount: count(pin.repin_count),
+      dominantColor: string(pin.dominant_color) ?? undefined,
+      outboundLink: string(pin.link) ?? undefined,
+    },
+  };
 }
 
 // pin.it short links carry no pin id, so they are followed once to the canonical

package/src/reddit.ts

@@ -1,8 +1,14 @@
 import {
   asUrl,
+  bool,
+  count,
   filename,
+  isoFromEpochSeconds,
+  number,
   object,
   string,
+  type PostMetadata,
+  type RedditExtra,
   type ResolveContext,
   type Json,
   type Net,
@@ -25,7 +31,26 @@ export async function resolveReddit(input: ResolveContext): Promise<PostfetchRes
   if (items.length === 0) {
     throw new Error("Reddit media not found");
   }
-  return { archiveFilename: filename(`reddit_${id}.zip`), id, items, platform: "reddit" };
+  return { archiveFilename: filename(`reddit_${id}.zip`), id, items, metadata: redditMetadata(post), platform: "reddit" };
+}
+
+export function redditMetadata(post: Json): PostMetadata & { extra?: RedditExtra } {
+  const author = string(post.author);
+  return {
+    title: string(post.title) ?? undefined,
+    text: string(post.selftext) ?? undefined,
+    author: author ? { handle: author } : undefined,
+    createdAt: isoFromEpochSeconds(post.created_utc),
+    likeCount: count(post.ups),
+    commentCount: count(post.num_comments),
+    nsfw: bool(post.over_18),
+    extra: {
+      subreddit: string(post.subreddit) ?? undefined,
+      score: number(post.score) ?? undefined,
+      upvoteRatio: number(post.upvote_ratio) ?? undefined,
+      permalink: string(post.permalink) ?? undefined,
+    },
+  };
 }
 
 // Share and short links (redd.it/<id>, /r/<sub>/s/<share>) carry no post id, so

package/src/soundcloud.ts

@@ -1,9 +1,13 @@
 import {
   asUrl,
+  count,
   filename,
+  isoFromDateString,
   number,
   object,
   string,
+  type PostMetadata,
+  type SoundcloudExtra,
   type ResolveContext,
   type Json,
   type Net,
@@ -18,7 +22,29 @@ export async function resolveSoundcloud(input: ResolveContext): Promise<Postfetc
   const track = await resolveTrack(input.net, url, clientId);
   const id = trackId(track);
   const item = await audioItem(input.net, track, id, clientId);
-  return { archiveFilename: filename(`soundcloud_${id}.zip`), id, items: [item], platform: "soundcloud" };
+  return { archiveFilename: filename(`soundcloud_${id}.zip`), id, items: [item], metadata: soundcloudMetadata(track), platform: "soundcloud" };
+}
+
+export function soundcloudMetadata(track: Json): PostMetadata & { extra?: SoundcloudExtra } {
+  const user = object(track.user) ? track.user : null;
+  const durationMs = count(track.duration);
+  return {
+    title: string(track.title) ?? undefined,
+    text: string(track.description) ?? undefined,
+    author: user
+      ? { handle: string(user.username) ?? undefined, name: string(user.full_name) ?? undefined }
+      : undefined,
+    createdAt: isoFromDateString(track.created_at),
+    likeCount: count(track.likes_count),
+    commentCount: count(track.comment_count),
+    shareCount: count(track.reposts_count),
+    viewCount: count(track.playback_count),
+    extra: {
+      genre: string(track.genre) ?? undefined,
+      license: string(track.license) ?? undefined,
+      durationSeconds: durationMs === undefined ? undefined : Math.round(durationMs / 1000),
+    },
+  };
 }
 
 async function canonicalUrl(net: Net, input: string): Promise<string> {

package/src/tiktok.ts

@@ -1,8 +1,13 @@
 import {
   asUrl,
+  bool,
+  count,
   filename,
+  isoFromEpochSeconds,
   object,
   string,
+  type PostMetadata,
+  type TiktokExtra,
   type ResolveContext,
   type Json,
   type Net,
@@ -38,7 +43,36 @@ export async function resolveTiktok(input: ResolveContext): Promise<PostfetchRes
   if (items.length === 0) {
     throw new Error("TikTok media not found");
   }
-  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, platform: "tiktok" };
+  return { archiveFilename: filename(`tiktok_${user}_${id}.zip`), id, items, metadata: tiktokMetadata(page.item), platform: "tiktok" };
+}
+
+export function tiktokMetadata(item: Json): PostMetadata & { extra?: TiktokExtra } {
+  const user = object(item.author) ? item.author : null;
+  const stats = object(item.stats) ? item.stats : null;
+  const music = object(item.music) ? item.music : null;
+  const video = object(item.video) ? item.video : null;
+  return {
+    text: string(item.desc) ?? undefined,
+    author: user
+      ? {
+          handle: string(user.uniqueId) ?? undefined,
+          name: string(user.nickname) ?? undefined,
+          verified: bool(user.verified),
+        }
+      : undefined,
+    createdAt: isoFromEpochSeconds(item.createTime),
+    likeCount: stats ? count(stats.diggCount) : undefined,
+    commentCount: stats ? count(stats.commentCount) : undefined,
+    shareCount: stats ? count(stats.shareCount) : undefined,
+    viewCount: stats ? count(stats.playCount) : undefined,
+    extra: {
+      saveCount: stats ? count(stats.collectCount) : undefined,
+      musicTitle: music ? string(music.title) ?? undefined : undefined,
+      musicAuthor: music ? string(music.authorName) ?? undefined : undefined,
+      region: string(item.locationCreated) ?? undefined,
+      durationSeconds: video ? count(video.duration) : undefined,
+    },
+  };
 }
 
 async function fetchVideoPage(

package/src/twitter.ts

@@ -1,9 +1,14 @@
 import {
   asUrl,
+  bool,
+  count,
   filename,
+  isoFromDateString,
   number,
   object,
   string,
+  type PostMetadata,
+  type TwitterExtra,
   type ResolveContext,
   type Json,
   type Net,
@@ -26,7 +31,28 @@ export async function resolveTwitter(input: ResolveContext): Promise<PostfetchRe
   if (items.length === 0) {
     throw new Error("Twitter media not found");
   }
-  return { archiveFilename: filename(`twitter_${id}.zip`), id, items, platform: "twitter" };
+  return { archiveFilename: filename(`twitter_${id}.zip`), id, items, metadata: twitterMetadata(tweet), platform: "twitter" };
+}
+
+export function twitterMetadata(tweet: Json): PostMetadata & { extra?: TwitterExtra } {
+  const user = object(tweet.user) ? tweet.user : null;
+  return {
+    text: (string(tweet.text) ?? string(tweet.full_text)) ?? undefined,
+    author: user
+      ? {
+          handle: string(user.screen_name) ?? undefined,
+          name: string(user.name) ?? undefined,
+          verified: bool(user.verified) ?? bool(user.is_blue_verified),
+        }
+      : undefined,
+    createdAt: isoFromDateString(tweet.created_at),
+    likeCount: count(tweet.favorite_count),
+    commentCount: count(tweet.conversation_count),
+    shareCount: count(tweet.retweet_count),
+    viewCount: count(tweet.view_count),
+    nsfw: bool(tweet.possibly_sensitive),
+    extra: { lang: string(tweet.lang) ?? undefined },
+  };
 }
 
 // The public syndication endpoint returns tweet media (video variants + photos)

package/src/youtube.ts

@@ -1,9 +1,13 @@
 import {
   asUrl,
+  count,
   filename,
+  isoFromDateString,
   number,
   object,
   string,
+  type PostMetadata,
+  type YoutubeExtra,
   type ResolveContext,
   type Json,
   type Net,
@@ -63,7 +67,32 @@ export async function resolveYoutube(input: ResolveContext): Promise<PostfetchRe
     url: streams.video,
     ...(streams.audio ? { audio: { headers, url: streams.audio } } : {}),
   };
-  return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], platform: "youtube" };
+  return { archiveFilename: filename(`youtube_${id}.zip`), id, items: [media], metadata: youtubeMetadata(payload), platform: "youtube" };
+}
+
+export function youtubeMetadata(payload: unknown): PostMetadata & { extra?: YoutubeExtra } {
+  const details = object(payload) && object(payload.videoDetails) ? payload.videoDetails : null;
+  const renderer =
+    object(payload) && object(payload.microformat) && object(payload.microformat.playerMicroformatRenderer)
+      ? payload.microformat.playerMicroformatRenderer
+      : null;
+  const author = details ? string(details.author) : null;
+  const keywords =
+    details && Array.isArray(details.keywords)
+      ? details.keywords.filter((keyword): keyword is string => typeof keyword === "string")
+      : [];
+  return {
+    title: details ? string(details.title) ?? undefined : undefined,
+    text: details ? string(details.shortDescription) ?? undefined : undefined,
+    author: author ? { name: author } : undefined,
+    createdAt: renderer ? isoFromDateString(renderer.publishDate) : undefined,
+    viewCount: details ? count(details.viewCount) : undefined,
+    extra: {
+      channelId: details ? string(details.channelId) ?? undefined : undefined,
+      durationSeconds: details ? count(details.lengthSeconds) : undefined,
+      keywords: keywords.length > 0 ? keywords : undefined,
+    },
+  };
 }
 
 // Adaptive H.264 video and AAC audio go up to 1080p with direct URLs; merging them