@lunora/browser 1.0.0-alpha.7 → 1.0.0-alpha.9

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.
Files changed (4) hide show
  1. package/README.md +2 -0
  2. package/dist/index.d.mts +135 -112
  3. package/dist/index.d.ts +135 -112
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -10,6 +10,8 @@
10
10
 
11
11
  <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
12
12
 
13
+ > **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
14
+
13
15
  <br />
14
16
 
15
17
  <div align="center">
package/dist/index.d.mts CHANGED
@@ -1,27 +1,28 @@
1
1
  /**
2
- * Structural projection of the Cloudflare **Browser Rendering** binding
3
- * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
4
- * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
5
- * marker) so unit tests can pass a plain-object double and the real binding
6
- * satisfies the same shape without importing `@cloudflare/workers-types` into
7
- * the public surface. See https://developers.cloudflare.com/browser-rendering/.
8
- *
9
- * It is intentionally opaque: callers never touch the binding directly, they
10
- * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
11
- * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
12
- * always has one) so the marker actually excludes an arbitrary value like `{}` —
13
- * a bare object fails to type-check where a binding is required, catching the
14
- * misuse at the call site instead of deferring to an opaque launch error.
15
- */
2
+ * Structural projection of the Cloudflare **Browser Rendering** binding
3
+ * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
4
+ * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
5
+ * marker) so unit tests can pass a plain-object double and the real binding
6
+ * satisfies the same shape without importing `@cloudflare/workers-types` into
7
+ * the public surface. See https://developers.cloudflare.com/browser-rendering/.
8
+ *
9
+ * It is intentionally opaque: callers never touch the binding directly, they
10
+ * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
11
+ * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
12
+ * always has one) so the marker actually excludes an arbitrary value like `{}` —
13
+ * a bare object fails to type-check where a binding is required, catching the
14
+ * misuse at the call site instead of deferring to an opaque launch error.
15
+ * @experimental
16
+ */
16
17
  interface BrowserBindingLike {
17
18
  readonly fetch: (...args: never[]) => unknown;
18
19
  }
19
20
  /**
20
- * Minimal projection of a Playwright `Route` (the argument the `page.route`
21
- * handler receives). Only the members the SSRF redirect guard drives are
22
- * declared: inspect the intercepted request's URL / navigation-ness, then either
23
- * let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
24
- */
21
+ * Minimal projection of a Playwright `Route` (the argument the `page.route`
22
+ * handler receives). Only the members the SSRF redirect guard drives are
23
+ * declared: inspect the intercepted request's URL / navigation-ness, then either
24
+ * let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
25
+ */
25
26
  interface RouteLike {
26
27
  /** Reject the intercepted request (fail-closed); `errorCode` is a Playwright abort reason. */
27
28
  abort: (errorCode?: string) => Promise<void>;
@@ -34,10 +35,11 @@ interface RouteLike {
34
35
  };
35
36
  }
36
37
  /**
37
- * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
38
- * Declared structurally so a test can inject a plain stub instead of a real
39
- * headless page (which needs workerd + the Browser Rendering binding).
40
- */
38
+ * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
39
+ * Declared structurally so a test can inject a plain stub instead of a real
40
+ * headless page (which needs workerd + the Browser Rendering binding).
41
+ * @experimental
42
+ */
41
43
  interface PageLike {
42
44
  /** Return the page's serialized HTML after the navigation settles. */
43
45
  content: () => Promise<string>;
@@ -51,11 +53,11 @@ interface PageLike {
51
53
  /** Render the page to a PDF buffer. */
52
54
  pdf: (options?: Record<string, unknown>) => Promise<Uint8Array>;
53
55
  /**
54
- * Register a request interceptor (Playwright `page.route`). Optional: a fake
55
- * or older page double without it still works — the SSRF redirect guard only
56
- * activates when interception is available, and the initial-URL guard applies
57
- * regardless. `pattern` follows Playwright's glob/URL matcher.
58
- */
56
+ * Register a request interceptor (Playwright `page.route`). Optional: a fake
57
+ * or older page double without it still works — the SSRF redirect guard only
58
+ * activates when interception is available, and the initial-URL guard applies
59
+ * regardless. `pattern` follows Playwright's glob/URL matcher.
60
+ */
59
61
  route?: (pattern: string, handler: (route: RouteLike) => unknown) => Promise<void>;
60
62
  /** Render the page to a PNG/JPEG buffer. */
61
63
  screenshot: (options?: Record<string, unknown>) => Promise<Uint8Array>;
@@ -66,154 +68,175 @@ interface PageLike {
66
68
  }) => Promise<void>;
67
69
  }
