@chilfish/gallery-dl-instagram 0.1.0 → 0.2.0

package/cli/index.ts

@@ -1,337 +0,0 @@
-#!/usr/bin/env node
-/**
- * gdl-instagram — CLI entry point.
- *
- * Usage:
- *   gdl-instagram <url> [options]          ← auto-detect from URL
- *   gdl-instagram tag <hashtag> [options]
- *   gdl-instagram saved [options]
- *
- * Every option is self-documented via ``--help``.
- */
-
-import { Command } from 'commander'
-import { ConfigManager } from '../config'
-import { DownloadJob, PrintJob } from '../core/job'
-import {
-  InstagramHighlightsExtractor,
-  InstagramPostExtractor,
-  InstagramSavedExtractor,
-  InstagramStoriesExtractor,
-  InstagramTagExtractor,
-  InstagramUserExtractor,
-} from '../instagram/extractors'
-import { createHttpClient, createLogger, createStorage, createWebClient, extractCsrfFromCookies } from './adapter'
-
-/** Shared options — applied to all subcommands */
-
-interface GlobalOptions {
-  sessionid?: string
-  cookies?: string
-  output?: string
-  videos?: string
-  previews?: string
-  audio?: boolean
-  maxPosts?: number
-  cursor?: string
-  orderPosts?: string
-  orderFiles?: string
-  staticVideos?: boolean
-  api?: string
-  verbose?: boolean
-  include?: string
-  split?: boolean
-  info?: boolean
-}
-
-function addSharedOptions(cmd: Command): Command {
-  return cmd
-    .option(
-      '--sessionid <cookie>',
-      'Instagram sessionid cookie value (from browser)',
-      process.env.INSTAGRAM_SESSIONID,
-    )
-    .option(
-      '--cookies <string>',
-      'Full Cookie header string from browser (DevTools → Network → Request Headers → Cookie)',
-      process.env.INSTAGRAM_COOKIES,
-    )
-    .option('-o, --output <dir>', 'Output directory', './data')
-    .option(
-      '--videos <mode>',
-      'Download videos: true, false, or merged (yt-dlp)',
-      'true',
-    )
-    .option(
-      '--previews <types>',
-      'Download only previews: video,audio (comma-separated)',
-    )
-    .option('--audio', 'Download standalone audio tracks', false)
-    .option('--max-posts <n>', 'Maximum number of posts to download', Number.parseInt)
-    .option(
-      '--cursor <cursor>',
-      'Resume from pagination cursor (see output of previous run)',
-    )
-    .option(
-      '--order-posts <order>',
-      'Post ordering: asc, desc, id, id_asc, id_desc',
-    )
-    .option(
-      '--order-files <order>',
-      'File ordering: r, d (reverse), or empty for natural order',
-    )
-    .option(
-      '--static-videos',
-      'Download static video cover images instead of actual videos',
-      false,
-    )
-    .option(
-      '--no-static-videos',
-      'Do not force static video covers (download real videos)',
-    )
-    .option('--api <backend>', 'API backend: rest (default) or graphql', 'rest')
-    .option('-v, --verbose', 'Verbose debug output', false)
-    .option(
-      '--include <list>',
-      'For user: comma-separated sub-extractors (posts,reels,tagged,stories,highlights,info,avatar)',
-      'posts',
-    )
-    .option(
-      '--split',
-      'For stories: split each frame into a separate post',
-      false,
-    )
-    .option(
-      '-i, --info',
-      'Print structured post info to terminal (no download)',
-      false,
-    )
-}
-
-/** Build config from parsed options */
-
-function buildConfig(opts: GlobalOptions): ConfigManager {
-  const config = new ConfigManager()
-
-  const ig: Record<string, unknown> = {}
-
-  if (opts.videos)
-    ig.videos = opts.videos
-  if (opts.previews)
-    ig.previews = opts.previews.split(',')
-  if (opts.audio)
-    ig.audio = true
-  if (opts.maxPosts)
-    ig['max-posts'] = opts.maxPosts
-  if (opts.cursor)
-    ig.cursor = opts.cursor
-  if (opts.orderPosts)
-    ig['order-posts'] = opts.orderPosts
-  if (opts.orderFiles)
-    ig['order-files'] = opts.orderFiles
-  if (opts.staticVideos)
-    ig['static-videos'] = true
-  if (opts.api)
-    ig.api = opts.api
-  if (opts.include)
-    ig.include = opts.include
-  if (opts.split)
-    ig.split = true
-
-  if (Object.keys(ig).length > 0) {
-    config.set('extractor.instagram', ig)
-  }
-
-  return config
-}
-
-/** Auto-detect the right extractor for a URL */
-
-function resolveExtractor(url: string): {
-  new (opts: any): any
-  readonly pattern: RegExp
-} {
-  for (const Cls of [
-    InstagramPostExtractor,
-    InstagramStoriesExtractor,
-    InstagramHighlightsExtractor,
-    InstagramTagExtractor,
-    InstagramSavedExtractor,
-    InstagramUserExtractor,
-  ]) {
-    if (Cls.pattern.test(url)) {
-      return Cls
-    }
-  }
-
-  throw new Error(
-    `No extractor matched URL: ${url}. `
-    + 'Supported: /p/, /reel/, /{user}/, /stories/, /highlights/, /explore/tags/, /saved/',
-  )
-}
-
-/** Run an extractor */
-
-async function runExtractor(
-  url: string,
-  extrClass: {
-    new (opts: any): any
-    readonly pattern: RegExp
-  },
-  opts: GlobalOptions,
-): Promise<void> {
-  const config = buildConfig(opts)
-  const log = createLogger(opts.verbose ?? false)
-  let http: ReturnType<typeof createHttpClient>
-  let webCsrf: string | undefined
-
-  if (opts.cookies) {
-    // Full cookie string — highest priority
-    http = createHttpClient(undefined, opts.cookies, log)
-    webCsrf = extractCsrfFromCookies(opts.cookies)
-  }
-  else if (opts.sessionid) {
-    http = createHttpClient(opts.sessionid, undefined, log)
-  }
-  else {
-    const wc = await createWebClient(log)
-    http = wc.http
-    webCsrf = wc.csrfToken
-  }
-  const storage = createStorage()
-
-  const match = extrClass.pattern.exec(url)
-  if (!match) {
-    console.error(`URL did not match expected pattern: ${url}`)
-    process.exit(1)
-  }
-
-  // eslint-disable-next-line new-cap
-  const extractor = new extrClass({
-    url,
-    match,
-    config,
-    http,
-    storage,
-    log,
-    sessionId: opts.sessionid,
-    csrfToken: webCsrf,
-  })
-
-  if (opts.info) {
-    const job = new PrintJob(
-      extractor as import('../core/extractor').Extractor,
-    )
-    const start = Date.now()
-    try {
-      const status = await job.run()
-      const elapsed = ((Date.now() - start) / 1000).toFixed(1)
-      if (status !== 0) {
-        log.warn(`Finished with status ${status} in ${elapsed}s`)
-      }
-    }
-    catch (err) {
-      log.error(String(err))
-      process.exit(1)
-    }
-    return
-  }
-
-  const job = new DownloadJob(
-    extractor as import('../core/extractor').Extractor,
-  )
-  job.basePath = opts.output ?? './data'
-
-  const start = Date.now()
-  try {
-    const status = await job.run()
-    const elapsed = ((Date.now() - start) / 1000).toFixed(1)
-
-    if (status === 0) {
-      log.info(`Done in ${elapsed}s`)
-    }
-    else {
-      log.warn(`Finished with status ${status} in ${elapsed}s`)
-    }
-  }
-  catch (err) {
-    log.error(String(err))
-    process.exit(1)
-  }
-}
-
-/** Program */
-
-const program = new Command()
-
-program
-  .name('gdl-instagram')
-  .description(
-    'Download images and videos from Instagram.\n\n'
-    + 'Uses gallery-dl\'s extraction pipeline — supports posts, reels,\n'
-    + 'stories, highlights, tagged posts, saved collections, and more.\n\n'
-    + 'Requires a sessionid cookie exported from your browser.\n'
-    + 'Set via --sessionid or INSTAGRAM_SESSIONID environment variable.',
-  )
-  .version('0.1.0')
-
-/** Default command — auto-detect extractor from URL */
-
-const dlCmd = program
-  .command('dl', { isDefault: true })
-  .argument('[url]', 'Instagram URL to download (auto-detects type)')
-  .description(
-    'Download media from an Instagram URL (auto-detects post/user/stories/…)\n\n'
-    + 'Examples:\n'
-    + '  gdl-instagram https://www.instagram.com/p/CxAbCdEfGh/\n'
-    + '  gdl-instagram https://www.instagram.com/username/ --include=posts,reels\n'
-    + '  gdl-instagram https://www.instagram.com/stories/username/',
-  )
-  .action(async (url: string | undefined, opts: GlobalOptions) => {
-    if (!url) {
-      program.help()
-      return
-    }
-    const ExtrClass = resolveExtractor(url)
-    await runExtractor(url, ExtrClass, opts)
-  })
-addSharedOptions(dlCmd)
-
-/** tag subcommand */
-
-const tag = program
-  .command('tag <hashtag>')
-  .description(
-    'Download posts from an Instagram hashtag\n\n'
-    + 'Examples:\n'
-    + '  gdl-instagram tag cats\n'
-    + '  gdl-instagram tag https://www.instagram.com/explore/tags/cats/',
-  )
-  .action(async (hashtag: string, opts: GlobalOptions) => {
-    // Accept both raw tags and full URLs
-    const url = hashtag.startsWith('http')
-      ? hashtag
-      : `https://www.instagram.com/explore/tags/${hashtag}/`
-    await runExtractor(url, InstagramTagExtractor, opts)
-  })
-addSharedOptions(tag)
-
-/** saved subcommand */
-
-const saved = program
-  .command('saved')
-  .description(
-    'Download your saved (bookmarked) posts\n\n'
-    + 'Requires authentication via --sessionid.\n\n'
-    + 'Examples:\n'
-    + '  gdl-instagram saved --sessionid=abc123',
-  )
-  .action(async (opts: GlobalOptions) => {
-    const url = 'https://www.instagram.com/me/saved/'
-    await runExtractor(url, InstagramSavedExtractor, opts)
-  })
-addSharedOptions(saved)
-
-/** parse */
-
-program.parse()

