Skip to content

Commit 98b1f65

Browse files
KikobeatsKikobeats
authored
feat(no-relese): Improve API (#48)
* build: simplify API * build: don't pass args * docs: group similar content * fix: badge links * build: update example
1 parent 4b53873 commit 98b1f65

File tree

6 files changed

+102
-170
lines changed

6 files changed

+102
-170
lines changed

‎README.md‎

Lines changed: 50 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -50,12 +50,12 @@ browserless
5050

5151
You can see more common recipes at [`@browserless/examples`](https://github.com/Kikobeats/browserless/tree/master/packages/examples).
5252

53-
## API
53+
## Basic
5454

5555
All methods follow the same interface:
5656

57-
- `url` (*required*): The target URL.
58-
- `options` (*optional*): Specific settings for the method.
57+
- `<url>`: The target URL. It's required.
58+
- `[options]`: Specific settings for the method. It's optional.
5959

6060
The methods returns a Promise or a Node.js callback if pass an additional function as the last parameter.
6161

@@ -88,7 +88,7 @@ const browserless = require('browserless')({
8888

8989
See [puppeteer.launch#options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
9090

91-
By default the library will be pass a well known list of flags, so probably you don't need any additional setup.
91+
Additionally, you can setup:
9292

9393
##### timeout
9494

@@ -117,7 +117,7 @@ An incognito page will not share cookies/cache with other browser pages.
117117

118118
### .html(url, options)
119119

120-
It returns the full HTML content from the target `url`.
120+
It serializes the content from the target `url` into HTML.
121121

122122
```js
123123
const browserless = require('browserless')
@@ -131,54 +131,11 @@ const browserless = require('browserless')
131131

132132
#### options
133133

134-
See [page.goto](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options).
135-
136-
Additionally, you can setup:
137-
138-
##### waitFor
139-
140-
type: `string`|`function`|`number`</br>
141-
default: `0`
142-
143-
Wait a quantity of time, selector or function using [page.waitFor](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitforselectororfunctionortimeout-options-args).
144-
145-
##### waitUntil
146-
147-
type: `string[]`</br>
148-
default: `['networkidle0']`
149-
150-
Specify a list of events until consider navigation succeeded, using [page.waitForNavigation](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions).
151-
152-
##### userAgent
153-
154-
It will setup a custom user agent, using [page.setUserAgent](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetuseragentuseragent) method.
155-
156-
##### viewport
157-
158-
It will setup a custom viewport, using [page.setViewport](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetviewportviewport) method.
159-
160-
##### cookies
161-
162-
type: `object[]` </br>
163-
164-
A collection of [cookie's object](https://github.com/GoogleChrome/puppeteer/blob/v1.16.0/docs/api.md#pagesetcookiecookies) to set in the requests send.
165-
166-
##### headers
167-
168-
type: `object` </br>
169-
170-
An object containing additional HTTP headers to be sent with every request.
171-
172-
##### adblock
173-
174-
type: `boolean`</br>
175-
default: `true`
176-
177-
It will be abort requests detected as ads.
134+
See [browserless#goto](/#gotopage-options).
178135

179136
### .text(url, options)
180137

181-
It returns the full text content from the target `url`.
138+
It serializes the content from the target `url` into plain text.
182139

183140
```js
184141
const browserless = require('browserless')
@@ -192,7 +149,7 @@ const browserless = require('browserless')
192149

193150
#### options
194151

195-
The options you can provide are the same than [`.html`](#html) method, just the output will be different.
152+
See [browserless#goto](/#gotopage-options).
196153

197154
### .pdf(url, options)
198155

@@ -210,7 +167,7 @@ const browserless = require('browserless')
210167

211168
#### options
212169

213-
See [page.pdf](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagepdfoptions).
170+
See [browserless#goto](/#gotopage-options).
214171

215172
Additionally, you can setup:
216173

@@ -221,21 +178,6 @@ default: `'screen'`
221178

222179
Changes the CSS media type of the page using [page.emulateMedia](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulatemediamediatype).
223180

224-
##### device
225-
226-
type: `string`</br>
227-
default: `'macbook pro 13'`
228-
229-
It specifies the [device](#devices) descriptor to use in order to retrieve `userAgent` and `viewport`
230-
231-
##### userAgent
232-
233-
It will setup a custom user agent, using [page.setUserAgent](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetuseragentuseragent) method.
234-
235-
##### viewport
236-
237-
It will setup a custom viewport, using [page.setViewport](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetviewportviewport) method.
238-
239181
### .screenshot(url, options)
240182

241183
It takes a screenshot from the target `url`.
@@ -252,28 +194,13 @@ const browserless = require('browserless')
252194

253195
#### options
254196

255-
See [page.screenshot](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagescreenshotoptions).
197+
See [browserless#goto](/#gotopage-options).
256198

257199
Additionally, you can setup:
258200

259-
##### device
260-
261-
type: `string`</br>
262-
default: `'macbook pro 13'`
263-
264-
It specifies the [device](#devices) descriptor to use in order to retrieve `userAgent` and `viewport`
201+
##### hide
265202

266-
##### userAgent
267-
268-
It will setup a custom user agent, using [page.setUserAgent](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetuseragentuseragent) method.
269-
270-
##### viewport
271-
272-
It will setup a custom viewport, using [page.setViewport](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetviewportviewport) method.
273-
274-
##### hideElements
275-
276-
type: `array[]`</br>
203+
type: `string` | `string[]`</br>
277204

278205
Hide DOM elements matching the given [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
279206

@@ -283,32 +210,16 @@ Can be useful for cleaning up the page.
283210

284211
;(async () => {
285212
const buffer = await browserless.screenshot(url.toString(), {
286-
hideElements: ['.crisp-client', '#cookies-policy']
213+
hide: ['.crisp-client', '#cookies-policy']
287214
})
288215
})()
289216
```
290217

291218
This sets [`visibility: hidden`](https://stackoverflow.com/a/133064/64949) on the matched elements.
292219

293-
##### removeElements
294-
295-
type: `string[]`
296-
297-
Remove DOM elements matching the given [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
220+
##### click
298221

299-
This sets [`display: none`](https://stackoverflow.com/a/133064/64949) on the matched elements, so it could potentially break the website layout.
300-
301-
```js
302-
;(async () => {
303-
const buffer = await browserless.screenshot(url.toString(), {
304-
removeElements: ['.crisp-client', '#cookies-policy']
305-
})
306-
})()
307-
```
308-
309-
##### clickElement
310-
311-
type: `string`
222+
type: `string` | `string[]`</br>
312223

313224
Click the DOM element matching the given [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).
314225

@@ -321,7 +232,7 @@ Disable CSS [animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animat
321232

322233
##### modules
323234

324-
type: `string[]`
235+
type: `string` | `string[]`</br>
325236

326237
Inject [JavaScript modules](https://developers.google.com/web/fundamentals/primers/modules) into the page.
327238

@@ -337,7 +248,7 @@ Accepts an array of inline code, absolute URLs, and local file paths (must have
337248

338249
##### scripts
339250

340-
type: `string[]`
251+
type: `string` | `string[]`</br>
341252

342253
Same as the `modules` option, but instead injects the code as [`<script>` instead of `<script type="module">`](https://developers.google.com/web/fundamentals/primers/modules). Prefer the `modules` option whenever possible.
343254

@@ -351,7 +262,7 @@ Same as the `modules` option, but instead injects the code as [`<script>` instea
351262

352263
##### styles
353264

354-
type: `string[]`
265+
type: `string` | `string[]`</br>
355266

356267
Inject CSS styles into the page.
357268

@@ -365,7 +276,7 @@ Accepts an array of inline code, absolute URLs, and local file paths (must have
365276
})()
366277
```
367278

368-
##### scrollToElement
279+
##### scrollTo
369280

370281
type: `string` | `object`
371282

@@ -381,7 +292,7 @@ After the screenshot has been taken, this option allows you to place the screens
381292

382293
You can configure the overlay specifying:
383294

384-
- **browser**: It sets the browser image overlay to use. Supported values: `safari-light`,` safari-dark`.
295+
- **browser**: It sets the browser image overlay to use, being `safari-light` and ` safari-dark` supported values.
385296
- **background**: It sets the background color to use. You can pass a hexadecimal/rgb/rgba or a CSS gradient.
386297

387298
```js
@@ -486,6 +397,10 @@ const browserless = require('browserless')
486397

487398
#### options
488399

400+
Any option passed here will bypass to [page.goto](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options).
401+
402+
Additionally, you can setup:
403+
489404
##### url
490405

491406
type: `string`
@@ -499,6 +414,12 @@ default: `true`
499414

500415
It will be abort requests detected as ads.
501416

417+
##### headers
418+
419+
type: `object` </br>
420+
421+
An object containing additional HTTP headers to be sent with every request.
422+
502423
##### waitFor
503424

504425
type:`string|function|number`</br>
@@ -508,8 +429,8 @@ Wait a quantity of time, selector or function using [page.waitFor](https://githu
508429

509430
##### waitUntil
510431

511-
type:`array`</br>
512-
default: `['networkidle2', 'load', 'domcontentloaded']`
432+
type: `string` | `string[]`</br>
433+
default: `['networkidle0']`
513434

514435
Specify a list of events until consider navigation succeeded, using [page.waitForNavigation](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions).
515436

@@ -521,11 +442,18 @@ It will setup a custom user agent, using [page.setUserAgent](https://github.com/
521442

522443
It will setup a custom viewport, using [page.setViewport](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagesetviewportviewport) method.
523444

524-
##### args
445+
##### cookies
525446

526-
type: `object`
447+
type: `object[]` </br>
527448

528-
The settings to be passed to [page.goto](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options).
449+
A collection of [cookie's object](https://github.com/GoogleChrome/puppeteer/blob/v1.16.0/docs/api.md#pagesetcookiecookies) to set in the requests send.
450+
451+
##### device
452+
453+
type: `string`</br>
454+
default: `'macbook pro 13'`
455+
456+
It specifies the [device](#devices) descriptor to use in order to retrieve `userAgent` and `viewport`
529457

530458
### .page()
531459

@@ -586,13 +514,14 @@ You don't need to think about the acquire/release step: It's done automagically
586514

587515
| Package | Version | Dependencies |
588516
|--------|-------|------------|
589-
| [`browserless`](https://github.com/microlinkhq/metascraper/tree/master/packages/browserless) | [![npm](https://img.shields.io/npm/v/browserless.svg?style=flat-square)](https://www.npmjs.com/package/browserless) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/browserless&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/browserless) |
590-
| [`@browserless/benchmark`](https://github.com/microlinkhq/metascraper/tree/master/packages/@browserless/benchmark) | [![npm](https://img.shields.io/npm/v/@browserless/benchmark.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/benchmark) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/@browserless/benchmark&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/@browserless/benchmark) |
591-
| [`@browserless/devices`](https://github.com/microlinkhq/metascraper/tree/master/packages/@browserless/devices) | [![npm](https://img.shields.io/npm/v/@browserless/devices.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/devices) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/@browserless/devices&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/@browserless/devices) |
592-
| [`@browserless/examples`](https://github.com/microlinkhq/metascraper/tree/master/packages/@browserless/examples) | [![npm](https://img.shields.io/npm/v/@browserless/examples.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/examples) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/@browserless/examples&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/@browserless/examples) |
593-
| [`@browserless/goto`](https://github.com/microlinkhq/metascraper/tree/master/packages/@browserless/goto) | [![npm](https://img.shields.io/npm/v/@browserless/goto.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/goto) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/@browserless/goto&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/@browserless/goto) |
594-
| [`@browserless/pool`](https://github.com/microlinkhq/metascraper/tree/master/packages/@browserless/pool) | [![npm](https://img.shields.io/npm/v/@browserless/pool.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/pool) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/@browserless/pool&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/@browserless/pool) |
595-
| [`@browserless/screenshot`](https://github.com/microlinkhq/metascraper/tree/master/packages/@browserless/screenshot) | [![npm](https://img.shields.io/npm/v/@browserless/screenshot.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/screenshot) | [![Dependency Status](https://david-dm.org/microlinkhq/metascraper.svg?path=packages/@browserless/screenshot&style=flat-square)](https://david-dm.org/microlinkhq/metascraper?path=packages/@browserless/screenshot) |
517+
| [`browserless`](https://github.com/kikobeats/browserless/tree/master/packages/browserless) | [![npm](https://img.shields.io/npm/v/browserless.svg?style=flat-square)](https://www.npmjs.com/package/browserless) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/browserless&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/browserless) |
518+
| [`@browserless/benchmark`](https://github.com/kikobeats/browserless/tree/master/packages/benchmark) | [![npm](https://img.shields.io/npm/v/@browserless/benchmark.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/benchmark) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/benchmark&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/@browserless/benchmark) |
519+
| [`@browserless/devices`](https://github.com/kikobeats/browserless/tree/master/packages/devices) | [![npm](https://img.shields.io/npm/v/@browserless/devices.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/devices) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/devices&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/@browserless/devices) |
520+
| [`@browserless/examples`](https://github.com/kikobeats/browserless/tree/master/packages/examples) | [![npm](https://img.shields.io/npm/v/@browserless/examples.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/examples) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/examples&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/@browserless/examples) |
521+
| [`@browserless/goto`](https://github.com/kikobeats/browserless/tree/master/packages/goto) | [![npm](https://img.shields.io/npm/v/@browserless/goto.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/goto) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/goto&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/@browserless/goto) |
522+
| [`@browserless/pool`](https://github.com/kikobeats/browserless/tree/master/packages/pool) | [![npm](https://img.shields.io/npm/v/@browserless/pool.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/pool) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/pool&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/@browserless/pool) |
523+
| [`@browserless/screenshot`](https://github.com/kikobeats/browserless/tree/master/packages/screenshot) | [![npm](https://img.shields.io/npm/v/@browserless/screenshot.svg?style=flat-square)](https://www.npmjs.com/package/@browserless/screenshot) | [![Dependency Status](https://david-dm.org/kikobeats/browserless.svg?path=packages/screenshot&style=flat-square)](https://david-dm.org/kikobeats/browserless?path=packages/@browserless/screenshot) |
524+
596525

597526
## Benchmark
598527

0 commit comments

Comments
 (0)