68
70
  /**
69
- * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
70
- * declared structurally for the same test-double reason as {@link PageLike}.
71
- */
71
+ * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
72
+ * declared structurally for the same test-double reason as {@link PageLike}.
73
+ * @experimental
74
+ */
72
75
  interface BrowserContextLike {
73
76
  newPage: () => Promise<PageLike>;
74
77
  }
75
78
  /**
76
- * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
77
- * Only `newContext`/`close` are used; declared structurally for the same
78
- * test-double reason as {@link PageLike}.
79
- */
79
+ * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
80
+ * Only `newContext`/`close` are used; declared structurally for the same
81
+ * test-double reason as {@link PageLike}.
82
+ * @experimental
83
+ */
80
84
  interface BrowserLike {
81
85
  close: () => Promise<void>;
82
86
  newContext: () => Promise<BrowserContextLike>;
83
87
  }
84
88
  /**
85
- * Structural projection of `@cloudflare/playwright`'s `launch` export
86
- * (`import { launch } from "@cloudflare/playwright"`). Injected via
87
- * {@link LunoraBrowserOptions.launch} so the factory never imports
88
- * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
89
- * dep out of the bundle for apps that never screenshot, and lets tests pass a
90
- * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
91
- */
89
+ * Structural projection of `@cloudflare/playwright`'s `launch` export
90
+ * (`import { launch } from "@cloudflare/playwright"`). Injected via
91
+ * {@link LunoraBrowserOptions.launch} so the factory never imports
92
+ * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
93
+ * dep out of the bundle for apps that never screenshot, and lets tests pass a
94
+ * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
95
+ * @experimental
96
+ */
92
97
  type BrowserLaunchLike = (binding: BrowserBindingLike, options?: Record<string, unknown>) => Promise<BrowserLike>;
93
- /** Options shared by the page-driving helpers ({@link Browser.screenshot} etc.). */
98
+ /**
99
+ * Options shared by the page-driving helpers ({@link Browser.screenshot} etc.).
100
+ * @experimental
101
+ */
94
102
  interface NavigateOptions {
95
103
  /**
96
- * Hard timeout in milliseconds for the navigation + operation. Clamped to a
97
- * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
98
- */
104
+ * Hard timeout in milliseconds for the navigation + operation. Clamped to a
105
+ * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
106
+ */
99
107
  timeoutMs?: number;
100
108
  /**
101
- * Playwright navigation wait condition. Playwright's set differs from
102
- * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
103
- * Default `load`.
104
- */
109
+ * Playwright navigation wait condition. Playwright's set differs from
110
+ * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
111
+ * Default `load`.
112
+ */
105
113
  waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
106
114
  }