package/config.ts

@@ -1,80 +0,0 @@
-/**
- * Simple nested config reader.
- *
- * Mirrors gallery-dl's ``config.interpolate``:
- *
- *   cfgPath like ``['extractor', 'instagram', 'post']``
- *   looks up: extractor.instagram.post.{key}, extractor.instagram.{key},
- *   extractor.{key}
- */
-
-import type { Config, ConfigValue } from './types'
-
-export class ConfigManager {
-  private readonly data: Config
-
-  constructor(data: Config = {}) {
-    this.data = data
-  }
-
-  /**
-   * Read a value at a dot-path like ``'extractor.instagram.videos'``.
-   * Returns ``undefined`` when the path doesn't exist.
-   */
-  get(path: string, defaultValue?: ConfigValue): ConfigValue | undefined {
-    const keys = path.split('.')
-    let node: unknown = this.data
-    for (const key of keys) {
-      if (node == null || typeof node !== 'object' || Array.isArray(node)) {
-        return defaultValue
-      }
-      node = (node as Record<string, unknown>)[key]
-    }
-    if (node === undefined)
-      return defaultValue
-    return node as ConfigValue
-  }
-
-  /**
-   * Interpolate a config key through a hierarchy of paths.
-   */
-  interpolate(
-    cfgPath: readonly string[],
-    key: string,
-    defaultVal?: ConfigValue,
-  ): ConfigValue | undefined {
-    let node: unknown = this.data
-
-    for (let i = 0; i < cfgPath.length; i++) {
-      if (node != null && typeof node === 'object' && !Array.isArray(node)) {
-        const v = (node as Record<string, unknown>)[key]
-        if (v !== undefined)
-          return v as ConfigValue
-      }
-      if (node == null || typeof node !== 'object' || Array.isArray(node)) {
-        break
-      }
-      node = (node as Record<string, unknown>)[cfgPath[i]!]
-    }
-
-    return defaultVal
-  }
-
-  /**
-   * Mutate the config at a given dot-path.
-   */
-  set(path: string, value: unknown): void {
-    const keys = path.split('.')
-    let node: Record<string, unknown> = this.data as Record<string, unknown>
-    for (let i = 0; i < keys.length - 1; i++) {
-      const key = keys[i]!
-      let child = node[key]
-      if (child == null || typeof child !== 'object' || Array.isArray(child)) {
-        child = {}
-        node[key] = child
-      }
-      node = child as Record<string, unknown>
-    }
-    node[keys[keys.length - 1]!] = value
-  }
-}

