@postfetch/core 0.2.2 → 0.2.4

package/dist/download.d.ts

@@ -1,12 +1,48 @@
 import { type MediaItem, type PostfetchResult } from "./internal";
+/** Options for {@link download}, {@link archive} and {@link toResponse}. */
 export type DownloadOptions = {
+    /** Custom `fetch` implementation. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
 };
+/** A zip archive produced by {@link archive}. */
 export type Archive = {
+    /** The zip bytes (store mode, built in-process). */
     bytes: Uint8Array;
+    /** Suggested download filename. */
     filename: string;
+    /** Always `"application/zip"`. */
     mime: "application/zip";
 };
+/**
+ * Fetch a single media item from its CDN with the headers it requires.
+ *
+ * @param item A {@link MediaItem} from a {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns The upstream `Response`, ready to stream or buffer.
+ * @throws {PostfetchError} If the CDN responds with a non-OK status.
+ *
+ * @example
+ * ```ts
+ * const result = await postfetch(url);
+ * await Bun.write(result.items[0].filename, await download(result.items[0]));
+ * ```
+ */
 export declare function download(item: MediaItem, options?: DownloadOptions): Promise<Response>;
+/**
+ * Download every item of a result and zip them in-process (store mode).
+ *
+ * @param result A {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns The zip bytes and a suggested filename.
+ */
 export declare function archive(result: PostfetchResult, options?: DownloadOptions): Promise<Archive>;
+/**
+ * Turn a result into a ready-to-serve `Response`: a single item is streamed as
+ * its file, multiple items become a zip. Sets `content-disposition` and the
+ * `x-media-*` headers. This is what the showcase server and templates return.
+ *
+ * @param result A {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns A `Response` a server or edge function can return directly.
+ */
 export declare function toResponse(result: PostfetchResult, options?: DownloadOptions): Promise<Response>;

package/dist/index.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Turn a public social post URL into its media.
+ *
+ * {@link postfetch} resolves Instagram, 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`.
+ *
+ * @example Resolve a reel and save the video
+ * ```ts
+ * import { postfetch, download } from "@postfetch/core";
+ *
+ * const result = await postfetch("https://www.instagram.com/reel/DZ0ixNxtvYq/");
+ * const [item] = result.items; // { kind: "video", url, headers, filename, ... }
+ * const response = await download(item);
+ * ```
+ *
+ * @module
+ */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
 export { download, archive, toResponse, type Archive, type DownloadOptions } from "./download";
 export { PostfetchError } from "./internal";

package/dist/internal.d.ts

@@ -1,18 +1,33 @@
+/** A platform that {@link postfetch} can resolve. */
 export type Platform = "facebook" | "instagram" | "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. */
 export type MediaItem = {
+    /** Suggested download filename. */
     filename: string;
+    /** Headers required to fetch {@link MediaItem.url} from the CDN. */
     headers: HeadersInit;
+    /** Platform media id. */
     id: string;
+    /** Whether this item is a video, image or audio file. */
     kind: MediaKind;
+    /** MIME type of the media. */
     mime: string;
+    /** The platform this item came from. */
     platform: Platform;
+    /** 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 = {
+    /** Suggested filename when zipping every item. */
     archiveFilename: string;
+    /** Platform post/media id. */
     id: string;
+    /** The post's media, in order. */
     items: MediaItem[];
+    /** The platform the post came from. */
     platform: Platform;
 };
 export type Net = (url: string, init?: RequestInit, attempts?: number) => Promise<Response>;
@@ -21,9 +36,19 @@ export type ResolveContext = {
     preferredWidth: number;
     url: string;
 };
+/** 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;
-    constructor(status: number, message: string);
+    /**
+     * Create an error tagged with an HTTP status.
+     *
+     * @param status HTTP status that best describes the failure.
+     * @param message Human-readable message.
+     */
+    constructor(
+    /** HTTP status that best describes the failure. */
+    status: number, message: string);
 }
 export type Json = Record<string, unknown>;
 export declare function createNet(baseFetch?: typeof fetch): Net;

package/dist/postfetch.d.ts

@@ -1,7 +1,38 @@
 import { type Platform, type PostfetchResult } from "./internal";
+/** Options for {@link postfetch}. */
 export type PostfetchOptions = {
+    /** Custom `fetch` implementation — inject one to unit-test resolvers offline. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
+    /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
     preferredWidth?: 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`.
+ *
+ * @param url A post URL from Instagram, TikTok, YouTube, Facebook or X.
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { postfetch } from "@postfetch/core";
+ *
+ * const result = await postfetch("https://vt.tiktok.com/ZSxpHvCUM/");
+ * for (const item of result.items) console.log(item.kind, item.url);
+ * ```
+ */
 export declare function postfetch(url: string, options?: PostfetchOptions): Promise<PostfetchResult>;
+/**
+ * Detect which platform a URL belongs to, from its host.
+ *
+ * @param url Any URL.
+ * @returns The matched {@link Platform}.
+ * @throws {PostfetchError} If the host is not a supported platform.
+ */
 export declare function detect(url: string): Platform;

package/package.json

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

package/src/download.ts

@@ -1,16 +1,36 @@
 import { createNet, PostfetchError, type MediaItem, type PostfetchResult } from "./internal";
 import { zip } from "./zip";
 
+/** Options for {@link download}, {@link archive} and {@link toResponse}. */
 export type DownloadOptions = {
+  /** Custom `fetch` implementation. Defaults to the global `fetch`. */
   fetch?: typeof fetch;
 };
 
+/** A zip archive produced by {@link archive}. */
 export type Archive = {
+  /** The zip bytes (store mode, built in-process). */
   bytes: Uint8Array;
+  /** Suggested download filename. */
   filename: string;
+  /** Always `"application/zip"`. */
   mime: "application/zip";
 };
 
+/**
+ * Fetch a single media item from its CDN with the headers it requires.
+ *
+ * @param item A {@link MediaItem} from a {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns The upstream `Response`, ready to stream or buffer.
+ * @throws {PostfetchError} If the CDN responds with a non-OK status.
+ *
+ * @example
+ * ```ts
+ * const result = await postfetch(url);
+ * await Bun.write(result.items[0].filename, await download(result.items[0]));
+ * ```
+ */
 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 });
@@ -20,6 +40,13 @@ export async function download(item: MediaItem, options: DownloadOptions = {}):
   return response;
 }
 
+/**
+ * Download every item of a result and zip them in-process (store mode).
+ *
+ * @param result A {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns The zip bytes and a suggested filename.
+ */
 export async function archive(result: PostfetchResult, options: DownloadOptions = {}): Promise<Archive> {
   const net = createNet(options.fetch ?? globalThis.fetch);
   const files = await Promise.all(
@@ -34,6 +61,15 @@ export async function archive(result: PostfetchResult, options: DownloadOptions
   return { bytes: zip(files), filename: result.archiveFilename, mime: "application/zip" };
 }
 
+/**
+ * Turn a result into a ready-to-serve `Response`: a single item is streamed as
+ * its file, multiple items become a zip. Sets `content-disposition` and the
+ * `x-media-*` headers. This is what the showcase server and templates return.
+ *
+ * @param result A {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns A `Response` a server or edge function can return directly.
+ */
 export async function toResponse(result: PostfetchResult, options: DownloadOptions = {}): Promise<Response> {
   if (result.items.length === 1) {
     return singleResponse(result.items[0], options);

package/src/index.ts

@@ -1,3 +1,24 @@
+/**
+ * Turn a public social post URL into its media.
+ *
+ * {@link postfetch} resolves Instagram, 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`.
+ *
+ * @example Resolve a reel and save the video
+ * ```ts
+ * import { postfetch, download } from "@postfetch/core";
+ *
+ * const result = await postfetch("https://www.instagram.com/reel/DZ0ixNxtvYq/");
+ * const [item] = result.items; // { kind: "video", url, headers, filename, ... }
+ * const response = await download(item);
+ * ```
+ *
+ * @module
+ */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
 export { download, archive, toResponse, type Archive, type DownloadOptions } from "./download";
 export { PostfetchError } from "./internal";

package/src/internal.ts

@@ -1,21 +1,36 @@
+/** A platform that {@link postfetch} can resolve. */
 export type Platform = "facebook" | "instagram" | "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. */
 export type MediaItem = {
+  /** Suggested download filename. */
   filename: string;
+  /** Headers required to fetch {@link MediaItem.url} from the CDN. */
   headers: HeadersInit;
+  /** Platform media id. */
   id: string;
+  /** Whether this item is a video, image or audio file. */
   kind: MediaKind;
+  /** MIME type of the media. */
   mime: string;
+  /** The platform this item came from. */
   platform: Platform;
+  /** 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 = {
+  /** Suggested filename when zipping every item. */
   archiveFilename: string;
+  /** Platform post/media id. */
   id: string;
+  /** The post's media, in order. */
   items: MediaItem[];
+  /** The platform the post came from. */
   platform: Platform;
 };
 
@@ -27,8 +42,16 @@ export type ResolveContext = {
   url: string;
 };
 
+/** An error carrying an HTTP status, so adapters can map failures onto responses. */
 export class PostfetchError extends Error {
+  /**
+   * Create an error tagged with an HTTP status.
+   *
+   * @param status HTTP status that best describes the failure.
+   * @param message Human-readable message.
+   */
   constructor(
+    /** HTTP status that best describes the failure. */
     readonly status: number,
     message: string,
   ) {

package/src/postfetch.ts

@@ -5,11 +5,35 @@ import { resolveTiktok } from "./tiktok";
 import { resolveTwitter } from "./twitter";
 import { resolveYoutube } from "./youtube";
 
+/** Options for {@link postfetch}. */
 export type PostfetchOptions = {
+  /** Custom `fetch` implementation — inject one to unit-test resolvers offline. Defaults to the global `fetch`. */
   fetch?: typeof fetch;
+  /** Preferred media width in pixels; the closest available rendition is chosen. Defaults to `720`. */
   preferredWidth?: 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`.
+ *
+ * @param url A post URL from Instagram, TikTok, YouTube, Facebook or X.
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { postfetch } from "@postfetch/core";
+ *
+ * const result = await postfetch("https://vt.tiktok.com/ZSxpHvCUM/");
+ * for (const item of result.items) console.log(item.kind, item.url);
+ * ```
+ */
 export async function postfetch(url: string, options: PostfetchOptions = {}): Promise<PostfetchResult> {
   const trimmed = url.trim();
   if (trimmed.length === 0) {
@@ -34,6 +58,13 @@ export async function postfetch(url: string, options: PostfetchOptions = {}): Pr
   }
 }
 
+/**
+ * Detect which platform a URL belongs to, from its host.
+ *
+ * @param url Any URL.
+ * @returns The matched {@link Platform}.
+ * @throws {PostfetchError} If the host is not a supported platform.
+ */
 export function detect(url: string): Platform {
   const host = asUrl(url).hostname;
   if (host.includes("tiktok.com")) {