@hydrafetch/node-sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,350 @@
1
+ type Format = 'markdown' | 'html' | 'rawHtml' | 'links' | 'structured' | 'summary' | 'json' | 'brand';
2
+ interface Usage {
3
+ creditsUsed: number;
4
+ creditsRemaining: number;
5
+ freshness?: string;
6
+ }
7
+ interface PageMetadata {
8
+ title?: string;
9
+ description?: string;
10
+ language?: string;
11
+ [key: string]: unknown;
12
+ }
13
+ /** What each format puts on a scrape result. */
14
+ interface ScrapeContent {
15
+ markdown: string;
16
+ html: string;
17
+ rawHtml: string;
18
+ links: string[];
19
+ structured: unknown;
20
+ summary: string;
21
+ json: unknown;
22
+ brand: BrandResult;
23
+ }
24
+ interface ScrapeBase {
25
+ url: string;
26
+ /** Where the request landed after redirects. */
27
+ finalUrl?: string;
28
+ redirected?: boolean;
29
+ status?: number;
30
+ cached?: boolean;
31
+ warning?: string;
32
+ metadata?: PageMetadata;
33
+ usage?: Usage;
34
+ quality?: Record<string, unknown>;
35
+ }
36
+ /**
37
+ * A scrape result, narrowed to the formats you asked for.
38
+ *
39
+ * The requested formats are required; every other format stays optional, so
40
+ * `page.markdown` needs no null check when you asked for markdown.
41
+ */
42
+ type ScrapeResult<F extends Format = 'markdown'> = ScrapeBase & {
43
+ [K in F]: ScrapeContent[K];
44
+ } & Partial<Omit<ScrapeContent, F>>;
45
+ interface ScrapeOptions<F extends readonly Format[] = readonly Format[]> {
46
+ /** Which outputs to return. Defaults to `['markdown']`. */
47
+ formats?: F;
48
+ /** Serve a cached capture up to this many milliseconds old. */
49
+ maxAge?: number;
50
+ /** Only answer from cache; never fetch. */
51
+ cacheOnly?: boolean;
52
+ storeInCache?: boolean;
53
+ /**
54
+ * Keep headings, lists and tables. Off by default, which optimises for raw
55
+ * content and can read as one unstructured blob on marketing and listing
56
+ * pages — turn it on and retry when the structure matters.
57
+ */
58
+ preferStructure?: boolean;
59
+ /** Drop navigation, footers and banners. */
60
+ onlyMainContent?: boolean;
61
+ includeTags?: string[];
62
+ excludeTags?: string[];
63
+ removeBase64Images?: boolean;
64
+ blockAds?: boolean;
65
+ includeLinks?: boolean;
66
+ /** Milliseconds to wait after load before capturing. */
67
+ waitFor?: number;
68
+ /** Per-request ceiling in milliseconds. */
69
+ timeout?: number;
70
+ headers?: Record<string, string>;
71
+ jsonOptions?: Record<string, unknown>;
72
+ }
73
+ interface MapOptions {
74
+ includeLinks?: boolean;
75
+ limit?: number;
76
+ search?: string;
77
+ sitemap?: string;
78
+ sitemapInclude?: string[];
79
+ sitemapExclude?: string[];
80
+ order?: string;
81
+ includeSubdomains?: boolean;
82
+ ignoreQueryParameters?: boolean;
83
+ }
84
+ interface MapResult {
85
+ url: string;
86
+ links: string[];
87
+ count: number;
88
+ total?: number;
89
+ truncated?: boolean;
90
+ }
91
+ interface SearchOptions {
92
+ limit?: number;
93
+ /** Also fetch each result as markdown, at one extra credit per page. */
94
+ scrapeResults?: boolean;
95
+ scrapeOptions?: ScrapeOptions;
96
+ timeRange?: string;
97
+ country?: string;
98
+ includeDomains?: string[];
99
+ excludeDomains?: string[];
100
+ }
101
+ interface SearchResultItem {
102
+ title: string;
103
+ url: string;
104
+ snippet: string;
105
+ rank: number;
106
+ /** Populated only when `scrapeResults` was set. */
107
+ data?: ScrapeResult;
108
+ }
109
+ interface SearchResult {
110
+ query: string;
111
+ status?: string;
112
+ results: SearchResultItem[];
113
+ }
114
+ interface ExtractOptions {
115
+ /** A JSON Schema the result must conform to. */
116
+ schema?: Record<string, unknown>;
117
+ /** Natural-language description of what to pull, instead of or alongside a schema. */
118
+ prompt?: string;
119
+ preferStructure?: boolean;
120
+ enableWebSearch?: boolean;
121
+ showSources?: boolean;
122
+ showConfidence?: boolean;
123
+ mergeEntities?: boolean;
124
+ maxAge?: number;
125
+ }
126
+ interface ExtractItem<T = unknown> {
127
+ url: string;
128
+ /** The extracted object, shaped by your schema. */
129
+ data?: T;
130
+ fields?: Record<string, unknown>;
131
+ error?: string;
132
+ }
133
+ interface ExtractResult<T = unknown> {
134
+ /** One entry per URL, in the order you passed them. */
135
+ results: ExtractItem<T>[];
136
+ sources?: unknown[];
137
+ /** Present when `mergeEntities` folded the pages into one record. */
138
+ collection?: {
139
+ data?: T;
140
+ sources?: unknown[];
141
+ }[];
142
+ }
143
+ interface CrawlOptions {
144
+ limit?: number;
145
+ maxDepth?: number;
146
+ includePaths?: string[];
147
+ excludePaths?: string[];
148
+ allowSubdomains?: boolean;
149
+ /** Called on progress and completion instead of you polling. */
150
+ webhook?: string;
151
+ /** Per-page options. These do NOT go at the top level. */
152
+ scrapeOptions?: ScrapeOptions;
153
+ }
154
+ interface BatchOptions {
155
+ webhook?: string;
156
+ /** Per-page options. These do NOT go at the top level. */
157
+ scrapeOptions?: ScrapeOptions;
158
+ }
159
+ type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
160
+ interface JobPage {
161
+ url: string;
162
+ requestedUrl?: string;
163
+ status: string;
164
+ depth?: number;
165
+ error?: string;
166
+ errorCode?: string;
167
+ retryable?: boolean;
168
+ /** The page itself, once it succeeded. */
169
+ data?: ScrapeResult;
170
+ }
171
+ interface JobResult {
172
+ id: string;
173
+ kind?: 'crawl' | 'batch' | string;
174
+ status: JobStatus | string;
175
+ seedUrl?: string;
176
+ total?: number;
177
+ completed?: number;
178
+ failed?: number;
179
+ creditsUsed?: number;
180
+ /** The per-page results. Note: `pages`, not `data`. */
181
+ pages?: JobPage[];
182
+ }
183
+ interface BrandOptions {
184
+ /** The background the logo will sit on. */
185
+ theme?: 'light' | 'dark' | 'auto';
186
+ /** The square mark, or the full logotype. */
187
+ type?: 'icon' | 'wordmark';
188
+ }
189
+ interface BrandResult {
190
+ domain?: string;
191
+ name?: string;
192
+ description?: string;
193
+ logos?: Array<Record<string, unknown>>;
194
+ colors?: Array<Record<string, unknown>>;
195
+ fonts?: Array<Record<string, unknown>>;
196
+ socials?: Record<string, string>;
197
+ [key: string]: unknown;
198
+ }
199
+ interface LogoResult {
200
+ url?: string;
201
+ domain?: string;
202
+ theme?: string;
203
+ type?: string;
204
+ [key: string]: unknown;
205
+ }
206
+ interface StyleguideResult {
207
+ domain?: string;
208
+ colors?: Record<string, unknown>;
209
+ typography?: Record<string, unknown>;
210
+ [key: string]: unknown;
211
+ }
212
+ interface ScreenshotOptions {
213
+ /** Capture the whole scrollable page rather than the viewport. */
214
+ fullPage?: boolean;
215
+ waitFor?: number;
216
+ timeout?: number;
217
+ maxAge?: number;
218
+ viewport?: {
219
+ width: number;
220
+ height: number;
221
+ };
222
+ }
223
+ interface ScreenshotResult {
224
+ url: string;
225
+ finalUrl?: string;
226
+ status?: number;
227
+ /** Public URL of the captured PNG. */
228
+ screenshot: string;
229
+ screenshotType?: string;
230
+ width?: number;
231
+ height?: number;
232
+ cached?: boolean;
233
+ }
234
+ interface PageImage {
235
+ src: string;
236
+ alt?: string;
237
+ width?: number;
238
+ height?: number;
239
+ }
240
+ interface ImagesResult {
241
+ url: string;
242
+ finalUrl?: string;
243
+ images: PageImage[];
244
+ }
245
+ interface WaitOptions {
246
+ /** How long to keep polling before giving up. Default 300000. */
247
+ timeoutMs?: number;
248
+ /** Gap between polls. Default 2000. */
249
+ pollIntervalMs?: number;
250
+ /** Called after every poll, for progress reporting. */
251
+ onProgress?: (job: JobResult) => void;
252
+ }
253
+
254
+ interface HydrafetchOptions {
255
+ /** Defaults to process.env.HYDRAFETCH_API_KEY. */
256
+ apiKey?: string;
257
+ baseUrl?: string;
258
+ /** Per-request timeout in milliseconds. Default 120000. */
259
+ timeoutMs?: number;
260
+ /** Retries for 429 and 5xx only. Default 2. */
261
+ maxRetries?: number;
262
+ fetch?: typeof globalThis.fetch;
263
+ }
264
+ declare class Hydrafetch {
265
+ private readonly apiKey;
266
+ private readonly baseUrl;
267
+ private readonly timeoutMs;
268
+ private readonly maxRetries;
269
+ private readonly fetchImpl;
270
+ constructor(options?: HydrafetchOptions | string);
271
+ private request;
272
+ /**
273
+ * One page as clean Markdown and structured data. One credit.
274
+ *
275
+ * The return type follows the formats you ask for, so the ones you requested
276
+ * are not optional:
277
+ *
278
+ * ```ts
279
+ * const a = await hf.scrape(url); // a.markdown: string
280
+ * const b = await hf.scrape(url, { formats: ['html'] }); // b.html: string
281
+ * ```
282
+ */
283
+ scrape<const F extends readonly Format[] = ['markdown']>(url: string, options?: ScrapeOptions<F>): Promise<ScrapeResult<F[number]>>;
284
+ /** A page straight to a Markdown string, for when that is all you want. */
285
+ markdown(url: string, options?: Omit<ScrapeOptions, 'formats'>): Promise<string>;
286
+ /** A site's URLs from its sitemap and links, without fetching the pages. One credit. */
287
+ map(url: string, options?: MapOptions): Promise<MapResult>;
288
+ /** Ranked web results. One credit, plus one per result when scrapeResults is set. */
289
+ search(query: string, options?: SearchOptions): Promise<SearchResult>;
290
+ /** Typed JSON from one or more URLs. Five credits per URL. */
291
+ extract<T = unknown>(urls: string | string[], options?: ExtractOptions): Promise<ExtractResult<T>>;
292
+ /** A company's brand from its domain. Five credits. */
293
+ brand(domain: string): Promise<BrandResult>;
294
+ /** One embeddable logo. One credit, a fifth of a full brand resolve. */
295
+ logo(domain: string, options?: BrandOptions): Promise<LogoResult>;
296
+ /** A site's design system, read from computed styles in a real browser. Ten credits. */
297
+ styleguide(domain: string): Promise<StyleguideResult>;
298
+ /** A rendered PNG of the page, returned as a public URL. Five credits. */
299
+ screenshot(url: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
300
+ /** A page's images with metadata, without rendering it. One credit. */
301
+ images(url: string, options?: {
302
+ maxAge?: number;
303
+ }): Promise<ImagesResult>;
304
+ /** A page's links. One credit. */
305
+ links(url: string, options?: Omit<ScrapeOptions, 'formats'>): Promise<ScrapeResult<'links'>>;
306
+ /**
307
+ * Start a crawl from a seed URL. Returns a job id immediately; poll with
308
+ * crawlStatus, or use crawlAndWait to do both.
309
+ */
310
+ startCrawl(url: string, options?: CrawlOptions): Promise<string>;
311
+ crawlStatus(id: string): Promise<JobResult>;
312
+ /**
313
+ * Start a batch over a known list of URLs. Per-page options belong in scrapeOptions,
314
+ * not at the top level.
315
+ */
316
+ startBatch(urls: string[], options?: BatchOptions): Promise<string>;
317
+ batchStatus(id: string): Promise<JobResult>;
318
+ /** Start a crawl and poll until it reaches a terminal state. */
319
+ crawlAndWait(url: string, options?: CrawlOptions, wait?: WaitOptions): Promise<JobResult>;
320
+ /** Start a batch and poll until it reaches a terminal state. */
321
+ batchAndWait(urls: string[], options?: BatchOptions, wait?: WaitOptions): Promise<JobResult>;
322
+ private waitForJob;
323
+ }
324
+
325
+ declare class HydrafetchError extends Error {
326
+ readonly code: string;
327
+ readonly status: number;
328
+ readonly requestId?: string;
329
+ readonly details?: unknown;
330
+ constructor(args: {
331
+ code: string;
332
+ message: string;
333
+ status: number;
334
+ requestId?: string;
335
+ details?: unknown;
336
+ });
337
+ /** 401 and 403. Retrying without changing the key is pointless. */
338
+ get isAuth(): boolean;
339
+ /** 402. The workspace is out of credits. */
340
+ get isOutOfCredits(): boolean;
341
+ /** 400 and 422. The request itself is wrong; a repeat costs another call and fails again. */
342
+ get isInvalidRequest(): boolean;
343
+ /** 429 and 5xx. Worth another attempt after a wait. */
344
+ get isRetryable(): boolean;
345
+ }
346
+ declare class HydrafetchTimeoutError extends HydrafetchError {
347
+ constructor(message: string);
348
+ }
349
+
350
+ export { type BatchOptions, type BrandOptions, type BrandResult, type CrawlOptions, type ExtractItem, type ExtractOptions, type ExtractResult, type Format, Hydrafetch, HydrafetchError, type HydrafetchOptions, HydrafetchTimeoutError, type ImagesResult, type JobPage, type JobResult, type JobStatus, type LogoResult, type MapOptions, type MapResult, type PageImage, type PageMetadata, type ScrapeBase, type ScrapeContent, type ScrapeOptions, type ScrapeResult, type ScreenshotOptions, type ScreenshotResult, type SearchOptions, type SearchResult, type SearchResultItem, type StyleguideResult, type Usage, type WaitOptions };
@@ -0,0 +1,350 @@
1
+ type Format = 'markdown' | 'html' | 'rawHtml' | 'links' | 'structured' | 'summary' | 'json' | 'brand';
2
+ interface Usage {
3
+ creditsUsed: number;
4
+ creditsRemaining: number;
5
+ freshness?: string;
6
+ }
7
+ interface PageMetadata {
8
+ title?: string;
9
+ description?: string;
10
+ language?: string;
11
+ [key: string]: unknown;
12
+ }
13
+ /** What each format puts on a scrape result. */
14
+ interface ScrapeContent {
15
+ markdown: string;
16
+ html: string;
17
+ rawHtml: string;
18
+ links: string[];
19
+ structured: unknown;
20
+ summary: string;
21
+ json: unknown;
22
+ brand: BrandResult;
23
+ }
24
+ interface ScrapeBase {
25
+ url: string;
26
+ /** Where the request landed after redirects. */
27
+ finalUrl?: string;
28
+ redirected?: boolean;
29
+ status?: number;
30
+ cached?: boolean;
31
+ warning?: string;
32
+ metadata?: PageMetadata;
33
+ usage?: Usage;
34
+ quality?: Record<string, unknown>;
35
+ }
36
+ /**
37
+ * A scrape result, narrowed to the formats you asked for.
38
+ *
39
+ * The requested formats are required; every other format stays optional, so
40
+ * `page.markdown` needs no null check when you asked for markdown.
41
+ */
42
+ type ScrapeResult<F extends Format = 'markdown'> = ScrapeBase & {
43
+ [K in F]: ScrapeContent[K];
44
+ } & Partial<Omit<ScrapeContent, F>>;
45
+ interface ScrapeOptions<F extends readonly Format[] = readonly Format[]> {
46
+ /** Which outputs to return. Defaults to `['markdown']`. */
47
+ formats?: F;
48
+ /** Serve a cached capture up to this many milliseconds old. */
49
+ maxAge?: number;
50
+ /** Only answer from cache; never fetch. */
51
+ cacheOnly?: boolean;
52
+ storeInCache?: boolean;
53
+ /**
54
+ * Keep headings, lists and tables. Off by default, which optimises for raw
55
+ * content and can read as one unstructured blob on marketing and listing
56
+ * pages — turn it on and retry when the structure matters.
57
+ */
58
+ preferStructure?: boolean;
59
+ /** Drop navigation, footers and banners. */
60
+ onlyMainContent?: boolean;
61
+ includeTags?: string[];
62
+ excludeTags?: string[];
63
+ removeBase64Images?: boolean;
64
+ blockAds?: boolean;
65
+ includeLinks?: boolean;
66
+ /** Milliseconds to wait after load before capturing. */
67
+ waitFor?: number;
68
+ /** Per-request ceiling in milliseconds. */
69
+ timeout?: number;
70
+ headers?: Record<string, string>;
71
+ jsonOptions?: Record<string, unknown>;
72
+ }
73
+ interface MapOptions {
74
+ includeLinks?: boolean;
75
+ limit?: number;
76
+ search?: string;
77
+ sitemap?: string;
78
+ sitemapInclude?: string[];
79
+ sitemapExclude?: string[];
80
+ order?: string;
81
+ includeSubdomains?: boolean;
82
+ ignoreQueryParameters?: boolean;
83
+ }
84
+ interface MapResult {
85
+ url: string;
86
+ links: string[];
87
+ count: number;
88
+ total?: number;
89
+ truncated?: boolean;
90
+ }
91
+ interface SearchOptions {
92
+ limit?: number;
93
+ /** Also fetch each result as markdown, at one extra credit per page. */
94
+ scrapeResults?: boolean;
95
+ scrapeOptions?: ScrapeOptions;
96
+ timeRange?: string;
97
+ country?: string;
98
+ includeDomains?: string[];
99
+ excludeDomains?: string[];
100
+ }
101
+ interface SearchResultItem {
102
+ title: string;
103
+ url: string;
104
+ snippet: string;
105
+ rank: number;
106
+ /** Populated only when `scrapeResults` was set. */
107
+ data?: ScrapeResult;
108
+ }
109
+ interface SearchResult {
110
+ query: string;
111
+ status?: string;
112
+ results: SearchResultItem[];
113
+ }
114
+ interface ExtractOptions {
115
+ /** A JSON Schema the result must conform to. */
116
+ schema?: Record<string, unknown>;
117
+ /** Natural-language description of what to pull, instead of or alongside a schema. */
118
+ prompt?: string;
119
+ preferStructure?: boolean;
120
+ enableWebSearch?: boolean;
121
+ showSources?: boolean;
122
+ showConfidence?: boolean;
123
+ mergeEntities?: boolean;
124
+ maxAge?: number;
125
+ }
126
+ interface ExtractItem<T = unknown> {
127
+ url: string;
128
+ /** The extracted object, shaped by your schema. */
129
+ data?: T;
130
+ fields?: Record<string, unknown>;
131
+ error?: string;
132
+ }
133
+ interface ExtractResult<T = unknown> {
134
+ /** One entry per URL, in the order you passed them. */
135
+ results: ExtractItem<T>[];
136
+ sources?: unknown[];
137
+ /** Present when `mergeEntities` folded the pages into one record. */
138
+ collection?: {
139
+ data?: T;
140
+ sources?: unknown[];
141
+ }[];
142
+ }
143
+ interface CrawlOptions {
144
+ limit?: number;
145
+ maxDepth?: number;
146
+ includePaths?: string[];
147
+ excludePaths?: string[];
148
+ allowSubdomains?: boolean;
149
+ /** Called on progress and completion instead of you polling. */
150
+ webhook?: string;
151
+ /** Per-page options. These do NOT go at the top level. */
152
+ scrapeOptions?: ScrapeOptions;
153
+ }
154
+ interface BatchOptions {
155
+ webhook?: string;
156
+ /** Per-page options. These do NOT go at the top level. */
157
+ scrapeOptions?: ScrapeOptions;
158
+ }
159
+ type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
160
+ interface JobPage {
161
+ url: string;
162
+ requestedUrl?: string;
163
+ status: string;
164
+ depth?: number;
165
+ error?: string;
166
+ errorCode?: string;
167
+ retryable?: boolean;
168
+ /** The page itself, once it succeeded. */
169
+ data?: ScrapeResult;
170
+ }
171
+ interface JobResult {
172
+ id: string;
173
+ kind?: 'crawl' | 'batch' | string;
174
+ status: JobStatus | string;
175
+ seedUrl?: string;
176
+ total?: number;
177
+ completed?: number;
178
+ failed?: number;
179
+ creditsUsed?: number;
180
+ /** The per-page results. Note: `pages`, not `data`. */
181
+ pages?: JobPage[];
182
+ }
183
+ interface BrandOptions {
184
+ /** The background the logo will sit on. */
185
+ theme?: 'light' | 'dark' | 'auto';
186
+ /** The square mark, or the full logotype. */
187
+ type?: 'icon' | 'wordmark';
188
+ }
189
+ interface BrandResult {
190
+ domain?: string;
191
+ name?: string;
192
+ description?: string;
193
+ logos?: Array<Record<string, unknown>>;
194
+ colors?: Array<Record<string, unknown>>;
195
+ fonts?: Array<Record<string, unknown>>;
196
+ socials?: Record<string, string>;
197
+ [key: string]: unknown;
198
+ }
199
+ interface LogoResult {
200
+ url?: string;
201
+ domain?: string;
202
+ theme?: string;
203
+ type?: string;
204
+ [key: string]: unknown;
205
+ }
206
+ interface StyleguideResult {
207
+ domain?: string;
208
+ colors?: Record<string, unknown>;
209
+ typography?: Record<string, unknown>;
210
+ [key: string]: unknown;
211
+ }
212
+ interface ScreenshotOptions {
213
+ /** Capture the whole scrollable page rather than the viewport. */
214
+ fullPage?: boolean;
215
+ waitFor?: number;
216
+ timeout?: number;
217
+ maxAge?: number;
218
+ viewport?: {
219
+ width: number;
220
+ height: number;
221
+ };
222
+ }
223
+ interface ScreenshotResult {
224
+ url: string;
225
+ finalUrl?: string;
226
+ status?: number;
227
+ /** Public URL of the captured PNG. */
228
+ screenshot: string;
229
+ screenshotType?: string;
230
+ width?: number;
231
+ height?: number;
232
+ cached?: boolean;
233
+ }
234
+ interface PageImage {
235
+ src: string;
236
+ alt?: string;
237
+ width?: number;
238
+ height?: number;
239
+ }
240
+ interface ImagesResult {
241
+ url: string;
242
+ finalUrl?: string;
243
+ images: PageImage[];
244
+ }
245
+ interface WaitOptions {
246
+ /** How long to keep polling before giving up. Default 300000. */
247
+ timeoutMs?: number;
248
+ /** Gap between polls. Default 2000. */
249
+ pollIntervalMs?: number;
250
+ /** Called after every poll, for progress reporting. */
251
+ onProgress?: (job: JobResult) => void;
252
+ }
253
+
254
+ interface HydrafetchOptions {
255
+ /** Defaults to process.env.HYDRAFETCH_API_KEY. */
256
+ apiKey?: string;
257
+ baseUrl?: string;
258
+ /** Per-request timeout in milliseconds. Default 120000. */
259
+ timeoutMs?: number;
260
+ /** Retries for 429 and 5xx only. Default 2. */
261
+ maxRetries?: number;
262
+ fetch?: typeof globalThis.fetch;
263
+ }
264
+ declare class Hydrafetch {
265
+ private readonly apiKey;
266
+ private readonly baseUrl;
267
+ private readonly timeoutMs;
268
+ private readonly maxRetries;
269
+ private readonly fetchImpl;
270
+ constructor(options?: HydrafetchOptions | string);
271
+ private request;
272
+ /**
273
+ * One page as clean Markdown and structured data. One credit.
274
+ *
275
+ * The return type follows the formats you ask for, so the ones you requested
276
+ * are not optional:
277
+ *
278
+ * ```ts
279
+ * const a = await hf.scrape(url); // a.markdown: string
280
+ * const b = await hf.scrape(url, { formats: ['html'] }); // b.html: string
281
+ * ```
282
+ */
283
+ scrape<const F extends readonly Format[] = ['markdown']>(url: string, options?: ScrapeOptions<F>): Promise<ScrapeResult<F[number]>>;
284
+ /** A page straight to a Markdown string, for when that is all you want. */
285
+ markdown(url: string, options?: Omit<ScrapeOptions, 'formats'>): Promise<string>;
286
+ /** A site's URLs from its sitemap and links, without fetching the pages. One credit. */
287
+ map(url: string, options?: MapOptions): Promise<MapResult>;
288
+ /** Ranked web results. One credit, plus one per result when scrapeResults is set. */
289
+ search(query: string, options?: SearchOptions): Promise<SearchResult>;
290
+ /** Typed JSON from one or more URLs. Five credits per URL. */
291
+ extract<T = unknown>(urls: string | string[], options?: ExtractOptions): Promise<ExtractResult<T>>;
292
+ /** A company's brand from its domain. Five credits. */
293
+ brand(domain: string): Promise<BrandResult>;
294
+ /** One embeddable logo. One credit, a fifth of a full brand resolve. */
295
+ logo(domain: string, options?: BrandOptions): Promise<LogoResult>;
296
+ /** A site's design system, read from computed styles in a real browser. Ten credits. */
297
+ styleguide(domain: string): Promise<StyleguideResult>;
298
+ /** A rendered PNG of the page, returned as a public URL. Five credits. */
299
+ screenshot(url: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
300
+ /** A page's images with metadata, without rendering it. One credit. */
301
+ images(url: string, options?: {
302
+ maxAge?: number;
303
+ }): Promise<ImagesResult>;
304
+ /** A page's links. One credit. */
305
+ links(url: string, options?: Omit<ScrapeOptions, 'formats'>): Promise<ScrapeResult<'links'>>;
306
+ /**
307
+ * Start a crawl from a seed URL. Returns a job id immediately; poll with
308
+ * crawlStatus, or use crawlAndWait to do both.
309
+ */
310
+ startCrawl(url: string, options?: CrawlOptions): Promise<string>;
311
+ crawlStatus(id: string): Promise<JobResult>;
312
+ /**
313
+ * Start a batch over a known list of URLs. Per-page options belong in scrapeOptions,
314
+ * not at the top level.
315
+ */
316
+ startBatch(urls: string[], options?: BatchOptions): Promise<string>;
317
+ batchStatus(id: string): Promise<JobResult>;
318
+ /** Start a crawl and poll until it reaches a terminal state. */
319
+ crawlAndWait(url: string, options?: CrawlOptions, wait?: WaitOptions): Promise<JobResult>;
320
+ /** Start a batch and poll until it reaches a terminal state. */
321
+ batchAndWait(urls: string[], options?: BatchOptions, wait?: WaitOptions): Promise<JobResult>;
322
+ private waitForJob;
323
+ }
324
+
325
+ declare class HydrafetchError extends Error {
326
+ readonly code: string;
327
+ readonly status: number;
328
+ readonly requestId?: string;
329
+ readonly details?: unknown;
330
+ constructor(args: {
331
+ code: string;
332
+ message: string;
333
+ status: number;
334
+ requestId?: string;
335
+ details?: unknown;
336
+ });
337
+ /** 401 and 403. Retrying without changing the key is pointless. */
338
+ get isAuth(): boolean;
339
+ /** 402. The workspace is out of credits. */
340
+ get isOutOfCredits(): boolean;
341
+ /** 400 and 422. The request itself is wrong; a repeat costs another call and fails again. */
342
+ get isInvalidRequest(): boolean;
343
+ /** 429 and 5xx. Worth another attempt after a wait. */
344
+ get isRetryable(): boolean;
345
+ }
346
+ declare class HydrafetchTimeoutError extends HydrafetchError {
347
+ constructor(message: string);
348
+ }
349
+
350
+ export { type BatchOptions, type BrandOptions, type BrandResult, type CrawlOptions, type ExtractItem, type ExtractOptions, type ExtractResult, type Format, Hydrafetch, HydrafetchError, type HydrafetchOptions, HydrafetchTimeoutError, type ImagesResult, type JobPage, type JobResult, type JobStatus, type LogoResult, type MapOptions, type MapResult, type PageImage, type PageMetadata, type ScrapeBase, type ScrapeContent, type ScrapeOptions, type ScrapeResult, type ScreenshotOptions, type ScreenshotResult, type SearchOptions, type SearchResult, type SearchResultItem, type StyleguideResult, type Usage, type WaitOptions };