package/core/extractor.ts

@@ -1,217 +0,0 @@
-/**
- * Base Extractor abstract class.
- *
- * Every extractor extends this.  The class provides:
- * - URL pattern matching via ``fromURL``
- * - One-time initialization guarded by ``initialize()``
- * - Async-iteration entrypoint ``[Symbol.asyncIterator]`` → ``items()``
- * - Rate-limited HTTP requests
- * - Timestamp parsing
- */
-
-import type { ConfigManager } from '../config'
-import type {
-  ConfigValue,
-  HttpClient,
-  HttpResponse,
-  MessageIter,
-  RequestConfig,
-  Storage,
-} from '../types'
-
-export interface ExtractorOptions {
-  url: string
-  match: RegExpMatchArray
-  config: ConfigManager
-  http: HttpClient
-  storage: Storage
-  /** The logger interface — at minimum a debug/info/warn/error contract */
-  log: Logger
-}
-
-export interface Logger {
-  debug: (message: string, ...args: unknown[]) => void
-  info: (message: string, ...args: unknown[]) => void
-  warn: (message: string, ...args: unknown[]) => void
-  error: (message: string, ...args: unknown[]) => void
-}
-
-/** A no-op logger */
-export const noopLogger: Logger = {
-  debug: () => {},
-  info: () => {},
-  warn: () => {},
-  error: () => {},
-}
-
-export abstract class Extractor {
-  /** Human-readable category (e.g. ``'instagram'``) */
-  abstract readonly category: string
-
-  /** Sub-category (e.g. ``'post'``, ``'posts'``, ``'reels'``) */
-  abstract readonly subcategory: string
-
-  /** Root URL (e.g. ``'https://www.instagram.com'``) */
-  abstract readonly root: string
-
-  /** Regex pattern to match against URLs */
-  static readonly pattern: RegExp = /^$/
-
-  /** The input URL */
-  readonly url: string
-
-  /** Regex match groups from ``fromURL`` */
-  readonly groups: readonly string[]
-
-  readonly config: ConfigManager
-  /** HTTP client — public so Job can access for downloads */
-  readonly http: HttpClient
-  /** Storage backend — public so Job can access for writes */
-  readonly storage: Storage
-  /** Logger instance — public so Job can access for reporting */
-  readonly log: Logger
-
-  /** Delay range in seconds — random between [min, max] before each request */
-  protected requestInterval: [number, number] = [6, 12]
-
-  private _initialized = false
-
-  constructor(opts: ExtractorOptions) {
-    this.url = opts.url
-    this.groups = opts.match ? [...opts.match].slice(1) : []
-    this.config = opts.config
-    this.http = opts.http
-    this.storage = opts.storage
-    this.log = opts.log
-  }
-
-  /** Initialization */
-
-  /**
-   * One-time async setup (cookies, session, internal state).
-   * Safe to call multiple times — after the first call it becomes a no-op.
-   */
-  async initialize(): Promise<void> {
-    if (this._initialized)
-      return
-    await this._init()
-    this._initialized = true
-    // Replace with no-op so subclasses can call super.initialize() freely
-    this.initialize = async () => {}
-  }
-
-  /**
-   * Subclass hook for one-time setup.
-   */
-  protected async _init(): Promise<void> {
-    // no-op by default
-  }
-
-  /** Async iteration */
-
-  async* [Symbol.asyncIterator](): MessageIter {
-    await this.initialize()
-    yield* this.items()
-  }
-
-  /**
-   * The main extraction pipeline.  Subclasses *must* implement this.
-   */
-  abstract items(): MessageIter
-
-  /** Config helpers */
-
-  /**
-   * Read a config value using the interpolated hierarchy.
-   */
-  protected _cfg(key: string, defaultVal?: ConfigValue): ConfigValue | undefined {
-    const path: readonly string[] = [
-      'extractor',
-      this.category,
-      this.subcategory,
-    ]
-    return this.config.interpolate(path, key, defaultVal)
-  }
-
-  /** HTTP */
-
-  private _lastRequestTime = 0
-
-  /**
-   * Rate-limited HTTP request wrapper.
-   */
-  async request(
-    url: string,
-    cfg: RequestConfig = {},
-  ): Promise<HttpResponse<unknown>> {
-    await this._throttle()
-    const response = await this.http.request({ url, ...cfg })
-    this._lastRequestTime = Date.now()
-    return response
-  }
-
-  /**
-   * Convenience: request + parse JSON body.
-   */
-  async requestJSON(
-    url: string,
-    cfg: RequestConfig = {},
-  ): Promise<unknown> {
-    const resp = await this.request(url, cfg)
-    if (typeof resp.data === 'object')
-      return resp.data
-    try {
-      return JSON.parse(resp.data as string)
-    }
-    catch {
-      return {}
-    }
-  }
-
-  /** Rate limiting */
-
-  /**
-   * Sleep long enough to keep the minimum interval between requests.
-   */
-  private async _throttle(): Promise<void> {
-    const now = Date.now()
-    const elapsed = now - this._lastRequestTime
-    const [min, max] = this.requestInterval
-    // Random delay in milliseconds
-    const target = min + Math.random() * (max - min)
-    const waitMs = Math.max(0, target * 1000 - elapsed)
-    if (waitMs > 0) {
-      await new Promise(r => setTimeout(r, waitMs))
-    }
-  }
-
-  /** Utility */
-
-  /**
-   * Convert a Unix timestamp (seconds or ms) to an ISO-8601 string.
-   */
-  parseTimestamp(ts: number | null | undefined): string {
-    if (ts == null)
-      return ''
-    // If ts looks like milliseconds (year > 2100 in seconds)
-    const asMs = ts > 2_500_000_000 ? ts : ts * 1000
-    return new Date(asMs).toISOString()
-  }
-
-  /**
-   * Generate a random hex token (used for CSRF).
-   */
-  static generateToken(size = 16): string {
-    const bytes = new Uint8Array(size)
-    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-      crypto.getRandomValues(bytes)
-    }
-    else {
-      // Fallback for Node without global crypto
-      for (let i = 0; i < size; i++) {
-        bytes[i] = Math.floor(Math.random() * 256)
-      }
-    }
-    return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('')
-  }
-}