@bctrl/sdk 1.0.1 → 1.0.2

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 (279) hide show
  1. package/README.md +24 -29
  2. package/dist/bctrl.d.ts +22 -36
  3. package/dist/bctrl.js +40 -75
  4. package/dist/browsers.d.ts +24 -0
  5. package/dist/browsers.js +82 -0
  6. package/dist/errors.d.ts +49 -43
  7. package/dist/errors.js +83 -120
  8. package/dist/files.d.ts +31 -0
  9. package/dist/files.js +97 -0
  10. package/dist/http.d.ts +18 -0
  11. package/dist/http.js +135 -0
  12. package/dist/index.d.ts +9 -12
  13. package/dist/index.js +8 -23
  14. package/dist/invocations.d.ts +24 -0
  15. package/dist/invocations.js +66 -0
  16. package/dist/pagination.d.ts +2 -0
  17. package/dist/pagination.js +13 -0
  18. package/dist/runs.d.ts +38 -0
  19. package/dist/runs.js +99 -0
  20. package/dist/runtimes.d.ts +73 -0
  21. package/dist/runtimes.js +205 -0
  22. package/dist/spaces.d.ts +41 -0
  23. package/dist/spaces.js +96 -0
  24. package/dist/types.d.ts +386 -0
  25. package/dist/types.js +1 -0
  26. package/dist/utils.d.ts +4 -0
  27. package/dist/utils.js +27 -0
  28. package/dist/version.js +2 -2
  29. package/package.json +12 -31
  30. package/dist/agents/browser-use/index.d.ts +0 -1
  31. package/dist/agents/browser-use/index.js +0 -9
  32. package/dist/agents/browser-use/namespace.d.ts +0 -39
  33. package/dist/agents/browser-use/namespace.js +0 -93
  34. package/dist/agents/index.d.ts +0 -2
  35. package/dist/agents/index.js +0 -17
  36. package/dist/agents/stagehand/core.d.ts +0 -93
  37. package/dist/agents/stagehand/core.js +0 -144
  38. package/dist/agents/stagehand/index.d.ts +0 -3
  39. package/dist/agents/stagehand/index.js +0 -24
  40. package/dist/agents/stagehand/namespace.d.ts +0 -51
  41. package/dist/agents/stagehand/namespace.js +0 -65
  42. package/dist/ai-credentials/client.d.ts +0 -12
  43. package/dist/ai-credentials/client.js +0 -70
  44. package/dist/ai-credentials/index.d.ts +0 -1
  45. package/dist/ai-credentials/index.js +0 -1
  46. package/dist/base/event-binding.d.ts +0 -7
  47. package/dist/base/event-binding.js +0 -23
  48. package/dist/base/types.d.ts +0 -109
  49. package/dist/base/types.js +0 -4
  50. package/dist/browser-extensions/client.d.ts +0 -15
  51. package/dist/browser-extensions/client.js +0 -72
  52. package/dist/browser-extensions/index.d.ts +0 -2
  53. package/dist/browser-extensions/index.js +0 -1
  54. package/dist/browser-profiles/client.d.ts +0 -11
  55. package/dist/browser-profiles/client.js +0 -63
  56. package/dist/browser-profiles/index.d.ts +0 -1
  57. package/dist/browser-profiles/index.js +0 -1
  58. package/dist/captcha/index.d.ts +0 -1
  59. package/dist/captcha/index.js +0 -1
  60. package/dist/captcha/namespace.d.ts +0 -34
  61. package/dist/captcha/namespace.js +0 -41
  62. package/dist/client/index.d.ts +0 -1
  63. package/dist/client/index.js +0 -1
  64. package/dist/client/rpc.d.ts +0 -83
  65. package/dist/client/rpc.js +0 -354
  66. package/dist/config.d.ts +0 -5
  67. package/dist/config.js +0 -28
  68. package/dist/constants/browser.d.ts +0 -2
  69. package/dist/constants/browser.js +0 -1
  70. package/dist/contracts/agent-tools.d.ts +0 -45
  71. package/dist/contracts/agent-tools.js +0 -31
  72. package/dist/contracts/automation.d.ts +0 -265
  73. package/dist/contracts/automation.js +0 -109
  74. package/dist/contracts/browser-management.d.ts +0 -179
  75. package/dist/contracts/browser-management.js +0 -95
  76. package/dist/contracts/browser-use.d.ts +0 -136
  77. package/dist/contracts/browser-use.js +0 -93
  78. package/dist/contracts/captcha.d.ts +0 -114
  79. package/dist/contracts/captcha.js +0 -40
  80. package/dist/contracts/desktop.d.ts +0 -223
  81. package/dist/contracts/desktop.js +0 -121
  82. package/dist/contracts/drivers/playwright.d.ts +0 -2008
  83. package/dist/contracts/drivers/playwright.js +0 -2033
  84. package/dist/contracts/drivers/puppeteer.d.ts +0 -1221
  85. package/dist/contracts/drivers/puppeteer.js +0 -941
  86. package/dist/contracts/drivers/selenium.d.ts +0 -156
  87. package/dist/contracts/drivers/selenium.js +0 -61
  88. package/dist/contracts/drivers/stagehand.d.ts +0 -155
  89. package/dist/contracts/drivers/stagehand.js +0 -7
  90. package/dist/contracts/extensions.d.ts +0 -13
  91. package/dist/contracts/extensions.js +0 -9
  92. package/dist/contracts/index.d.ts +0 -13
  93. package/dist/contracts/index.js +0 -13
  94. package/dist/contracts/public-api.d.ts +0 -360
  95. package/dist/contracts/public-api.js +0 -17
  96. package/dist/contracts/runtime.d.ts +0 -81
  97. package/dist/contracts/runtime.js +0 -16
  98. package/dist/contracts/stagehand.d.ts +0 -253
  99. package/dist/contracts/stagehand.js +0 -145
  100. package/dist/contracts/storage.d.ts +0 -51
  101. package/dist/contracts/storage.js +0 -56
  102. package/dist/contracts/vault.d.ts +0 -119
  103. package/dist/contracts/vault.js +0 -112
  104. package/dist/contracts/version.d.ts +0 -3
  105. package/dist/contracts/version.js +0 -16
  106. package/dist/desktop.d.ts +0 -2
  107. package/dist/desktop.js +0 -3
  108. package/dist/drivers/desktop/index.d.ts +0 -65
  109. package/dist/drivers/desktop/index.js +0 -68
  110. package/dist/drivers/desktop/session.d.ts +0 -313
  111. package/dist/drivers/desktop/session.js +0 -432
  112. package/dist/drivers/playwright/event-emitter.d.ts +0 -160
  113. package/dist/drivers/playwright/event-emitter.js +0 -297
  114. package/dist/drivers/playwright/generated/api-request-context.d.ts +0 -137
  115. package/dist/drivers/playwright/generated/api-request-context.js +0 -154
  116. package/dist/drivers/playwright/generated/api-response.d.ts +0 -119
  117. package/dist/drivers/playwright/generated/api-response.js +0 -123
  118. package/dist/drivers/playwright/generated/browser-context.d.ts +0 -284
  119. package/dist/drivers/playwright/generated/browser-context.js +0 -458
  120. package/dist/drivers/playwright/generated/browser.d.ts +0 -120
  121. package/dist/drivers/playwright/generated/browser.js +0 -151
  122. package/dist/drivers/playwright/generated/clock.d.ts +0 -80
  123. package/dist/drivers/playwright/generated/clock.js +0 -94
  124. package/dist/drivers/playwright/generated/console-message.d.ts +0 -94
  125. package/dist/drivers/playwright/generated/console-message.js +0 -89
  126. package/dist/drivers/playwright/generated/coverage.d.ts +0 -57
  127. package/dist/drivers/playwright/generated/coverage.js +0 -66
  128. package/dist/drivers/playwright/generated/dialog.d.ts +0 -79
  129. package/dist/drivers/playwright/generated/dialog.js +0 -80
  130. package/dist/drivers/playwright/generated/element-handle.d.ts +0 -399
  131. package/dist/drivers/playwright/generated/element-handle.js +0 -501
  132. package/dist/drivers/playwright/generated/frame-locator.d.ts +0 -34
  133. package/dist/drivers/playwright/generated/frame-locator.js +0 -63
  134. package/dist/drivers/playwright/generated/frame.d.ts +0 -557
  135. package/dist/drivers/playwright/generated/frame.js +0 -634
  136. package/dist/drivers/playwright/generated/js-handle.d.ts +0 -72
  137. package/dist/drivers/playwright/generated/js-handle.js +0 -92
  138. package/dist/drivers/playwright/generated/keyboard.d.ts +0 -103
  139. package/dist/drivers/playwright/generated/keyboard.js +0 -113
  140. package/dist/drivers/playwright/generated/locator.d.ts +0 -795
  141. package/dist/drivers/playwright/generated/locator.js +0 -974
  142. package/dist/drivers/playwright/generated/mouse.d.ts +0 -97
  143. package/dist/drivers/playwright/generated/mouse.js +0 -109
  144. package/dist/drivers/playwright/generated/page.d.ts +0 -762
  145. package/dist/drivers/playwright/generated/page.js +0 -988
  146. package/dist/drivers/playwright/generated/touchscreen.d.ts +0 -34
  147. package/dist/drivers/playwright/generated/touchscreen.js +0 -37
  148. package/dist/drivers/playwright/generated/tracing.d.ts +0 -78
  149. package/dist/drivers/playwright/generated/tracing.js +0 -80
  150. package/dist/drivers/playwright/generated/worker.d.ts +0 -53
  151. package/dist/drivers/playwright/generated/worker.js +0 -59
  152. package/dist/drivers/playwright/index.d.ts +0 -19
  153. package/dist/drivers/playwright/index.js +0 -20
  154. package/dist/drivers/playwright/remote-base.d.ts +0 -62
  155. package/dist/drivers/playwright/remote-base.js +0 -86
  156. package/dist/drivers/playwright/types.d.ts +0 -148
  157. package/dist/drivers/playwright/types.js +0 -8
  158. package/dist/drivers/puppeteer/errors.d.ts +0 -50
  159. package/dist/drivers/puppeteer/errors.js +0 -71
  160. package/dist/drivers/puppeteer/event-emitter.d.ts +0 -145
  161. package/dist/drivers/puppeteer/event-emitter.js +0 -259
  162. package/dist/drivers/puppeteer/generated/accessibility.d.ts +0 -77
  163. package/dist/drivers/puppeteer/generated/accessibility.js +0 -74
  164. package/dist/drivers/puppeteer/generated/browser-context.d.ts +0 -116
  165. package/dist/drivers/puppeteer/generated/browser-context.js +0 -168
  166. package/dist/drivers/puppeteer/generated/browser.d.ts +0 -169
  167. package/dist/drivers/puppeteer/generated/browser.js +0 -246
  168. package/dist/drivers/puppeteer/generated/console-message.d.ts +0 -54
  169. package/dist/drivers/puppeteer/generated/console-message.js +0 -69
  170. package/dist/drivers/puppeteer/generated/coverage.d.ts +0 -49
  171. package/dist/drivers/puppeteer/generated/coverage.js +0 -57
  172. package/dist/drivers/puppeteer/generated/dialog.d.ts +0 -46
  173. package/dist/drivers/puppeteer/generated/dialog.js +0 -60
  174. package/dist/drivers/puppeteer/generated/element-handle.d.ts +0 -261
  175. package/dist/drivers/puppeteer/generated/element-handle.js +0 -341
  176. package/dist/drivers/puppeteer/generated/file-chooser.d.ts +0 -34
  177. package/dist/drivers/puppeteer/generated/file-chooser.js +0 -43
  178. package/dist/drivers/puppeteer/generated/frame.d.ts +0 -221
  179. package/dist/drivers/puppeteer/generated/frame.js +0 -302
  180. package/dist/drivers/puppeteer/generated/http-request.d.ts +0 -195
  181. package/dist/drivers/puppeteer/generated/http-request.js +0 -243
  182. package/dist/drivers/puppeteer/generated/http-response.d.ts +0 -142
  183. package/dist/drivers/puppeteer/generated/http-response.js +0 -169
  184. package/dist/drivers/puppeteer/generated/js-handle.d.ts +0 -104
  185. package/dist/drivers/puppeteer/generated/js-handle.js +0 -125
  186. package/dist/drivers/puppeteer/generated/keyboard.d.ts +0 -79
  187. package/dist/drivers/puppeteer/generated/keyboard.js +0 -89
  188. package/dist/drivers/puppeteer/generated/locator.d.ts +0 -141
  189. package/dist/drivers/puppeteer/generated/locator.js +0 -164
  190. package/dist/drivers/puppeteer/generated/mouse.d.ts +0 -74
  191. package/dist/drivers/puppeteer/generated/mouse.js +0 -94
  192. package/dist/drivers/puppeteer/generated/page.d.ts +0 -604
  193. package/dist/drivers/puppeteer/generated/page.js +0 -776
  194. package/dist/drivers/puppeteer/generated/target.d.ts +0 -105
  195. package/dist/drivers/puppeteer/generated/target.js +0 -123
  196. package/dist/drivers/puppeteer/generated/touchscreen.d.ts +0 -87
  197. package/dist/drivers/puppeteer/generated/touchscreen.js +0 -103
  198. package/dist/drivers/puppeteer/generated/tracing.d.ts +0 -38
  199. package/dist/drivers/puppeteer/generated/tracing.js +0 -43
  200. package/dist/drivers/puppeteer/generated/web-worker.d.ts +0 -63
  201. package/dist/drivers/puppeteer/generated/web-worker.js +0 -73
  202. package/dist/drivers/puppeteer/index.d.ts +0 -21
  203. package/dist/drivers/puppeteer/index.js +0 -23
  204. package/dist/drivers/puppeteer/remote-base.d.ts +0 -57
  205. package/dist/drivers/puppeteer/remote-base.js +0 -79
  206. package/dist/drivers/puppeteer/types.d.ts +0 -178
  207. package/dist/drivers/puppeteer/types.js +0 -8
  208. package/dist/drivers/selenium/driver.d.ts +0 -28
  209. package/dist/drivers/selenium/driver.js +0 -169
  210. package/dist/drivers/selenium/element.d.ts +0 -34
  211. package/dist/drivers/selenium/element.js +0 -73
  212. package/dist/drivers/selenium/index.d.ts +0 -3
  213. package/dist/drivers/selenium/index.js +0 -5
  214. package/dist/drivers/selenium/types.d.ts +0 -2
  215. package/dist/drivers/selenium/types.js +0 -12
  216. package/dist/drivers/stagehand/generated/context.d.ts +0 -127
  217. package/dist/drivers/stagehand/generated/context.js +0 -153
  218. package/dist/drivers/stagehand/generated/locator.d.ts +0 -324
  219. package/dist/drivers/stagehand/generated/locator.js +0 -368
  220. package/dist/drivers/stagehand/generated/page.d.ts +0 -377
  221. package/dist/drivers/stagehand/generated/page.js +0 -439
  222. package/dist/drivers/stagehand/generated/response.d.ts +0 -197
  223. package/dist/drivers/stagehand/generated/response.js +0 -232
  224. package/dist/drivers/stagehand/index.d.ts +0 -5
  225. package/dist/drivers/stagehand/index.js +0 -8
  226. package/dist/drivers/stagehand/types.d.ts +0 -1
  227. package/dist/drivers/stagehand/types.js +0 -7
  228. package/dist/extensions/client.d.ts +0 -47
  229. package/dist/extensions/client.js +0 -154
  230. package/dist/extensions/index.d.ts +0 -1
  231. package/dist/extensions/index.js +0 -1
  232. package/dist/internal/dev-client.d.ts +0 -5
  233. package/dist/internal/dev-client.js +0 -9
  234. package/dist/internal/rpc-targets.d.ts +0 -17
  235. package/dist/internal/rpc-targets.js +0 -58
  236. package/dist/internal/serialization.d.ts +0 -32
  237. package/dist/internal/serialization.js +0 -42
  238. package/dist/internal/transport.d.ts +0 -24
  239. package/dist/internal/transport.js +0 -29
  240. package/dist/playwright.d.ts +0 -1
  241. package/dist/playwright.js +0 -2
  242. package/dist/puppeteer.d.ts +0 -1
  243. package/dist/puppeteer.js +0 -2
  244. package/dist/selenium.d.ts +0 -1
  245. package/dist/selenium.js +0 -2
  246. package/dist/stagehand.d.ts +0 -1
  247. package/dist/stagehand.js +0 -2
  248. package/dist/storage/client.d.ts +0 -151
  249. package/dist/storage/client.js +0 -329
  250. package/dist/storage/index.d.ts +0 -2
  251. package/dist/storage/index.js +0 -4
  252. package/dist/telemetry.d.ts +0 -18
  253. package/dist/telemetry.js +0 -93
  254. package/dist/updates/client.d.ts +0 -8
  255. package/dist/updates/client.js +0 -128
  256. package/dist/updates/index.d.ts +0 -1
  257. package/dist/updates/index.js +0 -1
  258. package/dist/utils/http.d.ts +0 -39
  259. package/dist/utils/http.js +0 -88
  260. package/dist/utils/index.d.ts +0 -4
  261. package/dist/utils/index.js +0 -4
  262. package/dist/utils/logger.d.ts +0 -27
  263. package/dist/utils/logger.js +0 -74
  264. package/dist/utils/schema.d.ts +0 -17
  265. package/dist/utils/schema.js +0 -31
  266. package/dist/utils/url.d.ts +0 -5
  267. package/dist/utils/url.js +0 -7
  268. package/dist/vault/client.d.ts +0 -43
  269. package/dist/vault/client.js +0 -123
  270. package/dist/vault/index.d.ts +0 -1
  271. package/dist/vault/index.js +0 -1
  272. package/dist/workspaces/browser-runtime.d.ts +0 -251
  273. package/dist/workspaces/browser-runtime.js +0 -1025
  274. package/dist/workspaces/client.d.ts +0 -48
  275. package/dist/workspaces/client.js +0 -222
  276. package/dist/workspaces/index.d.ts +0 -2
  277. package/dist/workspaces/index.js +0 -2
  278. package/dist/workspaces/runtime-event-pump.d.ts +0 -65
  279. package/dist/workspaces/runtime-event-pump.js +0 -716