107
- /** Options for {@link Browser.screenshot}. */
115
+ /**
116
+ * Options for {@link Browser.screenshot}.
117
+ * @experimental
118
+ */
108
119
  interface ScreenshotOptions extends NavigateOptions {
109
120
  /** Capture the full scrollable page rather than just the viewport. */
110
121
  fullPage?: boolean;
111
122
  /** Image encoding. Default `png`. */
112
123
  type?: "jpeg" | "png";
113
124
  /**
114
- * Viewport size. Each dimension is hard-capped (see the factory's
115
- * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
116
- */
125
+ * Viewport size. Each dimension is hard-capped (see the factory's
126
+ * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
127
+ */
117
128
  viewport?: {
118
129
  height: number;
119
130
  width: number;
120
131
  };
121
132
  }
122
- /** Options for {@link Browser.pdf}. */
133
+ /**
134
+ * Options for {@link Browser.pdf}.
135
+ * @experimental
136
+ */
123
137
  interface PdfOptions extends NavigateOptions {
124
138
  /** Paper format (`A4`, `Letter`, …) forwarded to Playwright. */
125
139
  format?: string;
126
140
  /** Print background graphics. Default `false`. */
127
141
  printBackground?: boolean;
128
142
  /**
129
- * Viewport used while laying out the page before printing. Hard-capped like
130
- * {@link ScreenshotOptions.viewport}.
131
- */
143
+ * Viewport used while laying out the page before printing. Hard-capped like
144
+ * {@link ScreenshotOptions.viewport}.
145
+ */
132
146
  viewport?: {
133
147
  height: number;
134
148
  width: number;
135
149
  };
136
150
  }
151
+ /**
152
+ * `LunoraBrowserOptions` is part of the experimental `@lunora/browser` API and may change without a major version bump.
153
+ * @experimental
154
+ */
137
155
  interface LunoraBrowserOptions {
138
156
  /**
139
- * Strict host allowlist. When set (non-empty), a navigation URL is refused
140
- * unless its hostname exactly matches one of these entries (case-insensitive,
141
- * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
142
- * that fully closes DNS rebinding: a public hostname that resolves to a
143
- * private/metadata IP can still be pinned out if it isn't on the list. Set it
144
- * whenever you pass client-controlled URLs to the browser. Leave it unset (the
145
- * default) to keep the previous behavior (only the string-based SSRF guard).
146
- */
157
+ * Strict host allowlist. When set (non-empty), a navigation URL is refused
158
+ * unless its hostname exactly matches one of these entries (case-insensitive,
159
+ * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
160
+ * that fully closes DNS rebinding: a public hostname that resolves to a
161
+ * private/metadata IP can still be pinned out if it isn't on the list. Set it
162
+ * whenever you pass client-controlled URLs to the browser. Leave it unset (the
163
+ * default) to keep the previous behavior (only the string-based SSRF guard).
164
+ */
147
165
  allowedHosts?: string[];
148
166
  /**
149
- * Opt out of the SSRF guard that, by default, refuses to navigate to a
150
- * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
151
- * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
152
- * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
153
- * `false` (the default) unless every caller-supplied URL is trusted — e.g.
154
- * you deliberately drive the browser at an internal service reachable through
155
- * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
156
- * the SSRF surface, so never combine it with caller-controlled URLs.
157
- */
167
+ * Opt out of the SSRF guard that, by default, refuses to navigate to a
168
+ * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
169
+ * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
170
+ * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
171
+ * `false` (the default) unless every caller-supplied URL is trusted — e.g.
172
+ * you deliberately drive the browser at an internal service reachable through
173
+ * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
174
+ * the SSRF surface, so never combine it with caller-controlled URLs.
175
+ */
158
176
  allowPrivateTargets?: boolean;
159
177
  /** The Cloudflare Browser Rendering binding (`env.BROWSER`). Required. */
160
178
  binding: BrowserBindingLike;
161
179
  /**
162
- * The `@cloudflare/playwright` `launch` function. Injected rather than
163
- * imported at module top so the optional peer dep stays out of the bundle
164
- * for non-browser apps and tests can pass a double. The generated worker
165
- * passes the real function; omitting it makes the helper throw on first use
166
- * with a clear "install `@cloudflare/playwright`" error.
167
- */
180
+ * The `@cloudflare/playwright` `launch` function. Injected rather than
181
+ * imported at module top so the optional peer dep stays out of the bundle
182
+ * for non-browser apps and tests can pass a double. The generated worker
183
+ * passes the real function; omitting it makes the helper throw on first use
184
+ * with a clear "install `@cloudflare/playwright`" error.
185
+ */
168
186
  launch?: BrowserLaunchLike;
169
187
  /**
170
- * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
171
- * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
172
- * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
173
- * resolved A/AAAA record is a private/internal address — closing the gap
174
- * where a public hostname resolves to a private IP after the string guard
175
- * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
176
- * (the browser re-resolves independently). If the DoH lookup itself fails, it
177
- * falls back to the string guard rather than allowing a resolved private IP.
178
- * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
179
- */
188
+ * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
189
+ * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
190
+ * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
191
+ * resolved A/AAAA record is a private/internal address — closing the gap
192
+ * where a public hostname resolves to a private IP after the string guard
193
+ * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
194
+ * (the browser re-resolves independently). If the DoH lookup itself fails, it
195
+ * falls back to the string guard rather than allowing a resolved private IP.
196
+ * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
197
+ */
180
198
  resolveDns?: boolean;
181
199
  /**
182
- * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
183
- * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
184
- */
200
+ * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
201
+ * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
202
+ */
185
203
  timeoutMs?: number;
186
204
  }
187
205
  /**
188
- * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
189
- * `@cloudflare/playwright`. **Action-only**: every method performs
190
- * non-deterministic network I/O (it navigates a real headless browser to a
191
- * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
192
- * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
193
- * browser, opens a context + page, navigates, performs the op, and always
194
- * closes the browser in a `finally` (a leaked session is billed and
195
- * rate-limited).
196
- */
206
+ * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
207
+ * `@cloudflare/playwright`. **Action-only**: every method performs
208
+ * non-deterministic network I/O (it navigates a real headless browser to a
209
+ * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
210
+ * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
211
+ * browser, opens a context + page, navigates, performs the op, and always
212
+ * closes the browser in a `finally` (a leaked session is billed and
213
+ * rate-limited).
214
+ * @experimental
215
+ */
197
216
  interface Browser {
198
217
  /** Serialized HTML of `url` after navigation settles. */
199
218
  content: (url: string, options?: NavigateOptions) => Promise<string>;
200
219
  /**
201
- * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
202
- * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
203
- * **always closed** when `fn` resolves or throws — do not retain references
204
- * to it past the callback.
205
- */
220
+ * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
221
+ * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
222
+ * **always closed** when `fn` resolves or throws — do not retain references
223
+ * to it past the callback.
224
+ */
206
225
  launch: <T>(function_: (browser: BrowserLike) => Promise<T>) => Promise<T>;
207
226
  /** Render `url` to a PDF buffer. */
208
227
  pdf: (url: string, options?: PdfOptions) => Promise<Uint8Array>;
209
228
  /**
210
- * Navigate to `url`, run `fn` inside the page context, and return its
211
- * (serializable) result. `fn` runs in the browser, not the worker — it
212
- * cannot close over worker-side variables.
213
- */
229
+ * Navigate to `url`, run `fn` inside the page context, and return its
230
+ * (serializable) result. `fn` runs in the browser, not the worker — it
231
+ * cannot close over worker-side variables.
232
+ */
214
233
  scrape: <T>(url: string, function_: (...args: never[]) => T, options?: NavigateOptions) => Promise<T>;
215
234
  /** Render `url` to an image buffer (PNG by default). */
216
235
  screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
217
236
  }
237
+ /**
238
+ * `createBrowser` is part of the experimental `@lunora/browser` API and may change without a major version bump.
239
+ * @experimental
240
+ */
218
241
  declare const createBrowser: (options: LunoraBrowserOptions) => Browser;
219
242
  export { type Browser, type BrowserBindingLike, type BrowserContextLike, type BrowserLaunchLike, type BrowserLike, type LunoraBrowserOptions, type NavigateOptions, type PageLike, type PdfOptions, type ScreenshotOptions, createBrowser };
package/dist/index.d.ts CHANGED
@@ -1,27 +1,28 @@
1
1
  /**
2
- * Structural projection of the Cloudflare **Browser Rendering** binding
3
- * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
4
- * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
5
- * marker) so unit tests can pass a plain-object double and the real binding
6
- * satisfies the same shape without importing `@cloudflare/workers-types` into
7
- * the public surface. See https://developers.cloudflare.com/browser-rendering/.
8
- *
9
- * It is intentionally opaque: callers never touch the binding directly, they
10
- * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
11
- * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
12
- * always has one) so the marker actually excludes an arbitrary value like `{}` —
13
- * a bare object fails to type-check where a binding is required, catching the
14
- * misuse at the call site instead of deferring to an opaque launch error.
15
- */
2
+ * Structural projection of the Cloudflare **Browser Rendering** binding
3
+ * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
4
+ * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
5
+ * marker) so unit tests can pass a plain-object double and the real binding
6
+ * satisfies the same shape without importing `@cloudflare/workers-types` into
7
+ * the public surface. See https://developers.cloudflare.com/browser-rendering/.
8
+ *
9
+ * It is intentionally opaque: callers never touch the binding directly, they
10
+ * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
11
+ * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
12
+ * always has one) so the marker actually excludes an arbitrary value like `{}` —
13
+ * a bare object fails to type-check where a binding is required, catching the
14
+ * misuse at the call site instead of deferring to an opaque launch error.
15
+ * @experimental
16
+ */
16
17
  interface BrowserBindingLike {
17
18
  readonly fetch: (...args: never[]) => unknown;
18
19
  }
19
20
  /**
20
- * Minimal projection of a Playwright `Route` (the argument the `page.route`
21
- * handler receives). Only the members the SSRF redirect guard drives are
22
- * declared: inspect the intercepted request's URL / navigation-ness, then either
23
- * let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
24
- */
21
+ * Minimal projection of a Playwright `Route` (the argument the `page.route`
22
+ * handler receives). Only the members the SSRF redirect guard drives are
23
+ * declared: inspect the intercepted request's URL / navigation-ness, then either
24
+ * let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
25
+ */
25
26
  interface RouteLike {
26
27
  /** Reject the intercepted request (fail-closed); `errorCode` is a Playwright abort reason. */
27
28
  abort: (errorCode?: string) => Promise<void>;
@@ -34,10 +35,11 @@ interface RouteLike {
34
35
  };
35
36
  }
36
37
  /**
37
- * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
38
- * Declared structurally so a test can inject a plain stub instead of a real
39
- * headless page (which needs workerd + the Browser Rendering binding).
40
- */
38
+ * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
39
+ * Declared structurally so a test can inject a plain stub instead of a real
40
+ * headless page (which needs workerd + the Browser Rendering binding).
41
+ * @experimental
42
+ */
41
43
  interface PageLike {
42
44
  /** Return the page's serialized HTML after the navigation settles. */
43
45
  content: () => Promise<string>;
@@ -51,11 +53,11 @@ interface PageLike {
51
53
  /** Render the page to a PDF buffer. */
52
54
  pdf: (options?: Record<string, unknown>) => Promise<Uint8Array>;
53
55
  /**
54
- * Register a request interceptor (Playwright `page.route`). Optional: a fake
55
- * or older page double without it still works — the SSRF redirect guard only
56
- * activates when interception is available, and the initial-URL guard applies
57
- * regardless. `pattern` follows Playwright's glob/URL matcher.
58
- */
56
+ * Register a request interceptor (Playwright `page.route`). Optional: a fake
57
+ * or older page double without it still works — the SSRF redirect guard only
58
+ * activates when interception is available, and the initial-URL guard applies
59
+ * regardless. `pattern` follows Playwright's glob/URL matcher.
60
+ */
59
61
  route?: (pattern: string, handler: (route: RouteLike) => unknown) => Promise<void>;
60
62
  /** Render the page to a PNG/JPEG buffer. */
61
63
  screenshot: (options?: Record<string, unknown>) => Promise<Uint8Array>;
@@ -66,154 +68,175 @@ interface PageLike {
66
68
  }) => Promise<void>;
67
69
  }
68
70
  /**
69
- * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
70
- * declared structurally for the same test-double reason as {@link PageLike}.
71
- */
71
+ * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
72
+ * declared structurally for the same test-double reason as {@link PageLike}.
73
+ * @experimental
74
+ */
72
75
  interface BrowserContextLike {
73
76
  newPage: () => Promise<PageLike>;
74
77
  }
75
78
  /**
76
- * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
77
- * Only `newContext`/`close` are used; declared structurally for the same
78
- * test-double reason as {@link PageLike}.
79
- */
79
+ * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
80
+ * Only `newContext`/`close` are used; declared structurally for the same
81
+ * test-double reason as {@link PageLike}.
82
+ * @experimental
83
+ */
80
84
  interface BrowserLike {
81
85
  close: () => Promise<void>;
82
86
  newContext: () => Promise<BrowserContextLike>;
83
87
  }
84
88
  /**
85
- * Structural projection of `@cloudflare/playwright`'s `launch` export
86
- * (`import { launch } from "@cloudflare/playwright"`). Injected via
87
- * {@link LunoraBrowserOptions.launch} so the factory never imports
88
- * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
89
- * dep out of the bundle for apps that never screenshot, and lets tests pass a
90
- * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
91
- */
89
+ * Structural projection of `@cloudflare/playwright`'s `launch` export
90
+ * (`import { launch } from "@cloudflare/playwright"`). Injected via
91
+ * {@link LunoraBrowserOptions.launch} so the factory never imports
92
+ * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
93
+ * dep out of the bundle for apps that never screenshot, and lets tests pass a
94
+ * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
95
+ * @experimental
96
+ */
92
97
  type BrowserLaunchLike = (binding: BrowserBindingLike, options?: Record<string, unknown>) => Promise<BrowserLike>;
93
- /** Options shared by the page-driving helpers ({@link Browser.screenshot} etc.). */
98
+ /**
99
+ * Options shared by the page-driving helpers ({@link Browser.screenshot} etc.).
100
+ * @experimental
101
+ */
94
102
  interface NavigateOptions {
95
103
  /**
96
- * Hard timeout in milliseconds for the navigation + operation. Clamped to a
97
- * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
98
- */
104
+ * Hard timeout in milliseconds for the navigation + operation. Clamped to a
105
+ * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
106
+ */
99
107
  timeoutMs?: number;
100
108
  /**
101
- * Playwright navigation wait condition. Playwright's set differs from
102
- * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
103
- * Default `load`.
104
- */
109
+ * Playwright navigation wait condition. Playwright's set differs from
110
+ * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
111
+ * Default `load`.
112
+ */
105
113
  waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
106
114
  }
107
- /** Options for {@link Browser.screenshot}. */
115
+ /**
116
+ * Options for {@link Browser.screenshot}.
117
+ * @experimental
118
+ */
108
119
  interface ScreenshotOptions extends NavigateOptions {
109
120
  /** Capture the full scrollable page rather than just the viewport. */
110
121
  fullPage?: boolean;
111
122
  /** Image encoding. Default `png`. */
112
123
  type?: "jpeg" | "png";
113
124
  /**
114
- * Viewport size. Each dimension is hard-capped (see the factory's
115
- * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
116
- */
125
+ * Viewport size. Each dimension is hard-capped (see the factory's
126
+ * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
127
+ */
117
128
  viewport?: {
118
129
  height: number;
119
130
  width: number;
120
131
  };
121
132
  }
122
- /** Options for {@link Browser.pdf}. */
133
+ /**
134
+ * Options for {@link Browser.pdf}.
135
+ * @experimental
136
+ */
123
137
  interface PdfOptions extends NavigateOptions {
124
138
  /** Paper format (`A4`, `Letter`, …) forwarded to Playwright. */
125
139
  format?: string;
126
140
  /** Print background graphics. Default `false`. */
127
141
  printBackground?: boolean;
128
142
  /**
129
- * Viewport used while laying out the page before printing. Hard-capped like
130
- * {@link ScreenshotOptions.viewport}.
131
- */
143
+ * Viewport used while laying out the page before printing. Hard-capped like
144
+ * {@link ScreenshotOptions.viewport}.
145
+ */
132
146
  viewport?: {
133
147
  height: number;
134
148
  width: number;
135
149
  };
136
150
  }
151
+ /**
152
+ * `LunoraBrowserOptions` is part of the experimental `@lunora/browser` API and may change without a major version bump.
153
+ * @experimental
154
+ */
137
155
  interface LunoraBrowserOptions {
138
156
  /**
139
- * Strict host allowlist. When set (non-empty), a navigation URL is refused
140
- * unless its hostname exactly matches one of these entries (case-insensitive,
141
- * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
142
- * that fully closes DNS rebinding: a public hostname that resolves to a
143
- * private/metadata IP can still be pinned out if it isn't on the list. Set it
144
- * whenever you pass client-controlled URLs to the browser. Leave it unset (the
145
- * default) to keep the previous behavior (only the string-based SSRF guard).
146
- */
157
+ * Strict host allowlist. When set (non-empty), a navigation URL is refused
158
+ * unless its hostname exactly matches one of these entries (case-insensitive,
159
+ * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
160
+ * that fully closes DNS rebinding: a public hostname that resolves to a
161
+ * private/metadata IP can still be pinned out if it isn't on the list. Set it
162
+ * whenever you pass client-controlled URLs to the browser. Leave it unset (the
163
+ * default) to keep the previous behavior (only the string-based SSRF guard).
164
+ */
147
165
  allowedHosts?: string[];
148
166
  /**
149
- * Opt out of the SSRF guard that, by default, refuses to navigate to a
150
- * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
151
- * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
152
- * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
153
- * `false` (the default) unless every caller-supplied URL is trusted — e.g.
154
- * you deliberately drive the browser at an internal service reachable through
155
- * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
156
- * the SSRF surface, so never combine it with caller-controlled URLs.
157
- */
167
+ * Opt out of the SSRF guard that, by default, refuses to navigate to a
168
+ * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
169
+ * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
170
+ * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
171
+ * `false` (the default) unless every caller-supplied URL is trusted — e.g.
172
+ * you deliberately drive the browser at an internal service reachable through
173
+ * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
174
+ * the SSRF surface, so never combine it with caller-controlled URLs.
175
+ */
158
176
  allowPrivateTargets?: boolean;
159
177
  /** The Cloudflare Browser Rendering binding (`env.BROWSER`). Required. */
160
178
  binding: BrowserBindingLike;
161
179
  /**
162
- * The `@cloudflare/playwright` `launch` function. Injected rather than
163
- * imported at module top so the optional peer dep stays out of the bundle
164
- * for non-browser apps and tests can pass a double. The generated worker
165
- * passes the real function; omitting it makes the helper throw on first use
166
- * with a clear "install `@cloudflare/playwright`" error.
167
- */
180
+ * The `@cloudflare/playwright` `launch` function. Injected rather than
181
+ * imported at module top so the optional peer dep stays out of the bundle
182
+ * for non-browser apps and tests can pass a double. The generated worker
183
+ * passes the real function; omitting it makes the helper throw on first use
184
+ * with a clear "install `@cloudflare/playwright`" error.
185
+ */
168
186
  launch?: BrowserLaunchLike;
169
187
  /**
170
- * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
171
- * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
172
- * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
173
- * resolved A/AAAA record is a private/internal address — closing the gap
174
- * where a public hostname resolves to a private IP after the string guard
175
- * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
176
- * (the browser re-resolves independently). If the DoH lookup itself fails, it
177
- * falls back to the string guard rather than allowing a resolved private IP.
178
- * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
179
- */
188
+ * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
189
+ * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
190
+ * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
191
+ * resolved A/AAAA record is a private/internal address — closing the gap
192
+ * where a public hostname resolves to a private IP after the string guard
193
+ * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
194
+ * (the browser re-resolves independently). If the DoH lookup itself fails, it
195
+ * falls back to the string guard rather than allowing a resolved private IP.
196
+ * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
197
+ */
180
198
  resolveDns?: boolean;
181
199
  /**
182
- * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
183
- * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
184
- */
200
+ * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
201
+ * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
202
+ */
185
203
  timeoutMs?: number;
186
204
  }
187
205
  /**
188
- * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
189
- * `@cloudflare/playwright`. **Action-only**: every method performs
190
- * non-deterministic network I/O (it navigates a real headless browser to a
191
- * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
192
- * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
193
- * browser, opens a context + page, navigates, performs the op, and always
194
- * closes the browser in a `finally` (a leaked session is billed and
195
- * rate-limited).
196
- */
206
+ * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
207
+ * `@cloudflare/playwright`. **Action-only**: every method performs
208
+ * non-deterministic network I/O (it navigates a real headless browser to a
209
+ * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
210
+ * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
211
+ * browser, opens a context + page, navigates, performs the op, and always
212
+ * closes the browser in a `finally` (a leaked session is billed and
213
+ * rate-limited).
214
+ * @experimental
215
+ */
197
216
  interface Browser {
198
217
  /** Serialized HTML of `url` after navigation settles. */
199
218
  content: (url: string, options?: NavigateOptions) => Promise<string>;
200
219
  /**
201
- * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
202
- * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
203
- * **always closed** when `fn` resolves or throws — do not retain references
204
- * to it past the callback.
205
- */
220
+ * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
221
+ * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
222
+ * **always closed** when `fn` resolves or throws — do not retain references
223
+ * to it past the callback.
224
+ */
206
225
  launch: <T>(function_: (browser: BrowserLike) => Promise<T>) => Promise<T>;
207
226
  /** Render `url` to a PDF buffer. */
208
227
  pdf: (url: string, options?: PdfOptions) => Promise<Uint8Array>;
209
228
  /**
210
- * Navigate to `url`, run `fn` inside the page context, and return its
211
- * (serializable) result. `fn` runs in the browser, not the worker — it
212
- * cannot close over worker-side variables.
213
- */
229
+ * Navigate to `url`, run `fn` inside the page context, and return its
230
+ * (serializable) result. `fn` runs in the browser, not the worker — it
231
+ * cannot close over worker-side variables.
232
+ */
214
233
  scrape: <T>(url: string, function_: (...args: never[]) => T, options?: NavigateOptions) => Promise<T>;
215
234
  /** Render `url` to an image buffer (PNG by default). */
216
235
  screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
217
236
  }
237
+ /**
238
+ * `createBrowser` is part of the experimental `@lunora/browser` API and may change without a major version bump.
239
+ * @experimental
240
+ */
218
241
  declare const createBrowser: (options: LunoraBrowserOptions) => Browser;
219
242
  export { type Browser, type BrowserBindingLike, type BrowserContextLike, type BrowserLaunchLike, type BrowserLike, type LunoraBrowserOptions, type NavigateOptions, type PageLike, type PdfOptions, type ScreenshotOptions, createBrowser };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lunora/browser",
3
- "version": "1.0.0-alpha.7",
3
+ "version": "1.0.0-alpha.9",
4
4
  "description": "Cloudflare Browser Rendering for Lunora: ctx.browser screenshots, PDF, and scraping in actions",
5
5
  "keywords": [
6
6
  "browser-rendering",
@@ -46,7 +46,7 @@
46
46
  "access": "public"
47
47
  },
48
48
  "dependencies": {
49
- "@lunora/errors": "1.0.0-alpha.4"
49
+ "@lunora/errors": "1.0.0-alpha.6"
50
50
  },
51
51
  "peerDependencies": {
52
52
  "@cloudflare/playwright": ">=1.0.0"