@postfetch/core 0.2.3 → 0.3.0

package/dist/download.d.ts

@@ -1,12 +1,51 @@
 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, ready to stream or buffer. A plain item streams
+ * straight from its CDN; a muxed item (one with {@link MediaItem.audio}) is
+ * downloaded as two streams and merged in-process, so its body is buffered.
+ *
+ * @param item A {@link MediaItem} from a {@link PostfetchResult}.
+ * @param options See {@link DownloadOptions}.
+ * @returns The upstream `Response`, or a buffered `Response` of the merged file.
+ * @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 (or, when muxed, merged and buffered), 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/hls.d.ts

@@ -0,0 +1,15 @@
+import type { Net } from "./internal";
+export type HlsVariant = {
+    width: number;
+    height: number;
+    bandwidth: number;
+    url: string;
+    audioGroup: string | null;
+};
+export type HlsMaster = {
+    variants: HlsVariant[];
+    audio: Record<string, string>;
+};
+export declare function isMasterPlaylist(text: string): boolean;
+export declare function parseMaster(text: string, baseUrl: string): HlsMaster;
+export declare function assembleHls(net: Net, playlistUrl: string, headers: HeadersInit): Promise<Uint8Array>;

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";