ultra-igdl 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,180 @@
+/** Auto-generated by scripts/sync-version.mjs — do not edit */
+declare const PACKAGE_VERSION = "1.0.0";
+
+type MediaType = "video" | "image";
+interface Media {
+    type: MediaType;
+    url: string;
+    thumbnail?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+}
+interface ResponseMeta {
+    extractor: string;
+    version: string;
+}
+interface Engagement {
+    likes?: number;
+    comments?: number;
+    views?: number;
+    shares?: number;
+    /** Creator disabled public like/view counts (not the same as zero likes). */
+    likesHidden?: boolean;
+    /** Creator disabled comments or comment counts. */
+    commentsHidden?: boolean;
+    /** Raw stats line from Instagram (likes/comments prefix) when present */
+    raw?: string;
+}
+/** Visibility / extraction hints for clients (e.g. owner hid like counts). */
+type EngagementTag = "likes_hidden" | "comments_hidden" | "engagement_hidden";
+/** Post shape hints (carousel detection, session needs). */
+type PostContentTag = "carousel" | "partial_carousel" | "session_recommended";
+type ResultTag = EngagementTag | PostContentTag;
+interface DownloadResponse {
+    code: number;
+    meta: ResponseMeta;
+    media: Media[];
+    /** Original post caption only (no likes/comments/shares text) */
+    caption: string;
+    username: string;
+    /** Likes, comments, views, shares — separate from caption */
+    engagement?: Engagement;
+    /** e.g. likes_hidden, carousel, partial_carousel */
+    tags?: ResultTag[];
+    message?: string;
+}
+interface ErrorResponse {
+    code: number;
+    message: string;
+    meta?: ResponseMeta;
+    /** Hint for clients when a background fetch is still running. */
+    retryAfterMs?: number;
+}
+type ApiResponse = DownloadResponse | ErrorResponse;
+interface UltraIgdlOptions {
+    cache?: boolean;
+    cacheTtlMs?: number;
+    /** How long stale cache may be served while revalidating (default 24h). */
+    staleCacheTtlMs?: number;
+    cacheMaxSize?: number;
+    redis?: RedisAdapter;
+    maxConcurrency?: number;
+    timeoutMs?: number;
+    retries?: number;
+    userAgentRotation?: boolean;
+    verbose?: boolean;
+    /**
+     * Target max time for `download()` to return. Uses instant cache/stale hits;
+     * on cold URLs returns 503 + `retryAfterMs` while fetch continues in background.
+     * Set `fastMode: true` for 500ms budget.
+     */
+    responseBudgetMs?: number;
+    /** Shorthand: `responseBudgetMs: 500`, `retries: 0`, aggressive cache. */
+    fastMode?: boolean;
+    /**
+     * Instagram `sessionid` cookie value (from a logged-in browser).
+     * Required for story downloads — Instagram does not embed story media in public HTML.
+     */
+    sessionId?: string;
+    /** Full Cookie header override (includes sessionid, csrftoken, etc.). */
+    cookies?: string;
+}
+interface RedisAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs?: number): Promise<void>;
+    del?(key: string): Promise<void>;
+}
+interface ParsedUrl {
+    type: "reel" | "post" | "story" | "highlight" | "tv" | "unknown";
+    shortcode?: string;
+    username?: string;
+    storyId?: string;
+    highlightId?: string;
+    storyMediaId?: string;
+    normalized: string;
+}
+interface HealthStatus {
+    status: "ok" | "degraded" | "error";
+    version: string;
+    uptime: number;
+    cache: {
+        size: number;
+        maxSize: number;
+        hitRate?: number;
+    };
+    pool: {
+        connections: number;
+        pending: number;
+    };
+}
+interface BatchResult {
+    url: string;
+    result: ApiResponse;
+    durationMs: number;
+}
+
+declare const EXTRACTOR_NAME = "ultra-igdl";
+
+declare class DownloaderCore {
+    private client;
+    private cache;
+    private options;
+    private startTime;
+    private semaphore;
+    constructor(options?: UltraIgdlOptions);
+    private acquire;
+    private release;
+    private meta;
+    private success;
+    private error;
+    private startDownloadTask;
+    /** API-only attempt for story/highlight (fits ~500ms budget). */
+    private fetchFastExtract;
+    /** Warm cache in background (full extraction, no response budget). */
+    prefetch(url: string): Promise<ApiResponse>;
+    download(url: string): Promise<ApiResponse>;
+    private ensureBackgroundFetch;
+    private fetchAndExtract;
+    info(url: string): Promise<ApiResponse>;
+    validate(url: string): Promise<{
+        valid: boolean;
+        type?: string;
+        normalized?: string;
+    }>;
+    media(url: string): Promise<Media[] | ErrorResponse>;
+    batch(urls: string[]): Promise<BatchResult[]>;
+    health(): Promise<HealthStatus>;
+    clearCache(): void;
+}
+
+interface ValidationResult {
+    valid: boolean;
+    type?: string;
+    normalized?: string;
+    error?: string;
+}
+declare function validateUrl(input: string): ValidationResult;
+
+declare function parseInstagramUrl(input: string): ParsedUrl;
+declare function isInstagramUrl(input: string): boolean;
+
+declare class ultraigdl {
+    private core;
+    constructor(options?: UltraIgdlOptions);
+    download(url: string): Promise<ApiResponse>;
+    info(url: string): Promise<ApiResponse>;
+    validate(url: string): Promise<{
+        valid: boolean;
+        type?: string;
+        normalized?: string;
+    }>;
+    media(url: string): Promise<Media[] | ErrorResponse>;
+    batch(urls: string[]): Promise<BatchResult[]>;
+    health(): Promise<HealthStatus>;
+    clearCache(): void;
+    /** Start extraction now so the next `download()` can return within `responseBudgetMs`. */
+    prefetch(url: string): Promise<ApiResponse>;
+}
+
+export { type ApiResponse, type BatchResult, type DownloadResponse, DownloaderCore, EXTRACTOR_NAME, type Engagement, type EngagementTag, type ErrorResponse, type HealthStatus, type Media, PACKAGE_VERSION, type PostContentTag, type RedisAdapter, type ResultTag, type UltraIgdlOptions, type ValidationResult, ultraigdl as default, isInstagramUrl, parseInstagramUrl, ultraigdl, validateUrl };

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+/** Auto-generated by scripts/sync-version.mjs — do not edit */
+declare const PACKAGE_VERSION = "1.0.0";
+
+type MediaType = "video" | "image";
+interface Media {
+    type: MediaType;
+    url: string;
+    thumbnail?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+}
+interface ResponseMeta {
+    extractor: string;
+    version: string;
+}
+interface Engagement {
+    likes?: number;
+    comments?: number;
+    views?: number;
+    shares?: number;
+    /** Creator disabled public like/view counts (not the same as zero likes). */
+    likesHidden?: boolean;
+    /** Creator disabled comments or comment counts. */
+    commentsHidden?: boolean;
+    /** Raw stats line from Instagram (likes/comments prefix) when present */
+    raw?: string;
+}
+/** Visibility / extraction hints for clients (e.g. owner hid like counts). */
+type EngagementTag = "likes_hidden" | "comments_hidden" | "engagement_hidden";
+/** Post shape hints (carousel detection, session needs). */
+type PostContentTag = "carousel" | "partial_carousel" | "session_recommended";
+type ResultTag = EngagementTag | PostContentTag;
+interface DownloadResponse {
+    code: number;
+    meta: ResponseMeta;
+    media: Media[];
+    /** Original post caption only (no likes/comments/shares text) */
+    caption: string;
+    username: string;
+    /** Likes, comments, views, shares — separate from caption */
+    engagement?: Engagement;
+    /** e.g. likes_hidden, carousel, partial_carousel */
+    tags?: ResultTag[];
+    message?: string;
+}
+interface ErrorResponse {
+    code: number;
+    message: string;
+    meta?: ResponseMeta;
+    /** Hint for clients when a background fetch is still running. */
+    retryAfterMs?: number;
+}
+type ApiResponse = DownloadResponse | ErrorResponse;
+interface UltraIgdlOptions {
+    cache?: boolean;
+    cacheTtlMs?: number;
+    /** How long stale cache may be served while revalidating (default 24h). */
+    staleCacheTtlMs?: number;
+    cacheMaxSize?: number;
+    redis?: RedisAdapter;
+    maxConcurrency?: number;
+    timeoutMs?: number;
+    retries?: number;
+    userAgentRotation?: boolean;
+    verbose?: boolean;
+    /**
+     * Target max time for `download()` to return. Uses instant cache/stale hits;
+     * on cold URLs returns 503 + `retryAfterMs` while fetch continues in background.
+     * Set `fastMode: true` for 500ms budget.
+     */
+    responseBudgetMs?: number;
+    /** Shorthand: `responseBudgetMs: 500`, `retries: 0`, aggressive cache. */
+    fastMode?: boolean;
+    /**
+     * Instagram `sessionid` cookie value (from a logged-in browser).
+     * Required for story downloads — Instagram does not embed story media in public HTML.
+     */
+    sessionId?: string;
+    /** Full Cookie header override (includes sessionid, csrftoken, etc.). */
+    cookies?: string;
+}
+interface RedisAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs?: number): Promise<void>;
+    del?(key: string): Promise<void>;
+}
+interface ParsedUrl {
+    type: "reel" | "post" | "story" | "highlight" | "tv" | "unknown";
+    shortcode?: string;
+    username?: string;
+    storyId?: string;
+    highlightId?: string;
+    storyMediaId?: string;
+    normalized: string;
+}
+interface HealthStatus {
+    status: "ok" | "degraded" | "error";
+    version: string;
+    uptime: number;
+    cache: {
+        size: number;
+        maxSize: number;
+        hitRate?: number;
+    };
+    pool: {
+        connections: number;
+        pending: number;
+    };
+}
+interface BatchResult {
+    url: string;
+    result: ApiResponse;
+    durationMs: number;
+}
+
+declare const EXTRACTOR_NAME = "ultra-igdl";
+
+declare class DownloaderCore {
+    private client;
+    private cache;
+    private options;
+    private startTime;
+    private semaphore;
+    constructor(options?: UltraIgdlOptions);
+    private acquire;
+    private release;
+    private meta;
+    private success;
+    private error;
+    private startDownloadTask;
+    /** API-only attempt for story/highlight (fits ~500ms budget). */
+    private fetchFastExtract;
+    /** Warm cache in background (full extraction, no response budget). */
+    prefetch(url: string): Promise<ApiResponse>;
+    download(url: string): Promise<ApiResponse>;
+    private ensureBackgroundFetch;
+    private fetchAndExtract;
+    info(url: string): Promise<ApiResponse>;
+    validate(url: string): Promise<{
+        valid: boolean;
+        type?: string;
+        normalized?: string;
+    }>;
+    media(url: string): Promise<Media[] | ErrorResponse>;
+    batch(urls: string[]): Promise<BatchResult[]>;
+    health(): Promise<HealthStatus>;
+    clearCache(): void;
+}
+
+interface ValidationResult {
+    valid: boolean;
+    type?: string;
+    normalized?: string;
+    error?: string;
+}
+declare function validateUrl(input: string): ValidationResult;
+
+declare function parseInstagramUrl(input: string): ParsedUrl;
+declare function isInstagramUrl(input: string): boolean;
+
+declare class ultraigdl {
+    private core;
+    constructor(options?: UltraIgdlOptions);
+    download(url: string): Promise<ApiResponse>;
+    info(url: string): Promise<ApiResponse>;
+    validate(url: string): Promise<{
+        valid: boolean;
+        type?: string;
+        normalized?: string;
+    }>;
+    media(url: string): Promise<Media[] | ErrorResponse>;
+    batch(urls: string[]): Promise<BatchResult[]>;
+    health(): Promise<HealthStatus>;
+    clearCache(): void;
+    /** Start extraction now so the next `download()` can return within `responseBudgetMs`. */
+    prefetch(url: string): Promise<ApiResponse>;
+}
+
+export { type ApiResponse, type BatchResult, type DownloadResponse, DownloaderCore, EXTRACTOR_NAME, type Engagement, type EngagementTag, type ErrorResponse, type HealthStatus, type Media, PACKAGE_VERSION, type PostContentTag, type RedisAdapter, type ResultTag, type UltraIgdlOptions, type ValidationResult, ultraigdl as default, isInstagramUrl, parseInstagramUrl, ultraigdl, validateUrl };