@postfetch/core 0.5.2 → 0.7.0

package/README.md

@@ -1,9 +1,9 @@
 # @postfetch/core
 
-Zero-dependency typed core that turns Instagram, TikTok and YouTube post URLs into media files. Part of [postfetch](https://github.com/chelokot/postfetch).
+Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files. Part of [postfetch](https://github.com/chelokot/postfetch).
 
 ```ts
-import { postfetch, download, archive, toResponse, PostfetchError } from "@postfetch/core";
+import { postfetch, download, downloadBlob, archive, toResponse, PostfetchError } from "@postfetch/core";
 
 const result = await postfetch("https://vt.tiktok.com/ZSxpHvCUM/");
 for (const item of result.items) {
@@ -11,9 +11,13 @@ for (const item of result.items) {
 }
 ```
 
-`postfetch(url, options?)` detects the platform and resolves its media into a typed `PostfetchResult` (URLs plus the headers needed to fetch them). It performs no side effects beyond the lookup — `download`, `archive` and `toResponse` turn the result into bytes or an HTTP `Response`.
+`postfetch(url, options?)` detects the platform and resolves its media into a typed `PostfetchResult` (URLs plus the headers needed to fetch them). It performs no side effects beyond the lookup — `download`, `downloadBlob`, `archive` and `toResponse` materialize the result.
 
-- `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number }`. Inject `fetch` to unit-test resolvers offline.
+`downloadBlob(url, headers?, options?)` materializes an already-resolved media URL for
+clients that need an uploadable `Blob`. Pass the resolved item's headers for
+protected CDN URLs: `downloadBlob(item.url, item.headers)`.
+
+- `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number; tryMaxBytes?: number }`. `tryMaxBytes` is a soft byte cap: when the normal media is larger, a smaller available rendition is returned; if its size cannot be discovered or no smaller rendition is available, the normal result is kept. Inject `fetch` to unit-test resolvers offline.
 - Every request rotates a consistent browser/app fingerprint, so a fixed user-agent never gets the whole fleet blocked.
 - No runtime dependencies, no `ffmpeg` / `yt-dlp`, no cookies.
 

package/dist/download.d.ts

@@ -30,6 +30,26 @@ export type Archive = {
  * ```
  */
 export declare function download(item: MediaItem, options?: DownloadOptions): Promise<Response>;
+/**
+ * Download an already-resolved media URL as a Blob.
+ *
+ * This is useful for consumers that need to upload media themselves instead of
+ * passing its URL to a third party. When the resolved {@link MediaItem} carries
+ * required CDN headers, pass them as the second argument.
+ *
+ * @param url A direct media URL returned by a resolver.
+ * @param headers Headers required by the resolved media URL.
+ * @param options Fetch options.
+ * @returns The downloaded media as a Blob.
+ *
+ * @example Upload a video with FormData
+ * ```ts
+ * const [media] = (await postfetch(sourceUrl)).items;
+ * const blob = await downloadBlob(media.url, media.headers);
+ * form.append("video", blob, media.filename);
+ * ```
+ */
+export declare function downloadBlob(url: string, headers?: HeadersInit, options?: DownloadOptions): Promise<Blob>;
 /**
  * Download every item of a result and zip them in-process (store mode).
  *

package/dist/fingerprint.d.ts

@@ -4,8 +4,12 @@ export type BrowserFingerprint = {
     secChUaPlatform: string;
     userAgent: string;
 };
+export type NavigationHeaders = Record<string, string> & {
+    "user-agent": string;
+};
 export declare function browserFingerprint(): BrowserFingerprint;
-export declare function navigationHeaders(): Record<string, string>;
+export declare function navigationHeaders(): NavigationHeaders;
 export declare function browserUserAgent(): string;
 export declare function firefoxUserAgent(): string;
+export declare function firefoxNavigationHeaders(userAgent?: string): NavigationHeaders;
 export declare function instagramAppUserAgent(): string;

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
  * Turn a public social post URL into its media.
  *
- * {@link postfetch} resolves Instagram, TikTok, YouTube, Facebook and X (Twitter)
+ * {@link postfetch} resolves Instagram, LinkedIn, 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`.
+ * {@link download}, {@link downloadBlob}, {@link archive} and {@link toResponse}
+ * helpers turn a result into bytes, a `Blob`, or a `Response`.
  *
  * @example Resolve a reel and save the video
  * ```ts
@@ -20,6 +20,6 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
-export { download, archive, toResponse, type Archive, type DownloadOptions } from "./download";
+export { download, downloadBlob, archive, toResponse, type Archive, type DownloadOptions, } from "./download";
 export { PostfetchError } from "./internal";
-export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, 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, TwitterQuotedTweet, YoutubeExtra, } from "./internal";