@postfetch/core 0.4.0 → 0.4.2

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 { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, YoutubeExtra, } 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";
   }
 }
@@ -250,7 +252,7 @@ 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) {
@@ -258,6 +260,50 @@ async function resolveInstagram(input) {
   }
   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);
+  const probe = response ? `oembed ${response.status}` : "oembed unreachable";
+  return new PostfetchError(reasonStatus(reason), `Instagram post unavailable: ${reason} (${probe})`, reason);
+}
+function instagramUnavailableReason(status, body) {
+  if (status === 404) {
+    return "notFound";
+  }
+  if (status === 429) {
+    return "rateLimited";
+  }
+  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);

package/dist/instagram.d.ts

@@ -1,5 +1,6 @@
-import { type InstagramExtra, type PostMetadata, type ResolveContext, type Json, 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

@@ -160,19 +160,30 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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

@@ -30,6 +30,7 @@ export type {
   Platform,
   PlatformResult,
   PostAuthor,
+  PostfetchReason,
   PostfetchResult,
   PostMetadata,
   RedditExtra,

package/src/instagram.ts

@@ -6,9 +6,11 @@ import {
   isoFromEpochSeconds,
   number,
   object,
+  PostfetchError,
   string,
   type InstagramExtra,
   type PostMetadata,
+  type PostfetchReason,
   type ResolveContext,
   type Net,
   type Json,
@@ -62,7 +64,7 @@ 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) {
@@ -71,6 +73,59 @@ export async function resolveInstagram(input: ResolveContext): Promise<Postfetch
   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);
+  // Carry the oembed status so an unclassified failure still leaves a raw clue
+  // (200 = post is public but no media could be parsed; 429 = throttled; …).
+  const probe = response ? `oembed ${response.status}` : "oembed unreachable";
+  return new PostfetchError(reasonStatus(reason), `Instagram post unavailable: ${reason} (${probe})`, reason);
+}
+
+// Classifies why the post is gone from the oembed endpoint, which returns a
+// telling status and body (404 when removed; 429 when throttled; 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 === 429) {
+    return "rateLimited";
+  }
+  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);

package/src/internal.ts

@@ -181,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 {
   /**
@@ -188,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";