@@ -1,93 +0,0 @@
1
- import type { ZodType, infer as ZodInfer } from 'zod';
2
- import type { ActOptions, ActResult, StagehandAction, ExtractOptions, StagehandExtractResult, StagehandObserveResult, ObserveOptions, StagehandAgentConfig, StagehandAgentExecuteOptions, StagehandAgentResult, StagehandMetrics, StagehandHistoryEntry } from '../../contracts/stagehand.js';
3
- import type { RpcSender } from '../../internal/transport.js';
4
- /** Page resolver - converts driver-specific page object to pageId */
5
- export type PageResolver<TPage> = (page?: TPage) => string | undefined;
6
- /** Options with page parameter (replaces pageId for SDK usage) */
7
- export type WithPage<TPage, TOptions = {}> = Omit<TOptions, 'pageId'> & {
8
- page?: TPage;
9
- };
10
- export type ActOptionsWithPage<TPage> = WithPage<TPage, ActOptions>;
11
- export type ExtractOptionsWithPage<TPage> = WithPage<TPage, ExtractOptions>;
12
- export type ObserveOptionsWithPage<TPage> = WithPage<TPage, ObserveOptions>;
13
- export type AgentExecuteOptionsWithPage<TPage> = WithPage<TPage, StagehandAgentExecuteOptions> & {
14
- instruction: string;
15
- };
16
- export type AgentExecuteCallOptionsWithPage<TPage> = WithPage<TPage, Omit<StagehandAgentExecuteOptions, 'instruction'>>;
17
- /**
18
- * Core Stagehand AI methods implementation.
19
- * Generic TPage allows each driver to specify its own page type.
20
- */
21
- export declare class StagehandCore<TPage = unknown> {
22
- private sendRpc;
23
- private getContextId;
24
- private getActivePageId;
25
- private resolvePage;
26
- constructor(sendRpc: RpcSender, getContextId: () => string | undefined, getActivePageId: () => string | undefined, resolvePage: PageResolver<TPage>);
27
- /** Resolve page object to pageId, falling back to active page */
28
- private resolvePageId;
29
- /** Strip page property from options before sending over RPC */
30
- private stripPage;
31
- /** Get RPC routing IDs */
32
- private rpcIds;
33
- /**
34
- * Execute an AI action on a page.
35
- * @example await session.act("click the login button", { page });
36
- */
37
- act(instruction: string, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
38
- act(action: StagehandAction, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
39
- /**
40
- * Extract data from a page using AI.
41
- * Supports Zod schemas for type-safe extraction.
42
- *
43
- * @example
44
- * // Get page text
45
- * const { pageText } = await session.extract({ page });
46
- *
47
- * // Extract with schema
48
- * const schema = z.object({ title: z.string(), price: z.number() });
49
- * const data = await session.extract("get product info", schema, { page });
50
- * // data is typed as { title: string; price: number }
51
- */
52
- extract(options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<{
53
- pageText: string;
54
- }>>;
55
- extract<T extends ZodType>(instruction: string, schema: T, options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<ZodInfer<T>>>;
56
- /**
57
- * Observe available actions on a page using AI.
58
- * @example const actions = await session.observe("find clickable elements", { page });
59
- */
60
- observe(options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
61
- observe(instruction: string, options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
62
- /**
63
- * Create a Stagehand agent for autonomous task execution.
64
- * @example
65
- * const agent = session.agent({ model: 'gpt-4o' });
66
- * await agent.execute("Find and click the login button", { page });
67
- */
68
- agent(config?: StagehandAgentConfig): StagehandAgent<TPage>;
69
- /**
70
- * Get Stagehand usage metrics.
71
- */
72
- getMetrics(): Promise<StagehandMetrics>;
73
- /**
74
- * Get Stagehand operation history.
75
- */
76
- getHistory(): Promise<StagehandHistoryEntry[]>;
77
- }
78
- /**
79
- * Stagehand agent for autonomous task execution.
80
- */
81
- export declare class StagehandAgent<TPage = unknown> {
82
- private sendRpc;
83
- private getContextId;
84
- private resolvePageId;
85
- private config?;
86
- constructor(sendRpc: RpcSender, getContextId: () => string | undefined, resolvePageId: (page?: TPage) => string | undefined, config?: StagehandAgentConfig | undefined);
87
- /**
88
- * Execute an autonomous task.
89
- * @example await agent.execute("Find and book a flight to Tokyo", { page });
90
- */
91
- execute(instruction: string, options?: AgentExecuteCallOptionsWithPage<TPage>): Promise<StagehandAgentResult>;
92
- execute(options: AgentExecuteOptionsWithPage<TPage>): Promise<StagehandAgentResult>;
93
- }
@@ -1,144 +0,0 @@
1
- // ============================================================================
2
- // StagehandCore - Centralized Stagehand AI methods
3
- // ============================================================================
4
- //
5
- // This module provides the core implementation of Stagehand AI methods
6
- // (act, extract, observe, agent) that can be used by:
7
- //
8
- // 1. Stagehand browser runtime clients - expose methods directly
9
- // 2. StagehandNamespace - wraps the same RPC surface for other runtime clients
10
- //
11
- // The API mirrors the real Stagehand SDK where AI methods take { page } option.
12
- //
13
- // ============================================================================
14
- import { toJsonSchema } from '../../utils/schema.js';
15
- // ============================================================================
16
- // StagehandCore
17
- // ============================================================================
18
- /**
19
- * Core Stagehand AI methods implementation.
20
- * Generic TPage allows each driver to specify its own page type.
21
- */
22
- export class StagehandCore {
23
- sendRpc;
24
- getContextId;
25
- getActivePageId;
26
- resolvePage;
27
- constructor(sendRpc, getContextId, getActivePageId, resolvePage) {
28
- this.sendRpc = sendRpc;
29
- this.getContextId = getContextId;
30
- this.getActivePageId = getActivePageId;
31
- this.resolvePage = resolvePage;
32
- }
33
- /** Resolve page object to pageId, falling back to active page */
34
- resolvePageId(page) {
35
- if (page) {
36
- const id = this.resolvePage(page);
37
- if (id)
38
- return id;
39
- }
40
- return this.getActivePageId();
41
- }
42
- /** Strip page property from options before sending over RPC */
43
- stripPage(options) {
44
- if (!options)
45
- return undefined;
46
- const { page, ...rest } = options;
47
- return Object.keys(rest).length > 0 ? rest : undefined;
48
- }
49
- /** Get RPC routing IDs */
50
- rpcIds(page) {
51
- return {
52
- contextId: this.getContextId(),
53
- pageId: this.resolvePageId(page),
54
- };
55
- }
56
- act(instructionOrAction, options) {
57
- return this.sendRpc('stagehand', 'act', [instructionOrAction, this.stripPage(options)], this.rpcIds(options?.page));
58
- }
59
- extract(instructionOrOptions, schema, options) {
60
- // No args or options only - extract page text
61
- if (instructionOrOptions === undefined || typeof instructionOrOptions === 'object') {
62
- const opts = instructionOrOptions;
63
- return this.sendRpc('stagehand', 'extract', [null, null, this.stripPage(opts)], this.rpcIds(opts?.page));
64
- }
65
- // Instruction + schema + options
66
- const jsonSchema = schema ? toJsonSchema(schema) : null;
67
- return this.sendRpc('stagehand', 'extract', [instructionOrOptions, jsonSchema, this.stripPage(options)], this.rpcIds(options?.page));
68
- }
69
- observe(instructionOrOptions, options) {
70
- // Options only
71
- if (instructionOrOptions === undefined || typeof instructionOrOptions === 'object') {
72
- const opts = instructionOrOptions;
73
- return this.sendRpc('stagehand', 'observe', [null, this.stripPage(opts)], this.rpcIds(opts?.page));
74
- }
75
- // Instruction + options
76
- return this.sendRpc('stagehand', 'observe', [instructionOrOptions, this.stripPage(options)], this.rpcIds(options?.page));
77
- }
78
- // ==========================================================================
79
- // agent
80
- // ==========================================================================
81
- /**
82
- * Create a Stagehand agent for autonomous task execution.
83
- * @example
84
- * const agent = session.agent({ model: 'gpt-4o' });
85
- * await agent.execute("Find and click the login button", { page });
86
- */
87
- agent(config) {
88
- return new StagehandAgent(this.sendRpc, () => this.getContextId(), (page) => this.resolvePageId(page), config);
89
- }
90
- // ==========================================================================
91
- // Metrics & History
92
- // ==========================================================================
93
- /**
94
- * Get Stagehand usage metrics.
95
- */
96
- getMetrics() {
97
- return this.sendRpc('stagehand', 'getMetrics', []);
98
- }
99
- /**
100
- * Get Stagehand operation history.
101
- */
102
- getHistory() {
103
- return this.sendRpc('stagehand', 'getHistory', []);
104
- }
105
- }
106
- // ============================================================================
107
- // StagehandAgent
108
- // ============================================================================
109
- /**
110
- * Stagehand agent for autonomous task execution.
111
- */
112
- export class StagehandAgent {
113
- sendRpc;
114
- getContextId;
115
- resolvePageId;
116
- config;
117
- constructor(sendRpc, getContextId, resolvePageId, config) {
118
- this.sendRpc = sendRpc;
119
- this.getContextId = getContextId;
120
- this.resolvePageId = resolvePageId;
121
- this.config = config;
122
- }
123
- execute(instructionOrOptions, options) {
124
- const isString = typeof instructionOrOptions === 'string';
125
- const page = isString ? options?.page : instructionOrOptions.page;
126
- // Build clean options without page
127
- let cleanOptions;
128
- if (isString) {
129
- const { page: _, ...rest } = options ?? {};
130
- cleanOptions = {
131
- instruction: instructionOrOptions,
132
- ...rest,
133
- };
134
- }
135
- else {
136
- const { page: _, ...rest } = instructionOrOptions;
137
- cleanOptions = rest;
138
- }
139
- return this.sendRpc('stagehand', 'agent.execute', [this.config, cleanOptions], {
140
- contextId: this.getContextId(),
141
- pageId: this.resolvePageId(page),
142
- });
143
- }
144
- }
@@ -1,3 +0,0 @@
1
- export { StagehandCore, StagehandAgent } from './core.js';
2
- export { StagehandNamespace } from './namespace.js';
3
- export type { ActOptionsWithPage, ExtractOptionsWithPage, ObserveOptionsWithPage, AgentExecuteOptionsWithPage, PageResolver, } from './core.js';
@@ -1,24 +0,0 @@
1
- // ============================================================================
2
- // Stagehand AI Agent - AI-powered browser automation
3
- // ============================================================================
4
- //
5
- // This module provides the Stagehand AI integration for bctrl.
6
- //
7
- // - StagehandCore: Centralized implementation of act, extract, observe, agent
8
- // - StagehandNamespace: Wraps core for .stagehand namespace on other drivers
9
- // - StagehandAgent: Agent wrapper for autonomous task execution
10
- //
11
- // Usage:
12
- // // For Playwright/Puppeteer/Selenium - via namespace
13
- // const session = await bctrl.browser('my-scraper').connect.puppeteer();
14
- // await session.stagehand.act("click button", { page });
15
- //
16
- // // For Stagehand driver - directly on session (matches real Stagehand SDK)
17
- // const session = await bctrl.browser('my-scraper').connect.stagehand();
18
- // await session.act("click button", { page });
19
- //
20
- // ============================================================================
21
- // Core implementation
22
- export { StagehandCore, StagehandAgent } from './core.js';
23
- // Namespace wrapper for other drivers
24
- export { StagehandNamespace } from './namespace.js';
@@ -1,51 +0,0 @@
1
- import type { ZodType, infer as ZodInfer } from 'zod';
2
- import { StagehandAgent, type ActOptionsWithPage, type ExtractOptionsWithPage, type ObserveOptionsWithPage, type PageResolver } from './core.js';
3
- import type { ActResult, StagehandAction, StagehandAgentConfig, StagehandExtractResult, StagehandMetrics, StagehandHistoryEntry, StagehandObserveResult } from '../../contracts/stagehand.js';
4
- import type { RpcSender } from '../../internal/transport.js';
5
- /**
6
- * Stagehand AI namespace - wraps StagehandCore for driver sessions.
7
- * Generic TPage allows each driver to specify its own page type.
8
- */
9
- export declare class StagehandNamespace<TPage = unknown> {
10
- private core;
11
- constructor(sendRpc: RpcSender, getContextId: () => string | undefined, getActivePageId: () => string | undefined, resolvePageFromDriver: PageResolver<TPage>);
12
- /**
13
- * Execute an AI action on a page.
14
- * @example await stagehand.act("click the login button", { page });
15
- */
16
- act(instruction: string, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
17
- act(action: StagehandAction, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
18
- /**
19
- * Extract data from a page using AI.
20
- * @example
21
- * const schema = z.object({ title: z.string(), price: z.number() });
22
- * const data = await stagehand.extract("get product info", schema, { page });
23
- */
24
- extract(options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<{
25
- pageText: string;
26
- }>>;
27
- extract<T extends ZodType>(instruction: string, schema: T, options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<ZodInfer<T>>>;
28
- /**
29
- * Observe available actions on a page using AI.
30
- * @example const actions = await stagehand.observe("find clickable elements", { page });
31
- */
32
- observe(options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
33
- observe(instruction: string, options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
34
- /**
35
- * Create a Stagehand agent for autonomous task execution.
36
- * @example
37
- * const agent = stagehand.agent({ model: 'gpt-4o' });
38
- * await agent.execute("Find and click the login button", { page });
39
- */
40
- agent(config?: StagehandAgentConfig): StagehandAgent<TPage>;
41
- /**
42
- * Get Stagehand usage metrics.
43
- */
44
- getMetrics(): Promise<StagehandMetrics>;
45
- /**
46
- * Get Stagehand operation history.
47
- */
48
- getHistory(): Promise<StagehandHistoryEntry[]>;
49
- }
50
- export { StagehandCore, StagehandAgent } from './core.js';
51
- export type { ActOptionsWithPage, ExtractOptionsWithPage, ObserveOptionsWithPage, AgentExecuteOptionsWithPage, PageResolver, } from './core.js';
@@ -1,65 +0,0 @@
1
- // ============================================================================
2
- // StagehandNamespace - Stagehand AI methods for non-stagehand drivers
3
- // ============================================================================
4
- //
5
- // This class provides the `.stagehand` namespace on driver sessions
6
- // for Playwright, Puppeteer, and Selenium drivers.
7
- //
8
- // Usage:
9
- // const session = await bctrl.browser('my-scraper').connect.puppeteer();
10
- // await session.stagehand.act("click button", { page });
11
- // const data = await session.stagehand.extract("get info", schema, { page });
12
- //
13
- // Note: For the stagehand driver, AI methods are exposed directly on the
14
- // session (session.act, session.extract, etc.) to match the real Stagehand SDK.
15
- //
16
- // ============================================================================
17
- import { StagehandCore, } from './core.js';
18
- /**
19
- * Stagehand AI namespace - wraps StagehandCore for driver sessions.
20
- * Generic TPage allows each driver to specify its own page type.
21
- */
22
- export class StagehandNamespace {
23
- core;
24
- constructor(sendRpc, getContextId, getActivePageId, resolvePageFromDriver) {
25
- this.core = new StagehandCore(sendRpc, getContextId, getActivePageId, resolvePageFromDriver);
26
- }
27
- act(instructionOrAction, options) {
28
- return this.core.act(instructionOrAction, options);
29
- }
30
- extract(instructionOrOptions, schema, options) {
31
- if (typeof instructionOrOptions === 'string') {
32
- return this.core.extract(instructionOrOptions, schema, options);
33
- }
34
- return this.core.extract(instructionOrOptions);
35
- }
36
- observe(instructionOrOptions, options) {
37
- if (typeof instructionOrOptions === 'string') {
38
- return this.core.observe(instructionOrOptions, options);
39
- }
40
- return this.core.observe(instructionOrOptions);
41
- }
42
- /**
43
- * Create a Stagehand agent for autonomous task execution.
44
- * @example
45
- * const agent = stagehand.agent({ model: 'gpt-4o' });
46
- * await agent.execute("Find and click the login button", { page });
47
- */
48
- agent(config) {
49
- return this.core.agent(config);
50
- }
51
- /**
52
- * Get Stagehand usage metrics.
53
- */
54
- getMetrics() {
55
- return this.core.getMetrics();
56
- }
57
- /**
58
- * Get Stagehand operation history.
59
- */
60
- getHistory() {
61
- return this.core.getHistory();
62
- }
63
- }
64
- // Re-export types and classes from core for convenience
65
- export { StagehandCore, StagehandAgent } from './core.js';
@@ -1,12 +0,0 @@
1
- import type { AiCredential, AiCredentialCreateRequest, AiCredentialTestResponse, AiCredentialUpdateRequest } from '../contracts/public-api.js';
2
- export declare class AiCredentialsClient {
3
- private readonly baseUrl;
4
- private readonly apiKey;
5
- constructor(baseUrl: string, apiKey: string);
6
- list(): Promise<AiCredential[]>;
7
- create(request: AiCredentialCreateRequest): Promise<AiCredential>;
8
- get(id: string): Promise<AiCredential>;
9
- update(id: string, request: AiCredentialUpdateRequest): Promise<AiCredential>;
10
- delete(id: string): Promise<void>;
11
- test(id: string): Promise<AiCredentialTestResponse>;
12
- }
@@ -1,70 +0,0 @@
1
- import { fetchWithTimeout, parseErrorDetails, parseJsonResponse } from '../utils/http.js';
2
- import { SDK_VERSION } from '../version.js';
3
- function buildHeaders(apiKey, withJsonBody = false) {
4
- const headers = {
5
- 'x-sdk-version': SDK_VERSION,
6
- Authorization: `Bearer ${apiKey}`,
7
- };
8
- if (withJsonBody) {
9
- headers['Content-Type'] = 'application/json';
10
- }
11
- return headers;
12
- }
13
- async function expectJson(response, context) {
14
- if (!response.ok) {
15
- const details = parseErrorDetails(await response.text());
16
- throw new Error(`${context}: ${details.message}`);
17
- }
18
- return parseJsonResponse(response, context);
19
- }
20
- export class AiCredentialsClient {
21
- baseUrl;
22
- apiKey;
23
- constructor(baseUrl, apiKey) {
24
- this.baseUrl = baseUrl;
25
- this.apiKey = apiKey;
26
- }
27
- async list() {
28
- const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials`, {
29
- headers: buildHeaders(this.apiKey),
30
- });
31
- const data = await expectJson(response, 'List AI credentials');
32
- return data.credentials;
33
- }
34
- async create(request) {
35
- const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials`, {
36
- method: 'POST',
37
- headers: buildHeaders(this.apiKey, true),
38
- body: JSON.stringify(request),
39
- });
40
- return expectJson(response, 'Create AI credential');
41
- }
42
- async get(id) {
43
- const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}`, {
44
- headers: buildHeaders(this.apiKey),
45
- });
46
- return expectJson(response, 'Get AI credential');
47
- }
48
- async update(id, request) {
49
- const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}`, {
50
- method: 'PATCH',
51
- headers: buildHeaders(this.apiKey, true),
52
- body: JSON.stringify(request),
53
- });
54
- return expectJson(response, 'Update AI credential');
55
- }
56
- async delete(id) {
57
- const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}`, {
58
- method: 'DELETE',
59
- headers: buildHeaders(this.apiKey),
60
- });
61
- await expectJson(response, 'Delete AI credential');
62
- }
63
- async test(id) {
64
- const response = await fetchWithTimeout(`${this.baseUrl}/ai-credentials/${encodeURIComponent(id)}/test`, {
65
- method: 'POST',
66
- headers: buildHeaders(this.apiKey),
67
- });
68
- return expectJson(response, 'Test AI credential');
69
- }
70
- }
@@ -1 +0,0 @@
1
- export { AiCredentialsClient } from './client.js';
@@ -1 +0,0 @@
1
- export { AiCredentialsClient } from './client.js';
@@ -1,7 +0,0 @@
1
- export interface RemoteListenerBinding {
2
- onFirstListener(event: string): void;
3
- onNoListeners(event: string): void;
4
- }
5
- export declare const REMOTE_LISTENER_BINDING_SYMBOL: unique symbol;
6
- export declare function getRemoteListenerBinding(target: unknown): RemoteListenerBinding | null;
7
- export declare function setRemoteListenerBinding(target: unknown, binding: RemoteListenerBinding | null): void;
@@ -1,23 +0,0 @@
1
- export const REMOTE_LISTENER_BINDING_SYMBOL = Symbol.for('bctrl.remoteListenerBinding');
2
- function isRemoteListenerBinding(value) {
3
- if (!value || typeof value !== 'object')
4
- return false;
5
- const onFirstListener = Reflect.get(value, 'onFirstListener');
6
- const onNoListeners = Reflect.get(value, 'onNoListeners');
7
- return typeof onFirstListener === 'function' && typeof onNoListeners === 'function';
8
- }
9
- export function getRemoteListenerBinding(target) {
10
- if (!target || typeof target !== 'object')
11
- return null;
12
- const candidate = Reflect.get(target, REMOTE_LISTENER_BINDING_SYMBOL);
13
- return isRemoteListenerBinding(candidate) ? candidate : null;
14
- }
15
- export function setRemoteListenerBinding(target, binding) {
16
- if (!target || typeof target !== 'object')
17
- return;
18
- if (!binding) {
19
- Reflect.deleteProperty(target, REMOTE_LISTENER_BINDING_SYMBOL);
20
- return;
21
- }
22
- Reflect.set(target, REMOTE_LISTENER_BINDING_SYMBOL, binding);
23
- }
@@ -1,109 +0,0 @@
1
- export type { DriverType, RpcMessage as _RpcMessage } from '../contracts/runtime.js';
2
- type InternalBctrlEnvironment = 'production' | 'development';
3
- /**
4
- * Profile selection options
5
- */
6
- export interface ProfileOptions {
7
- /** Use existing profile by ID */
8
- id?: string;
9
- /** Use existing profile by name */
10
- name?: string;
11
- /** Create new profile with this name */
12
- createName?: string;
13
- }
14
- /**
15
- * Connection options for connecting to bctrl
16
- */
17
- export interface ConnectOptions {
18
- /** Profile to use (by ID or name) */
19
- profile?: ProfileOptions;
20
- /** API key for authentication */
21
- apiKey: string;
22
- /**
23
- * Target environment.
24
- * Defaults to `production` (`https://api.bctrl.ai`).
25
- * Use `development` for a local gateway on `http://localhost:8787`.
26
- */
27
- environment?: InternalBctrlEnvironment;
28
- /**
29
- * Gateway origin or API base URL.
30
- * If you pass an origin, the SDK appends `/v1` automatically.
31
- */
32
- baseUrl?: string;
33
- /** Browser options */
34
- browserOptions?: {
35
- /** Run browser in headless mode */
36
- headless?: boolean;
37
- };
38
- /** Enable human-like mouse movement via CDP proxy (default: true) */
39
- humanize?: boolean;
40
- /** Mouse persona ID for humanization (0-124) */
41
- humanizePersonaId?: number;
42
- }
43
- /**
44
- * Locator step for remote locator chains
45
- */
46
- export interface LocatorStep {
47
- /** Locator method (e.g., 'locator', 'getByRole', 'getByText') */
48
- method: string;
49
- /** Arguments for the locator method */
50
- args: unknown[];
51
- }
52
- import type { DriverType, RpcTarget } from '../contracts/runtime.js';
53
- /**
54
- * SDK RPC message for sending commands to control-plane
55
- */
56
- export interface RpcMessageSdk {
57
- /** Driver type */
58
- driver: DriverType;
59
- /** Target object (browser, context, page, locator) */
60
- target: RpcTarget;
61
- /** Method to call on the target */
62
- method: string;
63
- /** Arguments for the method */
64
- args: unknown[];
65
- /** Page ID for page-specific operations */
66
- pageId?: string;
67
- /** Context ID for context-specific operations */
68
- contextId?: string;
69
- /** Locator chain for locator operations */
70
- locatorChain?: LocatorStep[];
71
- }
72
- /**
73
- * Session information returned from control-plane
74
- */
75
- export interface SessionInfo {
76
- /** Unique session ID */
77
- id: string;
78
- /** Default browser context ID (if applicable) */
79
- defaultContextId?: string;
80
- /** Default page ID (if applicable) */
81
- defaultPageId?: string;
82
- }
83
- /**
84
- * Select options
85
- */
86
- export interface SelectOption {
87
- value?: string;
88
- label?: string;
89
- index?: number;
90
- }
91
- /**
92
- * Keyboard press options
93
- */
94
- export interface PressOptions {
95
- delay?: number;
96
- }
97
- /**
98
- * Mouse click options
99
- */
100
- export interface MouseClickOptions {
101
- button?: 'left' | 'right' | 'middle';
102
- clickCount?: number;
103
- }
104
- /**
105
- * Evaluate options
106
- */
107
- export interface EvaluateOptions {
108
- timeout?: number;
109
- }
@@ -1,4 +0,0 @@
1
- // ============================================================================
2
- // Base Types - Common types for SDK redesign
3
- // ============================================================================
4
- export {};
@@ -1,15 +0,0 @@
1
- import type { BrowserExtensionDeleteResponse, BrowserExtensionImportRequest, ExtensionMetadata } from '../contracts/public-api.js';
2
- export interface BrowserExtensionUploadRequest {
3
- file: Buffer | Uint8Array | Blob;
4
- filename: string;
5
- }
6
- export declare class BrowserExtensionsClient {
7
- private readonly baseUrl;
8
- private readonly apiKey;
9
- constructor(baseUrl: string, apiKey: string);
10
- list(): Promise<ExtensionMetadata[]>;
11
- upload(request: BrowserExtensionUploadRequest): Promise<ExtensionMetadata>;
12
- importFromUrl(request: BrowserExtensionImportRequest): Promise<ExtensionMetadata>;
13
- get(id: string): Promise<ExtensionMetadata>;
14
- delete(id: string): Promise<BrowserExtensionDeleteResponse>;
15
- }