@bctrl/sdk 1.0.1 → 1.0.3

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 (277) hide show
  1. package/README.md +28 -29
  2. package/dist/bctrl.d.ts +22 -36
  3. package/dist/bctrl.js +40 -75
  4. package/dist/errors.d.ts +49 -43
  5. package/dist/errors.js +83 -120
  6. package/dist/files.d.ts +31 -0
  7. package/dist/files.js +97 -0
  8. package/dist/http.d.ts +18 -0
  9. package/dist/http.js +135 -0
  10. package/dist/index.d.ts +9 -12
  11. package/dist/index.js +7 -23
  12. package/dist/invocations.d.ts +86 -0
  13. package/dist/invocations.js +159 -0
  14. package/dist/pagination.d.ts +2 -0
  15. package/dist/pagination.js +13 -0
  16. package/dist/runs.d.ts +40 -0
  17. package/dist/runs.js +105 -0
  18. package/dist/runtimes.d.ts +69 -0
  19. package/dist/runtimes.js +202 -0
  20. package/dist/spaces.d.ts +40 -0
  21. package/dist/spaces.js +96 -0
  22. package/dist/types.d.ts +413 -0
  23. package/dist/types.js +1 -0
  24. package/dist/utils.d.ts +4 -0
  25. package/dist/utils.js +27 -0
  26. package/dist/version.js +2 -2
  27. package/package.json +4 -21
  28. package/dist/agents/browser-use/index.d.ts +0 -1
  29. package/dist/agents/browser-use/index.js +0 -9
  30. package/dist/agents/browser-use/namespace.d.ts +0 -39
  31. package/dist/agents/browser-use/namespace.js +0 -93
  32. package/dist/agents/index.d.ts +0 -2
  33. package/dist/agents/index.js +0 -17
  34. package/dist/agents/stagehand/core.d.ts +0 -93
  35. package/dist/agents/stagehand/core.js +0 -144
  36. package/dist/agents/stagehand/index.d.ts +0 -3
  37. package/dist/agents/stagehand/index.js +0 -24
  38. package/dist/agents/stagehand/namespace.d.ts +0 -51
  39. package/dist/agents/stagehand/namespace.js +0 -65
  40. package/dist/ai-credentials/client.d.ts +0 -12
  41. package/dist/ai-credentials/client.js +0 -70
  42. package/dist/ai-credentials/index.d.ts +0 -1
  43. package/dist/ai-credentials/index.js +0 -1
  44. package/dist/base/event-binding.d.ts +0 -7
  45. package/dist/base/event-binding.js +0 -23
  46. package/dist/base/types.d.ts +0 -109
  47. package/dist/base/types.js +0 -4
  48. package/dist/browser-extensions/client.d.ts +0 -15
  49. package/dist/browser-extensions/client.js +0 -72
  50. package/dist/browser-extensions/index.d.ts +0 -2
  51. package/dist/browser-extensions/index.js +0 -1
  52. package/dist/browser-profiles/client.d.ts +0 -11
  53. package/dist/browser-profiles/client.js +0 -63
  54. package/dist/browser-profiles/index.d.ts +0 -1
  55. package/dist/browser-profiles/index.js +0 -1
  56. package/dist/captcha/index.d.ts +0 -1
  57. package/dist/captcha/index.js +0 -1
  58. package/dist/captcha/namespace.d.ts +0 -34
  59. package/dist/captcha/namespace.js +0 -41
  60. package/dist/client/index.d.ts +0 -1
  61. package/dist/client/index.js +0 -1
  62. package/dist/client/rpc.d.ts +0 -83
  63. package/dist/client/rpc.js +0 -354
  64. package/dist/config.d.ts +0 -5
  65. package/dist/config.js +0 -28
  66. package/dist/constants/browser.d.ts +0 -2
  67. package/dist/constants/browser.js +0 -1
  68. package/dist/contracts/agent-tools.d.ts +0 -45
  69. package/dist/contracts/agent-tools.js +0 -31
  70. package/dist/contracts/automation.d.ts +0 -265
  71. package/dist/contracts/automation.js +0 -109
  72. package/dist/contracts/browser-management.d.ts +0 -179
  73. package/dist/contracts/browser-management.js +0 -95
  74. package/dist/contracts/browser-use.d.ts +0 -136
  75. package/dist/contracts/browser-use.js +0 -93
  76. package/dist/contracts/captcha.d.ts +0 -114
  77. package/dist/contracts/captcha.js +0 -40
  78. package/dist/contracts/desktop.d.ts +0 -223
  79. package/dist/contracts/desktop.js +0 -121
  80. package/dist/contracts/drivers/playwright.d.ts +0 -2008
  81. package/dist/contracts/drivers/playwright.js +0 -2033
  82. package/dist/contracts/drivers/puppeteer.d.ts +0 -1221
  83. package/dist/contracts/drivers/puppeteer.js +0 -941
  84. package/dist/contracts/drivers/selenium.d.ts +0 -156
  85. package/dist/contracts/drivers/selenium.js +0 -61
  86. package/dist/contracts/drivers/stagehand.d.ts +0 -155
  87. package/dist/contracts/drivers/stagehand.js +0 -7
  88. package/dist/contracts/extensions.d.ts +0 -13
  89. package/dist/contracts/extensions.js +0 -9
  90. package/dist/contracts/index.d.ts +0 -13
  91. package/dist/contracts/index.js +0 -13
  92. package/dist/contracts/public-api.d.ts +0 -360
  93. package/dist/contracts/public-api.js +0 -17
  94. package/dist/contracts/runtime.d.ts +0 -81
  95. package/dist/contracts/runtime.js +0 -16
  96. package/dist/contracts/stagehand.d.ts +0 -253
  97. package/dist/contracts/stagehand.js +0 -145
  98. package/dist/contracts/storage.d.ts +0 -51
  99. package/dist/contracts/storage.js +0 -56
  100. package/dist/contracts/vault.d.ts +0 -119
  101. package/dist/contracts/vault.js +0 -112
  102. package/dist/contracts/version.d.ts +0 -3
  103. package/dist/contracts/version.js +0 -16
  104. package/dist/desktop.d.ts +0 -2
  105. package/dist/desktop.js +0 -3
  106. package/dist/drivers/desktop/index.d.ts +0 -65
  107. package/dist/drivers/desktop/index.js +0 -68
  108. package/dist/drivers/desktop/session.d.ts +0 -313
  109. package/dist/drivers/desktop/session.js +0 -432
  110. package/dist/drivers/playwright/event-emitter.d.ts +0 -160
  111. package/dist/drivers/playwright/event-emitter.js +0 -297
  112. package/dist/drivers/playwright/generated/api-request-context.d.ts +0 -137
  113. package/dist/drivers/playwright/generated/api-request-context.js +0 -154
  114. package/dist/drivers/playwright/generated/api-response.d.ts +0 -119
  115. package/dist/drivers/playwright/generated/api-response.js +0 -123
  116. package/dist/drivers/playwright/generated/browser-context.d.ts +0 -284
  117. package/dist/drivers/playwright/generated/browser-context.js +0 -458
  118. package/dist/drivers/playwright/generated/browser.d.ts +0 -120
  119. package/dist/drivers/playwright/generated/browser.js +0 -151
  120. package/dist/drivers/playwright/generated/clock.d.ts +0 -80
  121. package/dist/drivers/playwright/generated/clock.js +0 -94
  122. package/dist/drivers/playwright/generated/console-message.d.ts +0 -94
  123. package/dist/drivers/playwright/generated/console-message.js +0 -89
  124. package/dist/drivers/playwright/generated/coverage.d.ts +0 -57
  125. package/dist/drivers/playwright/generated/coverage.js +0 -66
  126. package/dist/drivers/playwright/generated/dialog.d.ts +0 -79
  127. package/dist/drivers/playwright/generated/dialog.js +0 -80
  128. package/dist/drivers/playwright/generated/element-handle.d.ts +0 -399
  129. package/dist/drivers/playwright/generated/element-handle.js +0 -501
  130. package/dist/drivers/playwright/generated/frame-locator.d.ts +0 -34
  131. package/dist/drivers/playwright/generated/frame-locator.js +0 -63
  132. package/dist/drivers/playwright/generated/frame.d.ts +0 -557
  133. package/dist/drivers/playwright/generated/frame.js +0 -634
  134. package/dist/drivers/playwright/generated/js-handle.d.ts +0 -72
  135. package/dist/drivers/playwright/generated/js-handle.js +0 -92
  136. package/dist/drivers/playwright/generated/keyboard.d.ts +0 -103
  137. package/dist/drivers/playwright/generated/keyboard.js +0 -113
  138. package/dist/drivers/playwright/generated/locator.d.ts +0 -795
  139. package/dist/drivers/playwright/generated/locator.js +0 -974
  140. package/dist/drivers/playwright/generated/mouse.d.ts +0 -97
  141. package/dist/drivers/playwright/generated/mouse.js +0 -109
  142. package/dist/drivers/playwright/generated/page.d.ts +0 -762
  143. package/dist/drivers/playwright/generated/page.js +0 -988
  144. package/dist/drivers/playwright/generated/touchscreen.d.ts +0 -34
  145. package/dist/drivers/playwright/generated/touchscreen.js +0 -37
  146. package/dist/drivers/playwright/generated/tracing.d.ts +0 -78
  147. package/dist/drivers/playwright/generated/tracing.js +0 -80
  148. package/dist/drivers/playwright/generated/worker.d.ts +0 -53
  149. package/dist/drivers/playwright/generated/worker.js +0 -59
  150. package/dist/drivers/playwright/index.d.ts +0 -19
  151. package/dist/drivers/playwright/index.js +0 -20
  152. package/dist/drivers/playwright/remote-base.d.ts +0 -62
  153. package/dist/drivers/playwright/remote-base.js +0 -86
  154. package/dist/drivers/playwright/types.d.ts +0 -148
  155. package/dist/drivers/playwright/types.js +0 -8
  156. package/dist/drivers/puppeteer/errors.d.ts +0 -50
  157. package/dist/drivers/puppeteer/errors.js +0 -71
  158. package/dist/drivers/puppeteer/event-emitter.d.ts +0 -145
  159. package/dist/drivers/puppeteer/event-emitter.js +0 -259
  160. package/dist/drivers/puppeteer/generated/accessibility.d.ts +0 -77
  161. package/dist/drivers/puppeteer/generated/accessibility.js +0 -74
  162. package/dist/drivers/puppeteer/generated/browser-context.d.ts +0 -116
  163. package/dist/drivers/puppeteer/generated/browser-context.js +0 -168
  164. package/dist/drivers/puppeteer/generated/browser.d.ts +0 -169
  165. package/dist/drivers/puppeteer/generated/browser.js +0 -246
  166. package/dist/drivers/puppeteer/generated/console-message.d.ts +0 -54
  167. package/dist/drivers/puppeteer/generated/console-message.js +0 -69
  168. package/dist/drivers/puppeteer/generated/coverage.d.ts +0 -49
  169. package/dist/drivers/puppeteer/generated/coverage.js +0 -57
  170. package/dist/drivers/puppeteer/generated/dialog.d.ts +0 -46
  171. package/dist/drivers/puppeteer/generated/dialog.js +0 -60
  172. package/dist/drivers/puppeteer/generated/element-handle.d.ts +0 -261
  173. package/dist/drivers/puppeteer/generated/element-handle.js +0 -341
  174. package/dist/drivers/puppeteer/generated/file-chooser.d.ts +0 -34
  175. package/dist/drivers/puppeteer/generated/file-chooser.js +0 -43
  176. package/dist/drivers/puppeteer/generated/frame.d.ts +0 -221
  177. package/dist/drivers/puppeteer/generated/frame.js +0 -302
  178. package/dist/drivers/puppeteer/generated/http-request.d.ts +0 -195
  179. package/dist/drivers/puppeteer/generated/http-request.js +0 -243
  180. package/dist/drivers/puppeteer/generated/http-response.d.ts +0 -142
  181. package/dist/drivers/puppeteer/generated/http-response.js +0 -169
  182. package/dist/drivers/puppeteer/generated/js-handle.d.ts +0 -104
  183. package/dist/drivers/puppeteer/generated/js-handle.js +0 -125
  184. package/dist/drivers/puppeteer/generated/keyboard.d.ts +0 -79
  185. package/dist/drivers/puppeteer/generated/keyboard.js +0 -89
  186. package/dist/drivers/puppeteer/generated/locator.d.ts +0 -141
  187. package/dist/drivers/puppeteer/generated/locator.js +0 -164
  188. package/dist/drivers/puppeteer/generated/mouse.d.ts +0 -74
  189. package/dist/drivers/puppeteer/generated/mouse.js +0 -94
  190. package/dist/drivers/puppeteer/generated/page.d.ts +0 -604
  191. package/dist/drivers/puppeteer/generated/page.js +0 -776
  192. package/dist/drivers/puppeteer/generated/target.d.ts +0 -105
  193. package/dist/drivers/puppeteer/generated/target.js +0 -123
  194. package/dist/drivers/puppeteer/generated/touchscreen.d.ts +0 -87
  195. package/dist/drivers/puppeteer/generated/touchscreen.js +0 -103
  196. package/dist/drivers/puppeteer/generated/tracing.d.ts +0 -38
  197. package/dist/drivers/puppeteer/generated/tracing.js +0 -43
  198. package/dist/drivers/puppeteer/generated/web-worker.d.ts +0 -63
  199. package/dist/drivers/puppeteer/generated/web-worker.js +0 -73
  200. package/dist/drivers/puppeteer/index.d.ts +0 -21
  201. package/dist/drivers/puppeteer/index.js +0 -23
  202. package/dist/drivers/puppeteer/remote-base.d.ts +0 -57
  203. package/dist/drivers/puppeteer/remote-base.js +0 -79
  204. package/dist/drivers/puppeteer/types.d.ts +0 -178
  205. package/dist/drivers/puppeteer/types.js +0 -8
  206. package/dist/drivers/selenium/driver.d.ts +0 -28
  207. package/dist/drivers/selenium/driver.js +0 -169
  208. package/dist/drivers/selenium/element.d.ts +0 -34
  209. package/dist/drivers/selenium/element.js +0 -73
  210. package/dist/drivers/selenium/index.d.ts +0 -3
  211. package/dist/drivers/selenium/index.js +0 -5
  212. package/dist/drivers/selenium/types.d.ts +0 -2
  213. package/dist/drivers/selenium/types.js +0 -12
  214. package/dist/drivers/stagehand/generated/context.d.ts +0 -127
  215. package/dist/drivers/stagehand/generated/context.js +0 -153
  216. package/dist/drivers/stagehand/generated/locator.d.ts +0 -324
  217. package/dist/drivers/stagehand/generated/locator.js +0 -368
  218. package/dist/drivers/stagehand/generated/page.d.ts +0 -377
  219. package/dist/drivers/stagehand/generated/page.js +0 -439
  220. package/dist/drivers/stagehand/generated/response.d.ts +0 -197
  221. package/dist/drivers/stagehand/generated/response.js +0 -232
  222. package/dist/drivers/stagehand/index.d.ts +0 -5
  223. package/dist/drivers/stagehand/index.js +0 -8
  224. package/dist/drivers/stagehand/types.d.ts +0 -1
  225. package/dist/drivers/stagehand/types.js +0 -7
  226. package/dist/extensions/client.d.ts +0 -47
  227. package/dist/extensions/client.js +0 -154
  228. package/dist/extensions/index.d.ts +0 -1
  229. package/dist/extensions/index.js +0 -1
  230. package/dist/internal/dev-client.d.ts +0 -5
  231. package/dist/internal/dev-client.js +0 -9
  232. package/dist/internal/rpc-targets.d.ts +0 -17
  233. package/dist/internal/rpc-targets.js +0 -58
  234. package/dist/internal/serialization.d.ts +0 -32
  235. package/dist/internal/serialization.js +0 -42
  236. package/dist/internal/transport.d.ts +0 -24
  237. package/dist/internal/transport.js +0 -29
  238. package/dist/playwright.d.ts +0 -1
  239. package/dist/playwright.js +0 -2
  240. package/dist/puppeteer.d.ts +0 -1
  241. package/dist/puppeteer.js +0 -2
  242. package/dist/selenium.d.ts +0 -1
  243. package/dist/selenium.js +0 -2
  244. package/dist/stagehand.d.ts +0 -1
  245. package/dist/stagehand.js +0 -2
  246. package/dist/storage/client.d.ts +0 -151
  247. package/dist/storage/client.js +0 -329
  248. package/dist/storage/index.d.ts +0 -2
  249. package/dist/storage/index.js +0 -4
  250. package/dist/telemetry.d.ts +0 -18
  251. package/dist/telemetry.js +0 -93
  252. package/dist/updates/client.d.ts +0 -8
  253. package/dist/updates/client.js +0 -128
  254. package/dist/updates/index.d.ts +0 -1
  255. package/dist/updates/index.js +0 -1
  256. package/dist/utils/http.d.ts +0 -39
  257. package/dist/utils/http.js +0 -88
  258. package/dist/utils/index.d.ts +0 -4
  259. package/dist/utils/index.js +0 -4
  260. package/dist/utils/logger.d.ts +0 -27
  261. package/dist/utils/logger.js +0 -74
  262. package/dist/utils/schema.d.ts +0 -17
  263. package/dist/utils/schema.js +0 -31
  264. package/dist/utils/url.d.ts +0 -5
  265. package/dist/utils/url.js +0 -7
  266. package/dist/vault/client.d.ts +0 -43
  267. package/dist/vault/client.js +0 -123
  268. package/dist/vault/index.d.ts +0 -1
  269. package/dist/vault/index.js +0 -1
  270. package/dist/workspaces/browser-runtime.d.ts +0 -251
  271. package/dist/workspaces/browser-runtime.js +0 -1025
  272. package/dist/workspaces/client.d.ts +0 -48
  273. package/dist/workspaces/client.js +0 -222
  274. package/dist/workspaces/index.d.ts +0 -2
  275. package/dist/workspaces/index.js +0 -2
  276. package/dist/workspaces/runtime-event-pump.d.ts +0 -65
  277. 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
- }