omnifetch-lib 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# OmniFetch JavaScript Library
+
+JavaScript/TypeScript implementation of OmniFetch - a universal content extraction library.
+
+## Installation
+
+```bash
+npm install omnifetch
+```
+
+## Quick Start
+
+```typescript
+import { omniFetch } from 'omnifetch';
+
+// Text extraction
+const result = await omniFetch('https://example.com', { mode: 'TEXT' });
+console.log(result.content);
+
+// JSON extraction
+const jsonResult = await omniFetch('https://example.com', { mode: 'JSON' });
+console.log(jsonResult.content.title);
+```
+
+## Configuration
+
+```typescript
+interface OmniFetchConfig {
+  mode: 'JSON' | 'TEXT';        // Output format
+  timeout?: number;              // Request timeout in ms (default: 30000)
+  netlifyEndpoint?: string;      // Headless browser endpoint
+  headers?: Record<string, string>; // Custom headers
+  skipHeadless?: boolean;        // Skip Tier 2
+  skipSearch?: boolean;          // Skip Tier 3
+}
+```
+
+## Building
+
+```bash
+npm install
+npm run build
+```
+
+## Development
+
+```bash
+npm run dev  # Watch mode
+```
+
+See the main [README.md](../../README.md) for full documentation.

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+/**
+ * OmniFetch TypeScript Type Definitions
+ */
+/** Supported output modes */
+type OutputMode = 'JSON' | 'TEXT';
+/** Configuration options for OmniFetch */
+interface OmniFetchConfig {
+    /** Output mode: 'JSON' for structured data, 'TEXT' for plain text */
+    mode: OutputMode;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom Netlify endpoint for headless browser fallback */
+    netlifyEndpoint?: string;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+    /** Whether to skip Tier 2 (headless) and go directly to search fallback */
+    skipHeadless?: boolean;
+    /** Whether to skip Tier 3 (search fallback) entirely */
+    skipSearch?: boolean;
+}
+/** Result returned by OmniFetch */
+interface OmniFetchResult {
+    /** Whether the fetch was successful */
+    success: boolean;
+    /** The extracted content (string for TEXT mode, object for JSON mode) */
+    content?: string | Record<string, unknown>;
+    /** Array of suggested alternative URLs (when content not found) */
+    suggestions?: string[];
+    /** Error message if fetch failed */
+    error?: string;
+    /** Which tier successfully retrieved the content */
+    tier?: 1 | 2 | 3;
+    /** The final URL after any redirects */
+    finalUrl?: string;
+    /** Page title extracted from the content */
+    title?: string;
+}
+/** Default configuration values */
+declare const DEFAULT_CONFIG: Required<Omit<OmniFetchConfig, 'headers'>> & {
+    headers: Record<string, string>;
+};
+
+/**
+ * OmniFetch - Universal Content Extraction Library
+ *
+ * A cross-platform library for intelligent content extraction
+ * with tiered fetching strategies to bypass bot detection and paywalls.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Fetch content from a URL using OmniFetch's tiered strategy
+ *
+ * @example
+ * ```typescript
+ * import { omniFetch } from 'omnifetch';
+ *
+ * // Simple text extraction
+ * const result = await omniFetch('https://example.com', { mode: 'TEXT' });
+ * console.log(result.content);
+ *
+ * // JSON extraction with custom endpoint
+ * const jsonResult = await omniFetch('https://example.com/article', {
+ *   mode: 'JSON',
+ *   netlifyEndpoint: 'https://your-app.netlify.app/.netlify/functions/headless-fetch'
+ * });
+ * ```
+ *
+ * @param url - The URL to fetch content from
+ * @param config - Configuration options (mode, timeout, etc.)
+ * @returns Promise resolving to OmniFetchResult
+ */
+declare function omniFetch(url: string, config?: Partial<OmniFetchConfig>): Promise<OmniFetchResult>;
+/**
+ * Convenience function for TEXT mode extraction
+ *
+ * @param url - The URL to fetch
+ * @param options - Optional configuration (excluding mode)
+ * @returns Promise resolving to text content or error
+ */
+declare function fetchText(url: string, options?: Omit<Partial<OmniFetchConfig>, 'mode'>): Promise<OmniFetchResult>;
+/**
+ * Convenience function for JSON mode extraction
+ *
+ * @param url - The URL to fetch
+ * @param options - Optional configuration (excluding mode)
+ * @returns Promise resolving to JSON content or error
+ */
+declare function fetchJson(url: string, options?: Omit<Partial<OmniFetchConfig>, 'mode'>): Promise<OmniFetchResult>;
+
+export { DEFAULT_CONFIG, type OmniFetchConfig, type OmniFetchResult, type OutputMode, omniFetch as default, fetchJson, fetchText, omniFetch };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * OmniFetch TypeScript Type Definitions
+ */
+/** Supported output modes */
+type OutputMode = 'JSON' | 'TEXT';
+/** Configuration options for OmniFetch */
+interface OmniFetchConfig {
+    /** Output mode: 'JSON' for structured data, 'TEXT' for plain text */
+    mode: OutputMode;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom Netlify endpoint for headless browser fallback */
+    netlifyEndpoint?: string;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+    /** Whether to skip Tier 2 (headless) and go directly to search fallback */
+    skipHeadless?: boolean;
+    /** Whether to skip Tier 3 (search fallback) entirely */
+    skipSearch?: boolean;
+}
+/** Result returned by OmniFetch */
+interface OmniFetchResult {
+    /** Whether the fetch was successful */
+    success: boolean;
+    /** The extracted content (string for TEXT mode, object for JSON mode) */
+    content?: string | Record<string, unknown>;
+    /** Array of suggested alternative URLs (when content not found) */
+    suggestions?: string[];
+    /** Error message if fetch failed */
+    error?: string;
+    /** Which tier successfully retrieved the content */
+    tier?: 1 | 2 | 3;
+    /** The final URL after any redirects */
+    finalUrl?: string;
+    /** Page title extracted from the content */
+    title?: string;
+}
+/** Default configuration values */
+declare const DEFAULT_CONFIG: Required<Omit<OmniFetchConfig, 'headers'>> & {
+    headers: Record<string, string>;
+};
+
+/**
+ * OmniFetch - Universal Content Extraction Library
+ *
+ * A cross-platform library for intelligent content extraction
+ * with tiered fetching strategies to bypass bot detection and paywalls.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Fetch content from a URL using OmniFetch's tiered strategy
+ *
+ * @example
+ * ```typescript
+ * import { omniFetch } from 'omnifetch';
+ *
+ * // Simple text extraction
+ * const result = await omniFetch('https://example.com', { mode: 'TEXT' });
+ * console.log(result.content);
+ *
+ * // JSON extraction with custom endpoint
+ * const jsonResult = await omniFetch('https://example.com/article', {
+ *   mode: 'JSON',
+ *   netlifyEndpoint: 'https://your-app.netlify.app/.netlify/functions/headless-fetch'
+ * });
+ * ```
+ *
+ * @param url - The URL to fetch content from
+ * @param config - Configuration options (mode, timeout, etc.)
+ * @returns Promise resolving to OmniFetchResult
+ */
+declare function omniFetch(url: string, config?: Partial<OmniFetchConfig>): Promise<OmniFetchResult>;
+/**
+ * Convenience function for TEXT mode extraction
+ *
+ * @param url - The URL to fetch
+ * @param options - Optional configuration (excluding mode)
+ * @returns Promise resolving to text content or error
+ */
+declare function fetchText(url: string, options?: Omit<Partial<OmniFetchConfig>, 'mode'>): Promise<OmniFetchResult>;
+/**
+ * Convenience function for JSON mode extraction
+ *
+ * @param url - The URL to fetch
+ * @param options - Optional configuration (excluding mode)
+ * @returns Promise resolving to JSON content or error
+ */
+declare function fetchJson(url: string, options?: Omit<Partial<OmniFetchConfig>, 'mode'>): Promise<OmniFetchResult>;
+
+export { DEFAULT_CONFIG, type OmniFetchConfig, type OmniFetchResult, type OutputMode, omniFetch as default, fetchJson, fetchText, omniFetch };