@chilfish/gallery-dl-instagram 0.1.0 → 0.2.0

package/dist/sdk-CK9x5wFL.d.cts

@@ -0,0 +1,259 @@
+//#region src/types.d.ts
+/**
+ * Shared type definitions for the gallery-dl TypeScript port.
+ *
+ * Message types form a discriminated union — the `type` tag determines
+ * which handler a Job should invoke.
+ */
+/** HTTP abstraction */
+interface RequestConfig {
+  headers?: Record<string, string>;
+  params?: Record<string, string | number | null | undefined>;
+  method?: string;
+  data?: unknown;
+  timeout?: number;
+  signal?: AbortSignal;
+  /** WithCredentials / CORS cookie passthrough for browsers */
+  withCredentials?: boolean;
+  /** For binary downloads — 'arraybuffer' returns raw bytes */
+  responseType?: 'arraybuffer' | 'text' | 'json';
+}
+interface HttpResponse<T = unknown> {
+  status: number;
+  data: T;
+  headers: Record<string, string>;
+  /** Final URL after redirects */
+  url: string;
+  request?: RequestConfig;
+}
+interface HttpClient {
+  request: <T = unknown>(config: {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | null | undefined>;
+    data?: unknown;
+    signal?: AbortSignal;
+    timeout?: number;
+    responseType?: 'arraybuffer' | 'text' | 'json';
+  }) => Promise<HttpResponse<T>>;
+}
+/** Storage abstraction */
+interface Storage {
+  exists: (path: string) => Promise<boolean>;
+  write: (path: string, data: Uint8Array | string) => Promise<void>;
+  mkdir: (path: string) => Promise<void>;
+}
+type ConfigValue = string | number | boolean | null | ConfigValue[] | {
+  [key: string]: ConfigValue;
+};
+interface Config {
+  [key: string]: ConfigValue;
+}
+/** Metadata & messages */
+/**
+ * Flat string-keyed metadata dictionary.
+ * In gallery-dl every kwdict is a plain `{string → value}` map.
+ */
+type Metadata = Record<string, unknown>;
+interface DirectoryMsg {
+  readonly type: 'directory';
+  readonly metadata: Metadata;
+}
+interface UrlMsg {
+  readonly type: 'url';
+  readonly url: string;
+  readonly metadata: Metadata;
+}
+interface QueueMsg {
+  readonly type: 'queue';
+  readonly url: string;
+  readonly metadata: Metadata & {
+    readonly _extractor?: ExtractorClass;
+  };
+}
+type Message = DirectoryMsg | UrlMsg | QueueMsg;
+/**
+ * Async generator that yields Message values.
+ */
+type MessageIter = AsyncGenerator<Message, void, unknown>;
+/** Extractor class reference (for Queue dispatch) */
+/**
+ * Minimal shape that every Extractor class must expose so the Dispatch
+ * logic can re-instantiate from a URL.
+ */
+interface ExtractorClass {
+  pattern: RegExp;
+  subcategory: string;
+}
+//#endregion
+//#region src/config.d.ts
+declare class ConfigManager {
+  private readonly data;
+  constructor(data?: Config);
+  /**
+   * 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;
+  /**
+   * Interpolate a config key through a hierarchy of paths.
+   */
+  interpolate(cfgPath: readonly string[], key: string, defaultVal?: ConfigValue): ConfigValue | undefined;
+  /**
+   * Mutate the config at a given dot-path.
+   */
+  set(path: string, value: unknown): void;
+}
+//#endregion
+//#region src/core/extractor.d.ts
+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;
+}
+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 */
+declare const noopLogger: Logger;
+declare 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];
+  private _initialized;
+  constructor(opts: ExtractorOptions);
+  /** Initialization */
+  /**
+   * One-time async setup (cookies, session, internal state).
+   * Safe to call multiple times — after the first call it becomes a no-op.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Subclass hook for one-time setup.
+   */
+  protected _init(): Promise<void>;
+  /** Async iteration */
+  [Symbol.asyncIterator](): MessageIter;
+  /**
+   * 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;
+  /** HTTP */
+  private _lastRequestTime;
+  /**
+   * Rate-limited HTTP request wrapper.
+   */
+  request(url: string, cfg?: RequestConfig): Promise<HttpResponse<unknown>>;
+  /**
+   * Convenience: request + parse JSON body.
+   */
+  requestJSON(url: string, cfg?: RequestConfig): Promise<unknown>;
+  /** Rate limiting */
+  /**
+   * Sleep long enough to keep the minimum interval between requests.
+   */
+  private _throttle;
+  /** Utility */
+  /**
+   * Convert a Unix timestamp (seconds or ms) to an ISO-8601 string.
+   */
+  parseTimestamp(ts: number | null | undefined): string;
+  /**
+   * Generate a random hex token (used for CSRF).
+   */
+  static generateToken(size?: number): string;
+}
+//#endregion
+//#region src/sdk.d.ts
+interface SDKOptions {
+  /** Custom HttpClient implementation (required). */
+  http: HttpClient;
+  /**
+   * Custom Storage implementation for file output.
+   * Only needed if you plan to call ``download()``.
+   */
+  storage?: Storage;
+  /** Logger instance.  Defaults to a silent no-op logger. */
+  log?: Logger;
+  /** Pre-extracted CSRF token (optional). */
+  csrfToken?: string;
+}
+interface ExtractOptions {
+  /** Max posts to extract (for user/tag feeds). */
+  maxPosts?: number;
+  /** Download videos (default: true). */
+  videos?: boolean;
+  /** Max posts to extract (for user/tag feeds). */
+  limit?: number;
+}
+declare class InstagramSDK {
+  readonly http: HttpClient;
+  readonly storage: Storage;
+  readonly log: Logger;
+  readonly config: ConfigManager;
+  private readonly _csrfToken;
+  constructor(opts: {
+    http: HttpClient;
+    storage?: Storage;
+    log?: Logger;
+    csrfToken?: string;
+  });
+  /**
+   * Extract messages from an Instagram URL without downloading.
+   *
+   * Returns an async generator yielding Directory / Url / Queue messages.
+   * Each ``url`` message includes full metadata (post_id, username, dimensions, etc.).
+   */
+  extract(url: string): MessageIter;
+  /**
+   * Download all media from an Instagram URL.
+   *
+   * Uses the built-in DownloadJob + Storage to save files to disk.
+   * Requires ``storage`` to be set in constructor options.
+   *
+   * ```ts
+   * const stats = await ig.download('https://www.instagram.com/p/.../', './my-downloads')
+   * // → { posts: 1, files: 9, bytes: 4500000 }
+   * ```
+   */
+  download(url: string, outputDir?: string): Promise<{
+    posts: number;
+    files: number;
+    bytes: number;
+  }>;
+  /** Resolve a URL to an Extractor instance via pattern matching. */
+  private _resolve;
+}
+//#endregion
+export { Metadata as _, ExtractorOptions as a, Storage as b, ConfigManager as c, DirectoryMsg as d, ExtractorClass as f, MessageIter as g, Message as h, Extractor as i, Config as l, HttpResponse as m, InstagramSDK as n, Logger as o, HttpClient as p, SDKOptions as r, noopLogger as s, ExtractOptions as t, ConfigValue as u, QueueMsg as v, UrlMsg as x, RequestConfig as y };

package/dist/sdk-CK9x5wFL.d.mts

@@ -0,0 +1,259 @@
+//#region src/types.d.ts
+/**
+ * Shared type definitions for the gallery-dl TypeScript port.
+ *
+ * Message types form a discriminated union — the `type` tag determines
+ * which handler a Job should invoke.
+ */
+/** HTTP abstraction */
+interface RequestConfig {
+  headers?: Record<string, string>;
+  params?: Record<string, string | number | null | undefined>;
+  method?: string;
+  data?: unknown;
+  timeout?: number;
+  signal?: AbortSignal;
+  /** WithCredentials / CORS cookie passthrough for browsers */
+  withCredentials?: boolean;
+  /** For binary downloads — 'arraybuffer' returns raw bytes */
+  responseType?: 'arraybuffer' | 'text' | 'json';
+}
+interface HttpResponse<T = unknown> {
+  status: number;
+  data: T;
+  headers: Record<string, string>;
+  /** Final URL after redirects */
+  url: string;
+  request?: RequestConfig;
+}
+interface HttpClient {
+  request: <T = unknown>(config: {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | null | undefined>;
+    data?: unknown;
+    signal?: AbortSignal;
+    timeout?: number;
+    responseType?: 'arraybuffer' | 'text' | 'json';
+  }) => Promise<HttpResponse<T>>;
+}
+/** Storage abstraction */
+interface Storage {
+  exists: (path: string) => Promise<boolean>;
+  write: (path: string, data: Uint8Array | string) => Promise<void>;
+  mkdir: (path: string) => Promise<void>;
+}
+type ConfigValue = string | number | boolean | null | ConfigValue[] | {
+  [key: string]: ConfigValue;
+};
+interface Config {
+  [key: string]: ConfigValue;
+}
+/** Metadata & messages */
+/**
+ * Flat string-keyed metadata dictionary.
+ * In gallery-dl every kwdict is a plain `{string → value}` map.
+ */
+type Metadata = Record<string, unknown>;
+interface DirectoryMsg {
+  readonly type: 'directory';
+  readonly metadata: Metadata;
+}
+interface UrlMsg {
+  readonly type: 'url';
+  readonly url: string;
+  readonly metadata: Metadata;
+}
+interface QueueMsg {
+  readonly type: 'queue';
+  readonly url: string;
+  readonly metadata: Metadata & {
+    readonly _extractor?: ExtractorClass;
+  };
+}
+type Message = DirectoryMsg | UrlMsg | QueueMsg;
+/**
+ * Async generator that yields Message values.
+ */
+type MessageIter = AsyncGenerator<Message, void, unknown>;
+/** Extractor class reference (for Queue dispatch) */
+/**
+ * Minimal shape that every Extractor class must expose so the Dispatch
+ * logic can re-instantiate from a URL.
+ */
+interface ExtractorClass {
+  pattern: RegExp;
+  subcategory: string;
+}
+//#endregion
+//#region src/config.d.ts
+declare class ConfigManager {
+  private readonly data;
+  constructor(data?: Config);
+  /**
+   * 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;
+  /**
+   * Interpolate a config key through a hierarchy of paths.
+   */
+  interpolate(cfgPath: readonly string[], key: string, defaultVal?: ConfigValue): ConfigValue | undefined;
+  /**
+   * Mutate the config at a given dot-path.
+   */
+  set(path: string, value: unknown): void;
+}
+//#endregion
+//#region src/core/extractor.d.ts
+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;
+}
+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 */
+declare const noopLogger: Logger;
+declare 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];
+  private _initialized;
+  constructor(opts: ExtractorOptions);
+  /** Initialization */
+  /**
+   * One-time async setup (cookies, session, internal state).
+   * Safe to call multiple times — after the first call it becomes a no-op.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Subclass hook for one-time setup.
+   */
+  protected _init(): Promise<void>;
+  /** Async iteration */
+  [Symbol.asyncIterator](): MessageIter;
+  /**
+   * 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;
+  /** HTTP */
+  private _lastRequestTime;
+  /**
+   * Rate-limited HTTP request wrapper.
+   */
+  request(url: string, cfg?: RequestConfig): Promise<HttpResponse<unknown>>;
+  /**
+   * Convenience: request + parse JSON body.
+   */
+  requestJSON(url: string, cfg?: RequestConfig): Promise<unknown>;
+  /** Rate limiting */
+  /**
+   * Sleep long enough to keep the minimum interval between requests.
+   */
+  private _throttle;
+  /** Utility */
+  /**
+   * Convert a Unix timestamp (seconds or ms) to an ISO-8601 string.
+   */
+  parseTimestamp(ts: number | null | undefined): string;
+  /**
+   * Generate a random hex token (used for CSRF).
+   */
+  static generateToken(size?: number): string;
+}
+//#endregion
+//#region src/sdk.d.ts
+interface SDKOptions {
+  /** Custom HttpClient implementation (required). */
+  http: HttpClient;
+  /**
+   * Custom Storage implementation for file output.
+   * Only needed if you plan to call ``download()``.
+   */
+  storage?: Storage;
+  /** Logger instance.  Defaults to a silent no-op logger. */
+  log?: Logger;
+  /** Pre-extracted CSRF token (optional). */
+  csrfToken?: string;
+}
+interface ExtractOptions {
+  /** Max posts to extract (for user/tag feeds). */
+  maxPosts?: number;
+  /** Download videos (default: true). */
+  videos?: boolean;
+  /** Max posts to extract (for user/tag feeds). */
+  limit?: number;
+}
+declare class InstagramSDK {
+  readonly http: HttpClient;
+  readonly storage: Storage;
+  readonly log: Logger;
+  readonly config: ConfigManager;
+  private readonly _csrfToken;
+  constructor(opts: {
+    http: HttpClient;
+    storage?: Storage;
+    log?: Logger;
+    csrfToken?: string;
+  });
+  /**
+   * Extract messages from an Instagram URL without downloading.
+   *
+   * Returns an async generator yielding Directory / Url / Queue messages.
+   * Each ``url`` message includes full metadata (post_id, username, dimensions, etc.).
+   */
+  extract(url: string): MessageIter;
+  /**
+   * Download all media from an Instagram URL.
+   *
+   * Uses the built-in DownloadJob + Storage to save files to disk.
+   * Requires ``storage`` to be set in constructor options.
+   *
+   * ```ts
+   * const stats = await ig.download('https://www.instagram.com/p/.../', './my-downloads')
+   * // → { posts: 1, files: 9, bytes: 4500000 }
+   * ```
+   */
+  download(url: string, outputDir?: string): Promise<{
+    posts: number;
+    files: number;
+    bytes: number;
+  }>;
+  /** Resolve a URL to an Extractor instance via pattern matching. */
+  private _resolve;
+}
+//#endregion
+export { Metadata as _, ExtractorOptions as a, Storage as b, ConfigManager as c, DirectoryMsg as d, ExtractorClass as f, MessageIter as g, Message as h, Extractor as i, Config as l, HttpResponse as m, InstagramSDK as n, Logger as o, HttpClient as p, SDKOptions as r, noopLogger as s, ExtractOptions as t, ConfigValue as u, QueueMsg as v, UrlMsg as x, RequestConfig as y };