stagehand 0.0.4 → 3.5.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 (148) hide show
  1. checksums.yaml +7 -0
  2. data/.ignore +2 -0
  3. data/CHANGELOG.md +185 -0
  4. data/README.md +394 -31
  5. data/SECURITY.md +23 -0
  6. data/lib/stagehand/client.rb +123 -4
  7. data/lib/stagehand/errors.rb +228 -0
  8. data/lib/stagehand/file_part.rb +58 -0
  9. data/lib/stagehand/internal/stream.rb +56 -0
  10. data/lib/stagehand/internal/transport/base_client.rb +575 -0
  11. data/lib/stagehand/internal/transport/pooled_net_requester.rb +210 -0
  12. data/lib/stagehand/internal/type/array_of.rb +168 -0
  13. data/lib/stagehand/internal/type/base_model.rb +531 -0
  14. data/lib/stagehand/internal/type/base_page.rb +55 -0
  15. data/lib/stagehand/internal/type/base_stream.rb +83 -0
  16. data/lib/stagehand/internal/type/boolean.rb +77 -0
  17. data/lib/stagehand/internal/type/converter.rb +327 -0
  18. data/lib/stagehand/internal/type/enum.rb +131 -0
  19. data/lib/stagehand/internal/type/file_input.rb +111 -0
  20. data/lib/stagehand/internal/type/hash_of.rb +188 -0
  21. data/lib/stagehand/internal/type/request_parameters.rb +42 -0
  22. data/lib/stagehand/internal/type/union.rb +237 -0
  23. data/lib/stagehand/internal/type/unknown.rb +81 -0
  24. data/lib/stagehand/internal/util.rb +920 -0
  25. data/lib/stagehand/internal.rb +20 -0
  26. data/lib/stagehand/local.rb +439 -0
  27. data/lib/stagehand/models/action.rb +50 -0
  28. data/lib/stagehand/models/model_config.rb +55 -0
  29. data/lib/stagehand/models/session_act_params.rb +112 -0
  30. data/lib/stagehand/models/session_act_response.rb +127 -0
  31. data/lib/stagehand/models/session_end_params.rb +33 -0
  32. data/lib/stagehand/models/session_end_response.rb +17 -0
  33. data/lib/stagehand/models/session_execute_params.rb +212 -0
  34. data/lib/stagehand/models/session_execute_response.rb +212 -0
  35. data/lib/stagehand/models/session_extract_params.rb +107 -0
  36. data/lib/stagehand/models/session_extract_response.rb +46 -0
  37. data/lib/stagehand/models/session_navigate_params.rb +107 -0
  38. data/lib/stagehand/models/session_navigate_response.rb +44 -0
  39. data/lib/stagehand/models/session_observe_params.rb +99 -0
  40. data/lib/stagehand/models/session_observe_response.rb +91 -0
  41. data/lib/stagehand/models/session_replay_params.rb +33 -0
  42. data/lib/stagehand/models/session_replay_response.rb +100 -0
  43. data/lib/stagehand/models/session_start_params.rb +762 -0
  44. data/lib/stagehand/models/session_start_response.rb +55 -0
  45. data/lib/stagehand/models/stream_event.rb +120 -0
  46. data/lib/stagehand/models.rb +63 -0
  47. data/lib/stagehand/request_options.rb +77 -0
  48. data/lib/stagehand/resources/sessions.rb +488 -0
  49. data/lib/stagehand/version.rb +3 -1
  50. data/lib/stagehand.rb +74 -29
  51. data/manifest.yaml +17 -0
  52. data/rbi/stagehand/client.rbi +89 -0
  53. data/rbi/stagehand/errors.rbi +205 -0
  54. data/rbi/stagehand/file_part.rbi +37 -0
  55. data/rbi/stagehand/internal/stream.rbi +20 -0
  56. data/rbi/stagehand/internal/transport/base_client.rbi +314 -0
  57. data/rbi/stagehand/internal/transport/pooled_net_requester.rbi +83 -0
  58. data/rbi/stagehand/internal/type/array_of.rbi +104 -0
  59. data/rbi/stagehand/internal/type/base_model.rbi +308 -0
  60. data/rbi/stagehand/internal/type/base_page.rbi +42 -0
  61. data/rbi/stagehand/internal/type/base_stream.rbi +75 -0
  62. data/rbi/stagehand/internal/type/boolean.rbi +58 -0
  63. data/rbi/stagehand/internal/type/converter.rbi +216 -0
  64. data/rbi/stagehand/internal/type/enum.rbi +82 -0
  65. data/rbi/stagehand/internal/type/file_input.rbi +59 -0
  66. data/rbi/stagehand/internal/type/hash_of.rbi +104 -0
  67. data/rbi/stagehand/internal/type/request_parameters.rbi +29 -0
  68. data/rbi/stagehand/internal/type/union.rbi +128 -0
  69. data/rbi/stagehand/internal/type/unknown.rbi +58 -0
  70. data/rbi/stagehand/internal/util.rbi +487 -0
  71. data/rbi/stagehand/internal.rbi +18 -0
  72. data/rbi/stagehand/models/action.rbi +77 -0
  73. data/rbi/stagehand/models/model_config.rbi +94 -0
  74. data/rbi/stagehand/models/session_act_params.rbi +204 -0
  75. data/rbi/stagehand/models/session_act_response.rbi +250 -0
  76. data/rbi/stagehand/models/session_end_params.rbi +87 -0
  77. data/rbi/stagehand/models/session_end_response.rbi +30 -0
  78. data/rbi/stagehand/models/session_execute_params.rbi +440 -0
  79. data/rbi/stagehand/models/session_execute_response.rbi +414 -0
  80. data/rbi/stagehand/models/session_extract_params.rbi +209 -0
  81. data/rbi/stagehand/models/session_extract_response.rbi +91 -0
  82. data/rbi/stagehand/models/session_navigate_params.rbi +240 -0
  83. data/rbi/stagehand/models/session_navigate_response.rbi +91 -0
  84. data/rbi/stagehand/models/session_observe_params.rbi +198 -0
  85. data/rbi/stagehand/models/session_observe_response.rbi +184 -0
  86. data/rbi/stagehand/models/session_replay_params.rbi +89 -0
  87. data/rbi/stagehand/models/session_replay_response.rbi +286 -0
  88. data/rbi/stagehand/models/session_start_params.rbi +1703 -0
  89. data/rbi/stagehand/models/session_start_response.rbi +102 -0
  90. data/rbi/stagehand/models/stream_event.rbi +237 -0
  91. data/rbi/stagehand/models.rbi +25 -0
  92. data/rbi/stagehand/request_options.rbi +59 -0
  93. data/rbi/stagehand/resources/sessions.rbi +421 -0
  94. data/rbi/stagehand/version.rbi +5 -0
  95. data/sig/stagehand/client.rbs +41 -0
  96. data/sig/stagehand/errors.rbs +117 -0
  97. data/sig/stagehand/file_part.rbs +21 -0
  98. data/sig/stagehand/internal/stream.rbs +9 -0
  99. data/sig/stagehand/internal/transport/base_client.rbs +133 -0
  100. data/sig/stagehand/internal/transport/pooled_net_requester.rbs +48 -0
  101. data/sig/stagehand/internal/type/array_of.rbs +48 -0
  102. data/sig/stagehand/internal/type/base_model.rbs +102 -0
  103. data/sig/stagehand/internal/type/base_page.rbs +24 -0
  104. data/sig/stagehand/internal/type/base_stream.rbs +38 -0
  105. data/sig/stagehand/internal/type/boolean.rbs +26 -0
  106. data/sig/stagehand/internal/type/converter.rbs +79 -0
  107. data/sig/stagehand/internal/type/enum.rbs +32 -0
  108. data/sig/stagehand/internal/type/file_input.rbs +25 -0
  109. data/sig/stagehand/internal/type/hash_of.rbs +48 -0
  110. data/sig/stagehand/internal/type/request_parameters.rbs +19 -0
  111. data/sig/stagehand/internal/type/union.rbs +52 -0
  112. data/sig/stagehand/internal/type/unknown.rbs +26 -0
  113. data/sig/stagehand/internal/util.rbs +185 -0
  114. data/sig/stagehand/internal.rbs +9 -0
  115. data/sig/stagehand/models/action.rbs +46 -0
  116. data/sig/stagehand/models/model_config.rbs +56 -0
  117. data/sig/stagehand/models/session_act_params.rbs +111 -0
  118. data/sig/stagehand/models/session_act_response.rbs +121 -0
  119. data/sig/stagehand/models/session_end_params.rbs +41 -0
  120. data/sig/stagehand/models/session_end_response.rbs +13 -0
  121. data/sig/stagehand/models/session_execute_params.rbs +193 -0
  122. data/sig/stagehand/models/session_execute_response.rbs +215 -0
  123. data/sig/stagehand/models/session_extract_params.rbs +112 -0
  124. data/sig/stagehand/models/session_extract_response.rbs +36 -0
  125. data/sig/stagehand/models/session_navigate_params.rbs +114 -0
  126. data/sig/stagehand/models/session_navigate_response.rbs +36 -0
  127. data/sig/stagehand/models/session_observe_params.rbs +105 -0
  128. data/sig/stagehand/models/session_observe_response.rbs +89 -0
  129. data/sig/stagehand/models/session_replay_params.rbs +41 -0
  130. data/sig/stagehand/models/session_replay_response.rbs +137 -0
  131. data/sig/stagehand/models/session_start_params.rbs +866 -0
  132. data/sig/stagehand/models/session_start_response.rbs +44 -0
  133. data/sig/stagehand/models/stream_event.rbs +109 -0
  134. data/sig/stagehand/models.rbs +23 -0
  135. data/sig/stagehand/request_options.rbs +34 -0
  136. data/sig/stagehand/resources/sessions.rbs +121 -0
  137. data/sig/stagehand/version.rbs +3 -0
  138. metadata +170 -54
  139. data/.gitignore +0 -16
  140. data/Gemfile +0 -4
  141. data/Rakefile +0 -10
  142. data/lib/stagehand/client/oauth.rb +0 -32
  143. data/lib/stagehand/client/user.rb +0 -10
  144. data/lib/stagehand/rack/middleware.rb +0 -33
  145. data/lib/stagehand/railtie.rb +0 -19
  146. data/spec/spec_helper.rb +0 -7
  147. data/spec/stagehand_spec.rb +0 -44
  148. data/stagehand.gemspec +0 -25
@@ -0,0 +1,488 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Stagehand
4
+ module Resources
5
+ class Sessions
6
+ # See {Stagehand::Resources::Sessions#act_streaming} for streaming counterpart.
7
+ #
8
+ # Executes a browser action using natural language instructions or a predefined
9
+ # Action object.
10
+ #
11
+ # @overload act(id, input:, frame_id: nil, options: nil, x_stream_response: nil, request_options: {})
12
+ #
13
+ # @param id [String] Path param: Unique session identifier
14
+ #
15
+ # @param input [String, Stagehand::Models::Action] Body param: Natural language instruction or Action object
16
+ #
17
+ # @param frame_id [String, nil] Body param: Target frame ID for the action
18
+ #
19
+ # @param options [Stagehand::Models::SessionActParams::Options] Body param
20
+ #
21
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionActParams::XStreamResponse] Header param: Whether to stream the response via SSE
22
+ #
23
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
24
+ #
25
+ # @return [Stagehand::Models::SessionActResponse]
26
+ #
27
+ # @see Stagehand::Models::SessionActParams
28
+ def act(id, params)
29
+ parsed, options = Stagehand::SessionActParams.dump_request(params)
30
+ if parsed[:streamResponse]
31
+ message = "Please use `#act_streaming` for the streaming use case."
32
+ raise ArgumentError.new(message)
33
+ end
34
+ header_params = {x_stream_response: "x-stream-response"}
35
+ @client.request(
36
+ method: :post,
37
+ path: ["v1/sessions/%1$s/act", id],
38
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
39
+ body: parsed.except(*header_params.keys),
40
+ model: Stagehand::Models::SessionActResponse,
41
+ options: options
42
+ )
43
+ end
44
+
45
+ # See {Stagehand::Resources::Sessions#act} for non-streaming counterpart.
46
+ #
47
+ # Executes a browser action using natural language instructions or a predefined
48
+ # Action object.
49
+ #
50
+ # @overload act_streaming(id, input:, frame_id: nil, options: nil, x_stream_response: nil, request_options: {})
51
+ #
52
+ # @param id [String] Path param: Unique session identifier
53
+ #
54
+ # @param input [String, Stagehand::Models::Action] Body param: Natural language instruction or Action object
55
+ #
56
+ # @param frame_id [String, nil] Body param: Target frame ID for the action
57
+ #
58
+ # @param options [Stagehand::Models::SessionActParams::Options] Body param
59
+ #
60
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionActParams::XStreamResponse] Header param: Whether to stream the response via SSE
61
+ #
62
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
63
+ #
64
+ # @return [Stagehand::Internal::Stream<Stagehand::Models::StreamEvent>]
65
+ #
66
+ # @see Stagehand::Models::SessionActParams
67
+ def act_streaming(id, params)
68
+ parsed, options = Stagehand::SessionActParams.dump_request(params)
69
+ unless parsed.fetch(:streamResponse, true)
70
+ message = "Please use `#act` for the non-streaming use case."
71
+ raise ArgumentError.new(message)
72
+ end
73
+ parsed.store(:streamResponse, true)
74
+ header_params = {x_stream_response: "x-stream-response"}
75
+ @client.request(
76
+ method: :post,
77
+ path: ["v1/sessions/%1$s/act", id],
78
+ headers: {
79
+ "accept" => "text/event-stream",
80
+ **parsed.slice(*header_params.keys)
81
+ }.transform_keys(header_params),
82
+ body: parsed.except(*header_params.keys),
83
+ stream: Stagehand::Internal::Stream,
84
+ model: Stagehand::StreamEvent,
85
+ options: options
86
+ )
87
+ end
88
+
89
+ # Terminates the browser session and releases all associated resources.
90
+ #
91
+ # @overload end_(id, x_stream_response: nil, request_options: {})
92
+ #
93
+ # @param id [String] Unique session identifier
94
+ #
95
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionEndParams::XStreamResponse] Whether to stream the response via SSE
96
+ #
97
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
98
+ #
99
+ # @return [Stagehand::Models::SessionEndResponse]
100
+ #
101
+ # @see Stagehand::Models::SessionEndParams
102
+ def end_(id, params = {})
103
+ parsed, options = Stagehand::SessionEndParams.dump_request(params)
104
+ @client.request(
105
+ method: :post,
106
+ path: ["v1/sessions/%1$s/end", id],
107
+ headers: parsed.transform_keys(x_stream_response: "x-stream-response"),
108
+ model: Stagehand::Models::SessionEndResponse,
109
+ options: options
110
+ )
111
+ end
112
+
113
+ # See {Stagehand::Resources::Sessions#execute_streaming} for streaming
114
+ # counterpart.
115
+ #
116
+ # Some parameter documentations has been truncated, see
117
+ # {Stagehand::Models::SessionExecuteParams} for more details.
118
+ #
119
+ # Runs an autonomous AI agent that can perform complex multi-step browser tasks.
120
+ #
121
+ # @overload execute(id, agent_config:, execute_options:, frame_id: nil, should_cache: nil, x_stream_response: nil, request_options: {})
122
+ #
123
+ # @param id [String] Path param: Unique session identifier
124
+ #
125
+ # @param agent_config [Stagehand::Models::SessionExecuteParams::AgentConfig] Body param
126
+ #
127
+ # @param execute_options [Stagehand::Models::SessionExecuteParams::ExecuteOptions] Body param
128
+ #
129
+ # @param frame_id [String, nil] Body param: Target frame ID for the agent
130
+ #
131
+ # @param should_cache [Boolean] Body param: If true, the server captures a cache entry and returns it to the cli
132
+ #
133
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionExecuteParams::XStreamResponse] Header param: Whether to stream the response via SSE
134
+ #
135
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
136
+ #
137
+ # @return [Stagehand::Models::SessionExecuteResponse]
138
+ #
139
+ # @see Stagehand::Models::SessionExecuteParams
140
+ def execute(id, params)
141
+ parsed, options = Stagehand::SessionExecuteParams.dump_request(params)
142
+ if parsed[:streamResponse]
143
+ message = "Please use `#execute_streaming` for the streaming use case."
144
+ raise ArgumentError.new(message)
145
+ end
146
+ header_params = {x_stream_response: "x-stream-response"}
147
+ @client.request(
148
+ method: :post,
149
+ path: ["v1/sessions/%1$s/agentExecute", id],
150
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
151
+ body: parsed.except(*header_params.keys),
152
+ model: Stagehand::Models::SessionExecuteResponse,
153
+ options: options
154
+ )
155
+ end
156
+
157
+ # See {Stagehand::Resources::Sessions#execute} for non-streaming counterpart.
158
+ #
159
+ # Some parameter documentations has been truncated, see
160
+ # {Stagehand::Models::SessionExecuteParams} for more details.
161
+ #
162
+ # Runs an autonomous AI agent that can perform complex multi-step browser tasks.
163
+ #
164
+ # @overload execute_streaming(id, agent_config:, execute_options:, frame_id: nil, should_cache: nil, x_stream_response: nil, request_options: {})
165
+ #
166
+ # @param id [String] Path param: Unique session identifier
167
+ #
168
+ # @param agent_config [Stagehand::Models::SessionExecuteParams::AgentConfig] Body param
169
+ #
170
+ # @param execute_options [Stagehand::Models::SessionExecuteParams::ExecuteOptions] Body param
171
+ #
172
+ # @param frame_id [String, nil] Body param: Target frame ID for the agent
173
+ #
174
+ # @param should_cache [Boolean] Body param: If true, the server captures a cache entry and returns it to the cli
175
+ #
176
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionExecuteParams::XStreamResponse] Header param: Whether to stream the response via SSE
177
+ #
178
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
179
+ #
180
+ # @return [Stagehand::Internal::Stream<Stagehand::Models::StreamEvent>]
181
+ #
182
+ # @see Stagehand::Models::SessionExecuteParams
183
+ def execute_streaming(id, params)
184
+ parsed, options = Stagehand::SessionExecuteParams.dump_request(params)
185
+ unless parsed.fetch(:streamResponse, true)
186
+ message = "Please use `#execute` for the non-streaming use case."
187
+ raise ArgumentError.new(message)
188
+ end
189
+ parsed.store(:streamResponse, true)
190
+ header_params = {x_stream_response: "x-stream-response"}
191
+ @client.request(
192
+ method: :post,
193
+ path: ["v1/sessions/%1$s/agentExecute", id],
194
+ headers: {
195
+ "accept" => "text/event-stream",
196
+ **parsed.slice(*header_params.keys)
197
+ }.transform_keys(header_params),
198
+ body: parsed.except(*header_params.keys),
199
+ stream: Stagehand::Internal::Stream,
200
+ model: Stagehand::StreamEvent,
201
+ options: options
202
+ )
203
+ end
204
+
205
+ # See {Stagehand::Resources::Sessions#extract_streaming} for streaming
206
+ # counterpart.
207
+ #
208
+ # Extracts structured data from the current page using AI-powered analysis.
209
+ #
210
+ # @overload extract(id, frame_id: nil, instruction: nil, options: nil, schema: nil, x_stream_response: nil, request_options: {})
211
+ #
212
+ # @param id [String] Path param: Unique session identifier
213
+ #
214
+ # @param frame_id [String, nil] Body param: Target frame ID for the extraction
215
+ #
216
+ # @param instruction [String] Body param: Natural language instruction for what to extract
217
+ #
218
+ # @param options [Stagehand::Models::SessionExtractParams::Options] Body param
219
+ #
220
+ # @param schema [Hash{Symbol=>Object}] Body param: JSON Schema defining the structure of data to extract
221
+ #
222
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionExtractParams::XStreamResponse] Header param: Whether to stream the response via SSE
223
+ #
224
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
225
+ #
226
+ # @return [Stagehand::Models::SessionExtractResponse]
227
+ #
228
+ # @see Stagehand::Models::SessionExtractParams
229
+ def extract(id, params = {})
230
+ parsed, options = Stagehand::SessionExtractParams.dump_request(params)
231
+ if parsed[:streamResponse]
232
+ message = "Please use `#extract_streaming` for the streaming use case."
233
+ raise ArgumentError.new(message)
234
+ end
235
+ header_params = {x_stream_response: "x-stream-response"}
236
+ @client.request(
237
+ method: :post,
238
+ path: ["v1/sessions/%1$s/extract", id],
239
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
240
+ body: parsed.except(*header_params.keys),
241
+ model: Stagehand::Models::SessionExtractResponse,
242
+ options: options
243
+ )
244
+ end
245
+
246
+ # See {Stagehand::Resources::Sessions#extract} for non-streaming counterpart.
247
+ #
248
+ # Extracts structured data from the current page using AI-powered analysis.
249
+ #
250
+ # @overload extract_streaming(id, frame_id: nil, instruction: nil, options: nil, schema: nil, x_stream_response: nil, request_options: {})
251
+ #
252
+ # @param id [String] Path param: Unique session identifier
253
+ #
254
+ # @param frame_id [String, nil] Body param: Target frame ID for the extraction
255
+ #
256
+ # @param instruction [String] Body param: Natural language instruction for what to extract
257
+ #
258
+ # @param options [Stagehand::Models::SessionExtractParams::Options] Body param
259
+ #
260
+ # @param schema [Hash{Symbol=>Object}] Body param: JSON Schema defining the structure of data to extract
261
+ #
262
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionExtractParams::XStreamResponse] Header param: Whether to stream the response via SSE
263
+ #
264
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
265
+ #
266
+ # @return [Stagehand::Internal::Stream<Stagehand::Models::StreamEvent>]
267
+ #
268
+ # @see Stagehand::Models::SessionExtractParams
269
+ def extract_streaming(id, params = {})
270
+ parsed, options = Stagehand::SessionExtractParams.dump_request(params)
271
+ unless parsed.fetch(:streamResponse, true)
272
+ message = "Please use `#extract` for the non-streaming use case."
273
+ raise ArgumentError.new(message)
274
+ end
275
+ parsed.store(:streamResponse, true)
276
+ header_params = {x_stream_response: "x-stream-response"}
277
+ @client.request(
278
+ method: :post,
279
+ path: ["v1/sessions/%1$s/extract", id],
280
+ headers: {
281
+ "accept" => "text/event-stream",
282
+ **parsed.slice(*header_params.keys)
283
+ }.transform_keys(header_params),
284
+ body: parsed.except(*header_params.keys),
285
+ stream: Stagehand::Internal::Stream,
286
+ model: Stagehand::StreamEvent,
287
+ options: options
288
+ )
289
+ end
290
+
291
+ # Navigates the browser to the specified URL.
292
+ #
293
+ # @overload navigate(id, url:, frame_id: nil, options: nil, stream_response: nil, x_stream_response: nil, request_options: {})
294
+ #
295
+ # @param id [String] Path param: Unique session identifier
296
+ #
297
+ # @param url [String] Body param: URL to navigate to
298
+ #
299
+ # @param frame_id [String, nil] Body param: Target frame ID for the navigation
300
+ #
301
+ # @param options [Stagehand::Models::SessionNavigateParams::Options] Body param
302
+ #
303
+ # @param stream_response [Boolean] Body param: Whether to stream the response via SSE
304
+ #
305
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionNavigateParams::XStreamResponse] Header param: Whether to stream the response via SSE
306
+ #
307
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
308
+ #
309
+ # @return [Stagehand::Models::SessionNavigateResponse]
310
+ #
311
+ # @see Stagehand::Models::SessionNavigateParams
312
+ def navigate(id, params)
313
+ parsed, options = Stagehand::SessionNavigateParams.dump_request(params)
314
+ header_params = {x_stream_response: "x-stream-response"}
315
+ @client.request(
316
+ method: :post,
317
+ path: ["v1/sessions/%1$s/navigate", id],
318
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
319
+ body: parsed.except(*header_params.keys),
320
+ model: Stagehand::Models::SessionNavigateResponse,
321
+ options: options
322
+ )
323
+ end
324
+
325
+ # See {Stagehand::Resources::Sessions#observe_streaming} for streaming
326
+ # counterpart.
327
+ #
328
+ # Identifies and returns available actions on the current page that match the
329
+ # given instruction.
330
+ #
331
+ # @overload observe(id, frame_id: nil, instruction: nil, options: nil, x_stream_response: nil, request_options: {})
332
+ #
333
+ # @param id [String] Path param: Unique session identifier
334
+ #
335
+ # @param frame_id [String, nil] Body param: Target frame ID for the observation
336
+ #
337
+ # @param instruction [String] Body param: Natural language instruction for what actions to find
338
+ #
339
+ # @param options [Stagehand::Models::SessionObserveParams::Options] Body param
340
+ #
341
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionObserveParams::XStreamResponse] Header param: Whether to stream the response via SSE
342
+ #
343
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
344
+ #
345
+ # @return [Stagehand::Models::SessionObserveResponse]
346
+ #
347
+ # @see Stagehand::Models::SessionObserveParams
348
+ def observe(id, params = {})
349
+ parsed, options = Stagehand::SessionObserveParams.dump_request(params)
350
+ if parsed[:streamResponse]
351
+ message = "Please use `#observe_streaming` for the streaming use case."
352
+ raise ArgumentError.new(message)
353
+ end
354
+ header_params = {x_stream_response: "x-stream-response"}
355
+ @client.request(
356
+ method: :post,
357
+ path: ["v1/sessions/%1$s/observe", id],
358
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
359
+ body: parsed.except(*header_params.keys),
360
+ model: Stagehand::Models::SessionObserveResponse,
361
+ options: options
362
+ )
363
+ end
364
+
365
+ # See {Stagehand::Resources::Sessions#observe} for non-streaming counterpart.
366
+ #
367
+ # Identifies and returns available actions on the current page that match the
368
+ # given instruction.
369
+ #
370
+ # @overload observe_streaming(id, frame_id: nil, instruction: nil, options: nil, x_stream_response: nil, request_options: {})
371
+ #
372
+ # @param id [String] Path param: Unique session identifier
373
+ #
374
+ # @param frame_id [String, nil] Body param: Target frame ID for the observation
375
+ #
376
+ # @param instruction [String] Body param: Natural language instruction for what actions to find
377
+ #
378
+ # @param options [Stagehand::Models::SessionObserveParams::Options] Body param
379
+ #
380
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionObserveParams::XStreamResponse] Header param: Whether to stream the response via SSE
381
+ #
382
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
383
+ #
384
+ # @return [Stagehand::Internal::Stream<Stagehand::Models::StreamEvent>]
385
+ #
386
+ # @see Stagehand::Models::SessionObserveParams
387
+ def observe_streaming(id, params = {})
388
+ parsed, options = Stagehand::SessionObserveParams.dump_request(params)
389
+ unless parsed.fetch(:streamResponse, true)
390
+ message = "Please use `#observe` for the non-streaming use case."
391
+ raise ArgumentError.new(message)
392
+ end
393
+ parsed.store(:streamResponse, true)
394
+ header_params = {x_stream_response: "x-stream-response"}
395
+ @client.request(
396
+ method: :post,
397
+ path: ["v1/sessions/%1$s/observe", id],
398
+ headers: {
399
+ "accept" => "text/event-stream",
400
+ **parsed.slice(*header_params.keys)
401
+ }.transform_keys(header_params),
402
+ body: parsed.except(*header_params.keys),
403
+ stream: Stagehand::Internal::Stream,
404
+ model: Stagehand::StreamEvent,
405
+ options: options
406
+ )
407
+ end
408
+
409
+ # Retrieves replay metrics for a session.
410
+ #
411
+ # @overload replay(id, x_stream_response: nil, request_options: {})
412
+ #
413
+ # @param id [String] Unique session identifier
414
+ #
415
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionReplayParams::XStreamResponse] Whether to stream the response via SSE
416
+ #
417
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
418
+ #
419
+ # @return [Stagehand::Models::SessionReplayResponse]
420
+ #
421
+ # @see Stagehand::Models::SessionReplayParams
422
+ def replay(id, params = {})
423
+ parsed, options = Stagehand::SessionReplayParams.dump_request(params)
424
+ @client.request(
425
+ method: :get,
426
+ path: ["v1/sessions/%1$s/replay", id],
427
+ headers: parsed.transform_keys(x_stream_response: "x-stream-response"),
428
+ model: Stagehand::Models::SessionReplayResponse,
429
+ options: options
430
+ )
431
+ end
432
+
433
+ # Creates a new browser session with the specified configuration. Returns a
434
+ # session ID used for all subsequent operations.
435
+ #
436
+ # @overload start(model_name:, act_timeout_ms: nil, browser: nil, browserbase_session_create_params: nil, browserbase_session_id: nil, dom_settle_timeout_ms: nil, experimental: nil, self_heal: nil, system_prompt: nil, verbose: nil, wait_for_captcha_solves: nil, x_stream_response: nil, request_options: {})
437
+ #
438
+ # @param model_name [String] Body param: Model name to use for AI operations
439
+ #
440
+ # @param act_timeout_ms [Float] Body param: Timeout in ms for act operations (deprecated, v2 only)
441
+ #
442
+ # @param browser [Stagehand::Models::SessionStartParams::Browser] Body param
443
+ #
444
+ # @param browserbase_session_create_params [Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams] Body param
445
+ #
446
+ # @param browserbase_session_id [String] Body param: Existing Browserbase session ID to resume
447
+ #
448
+ # @param dom_settle_timeout_ms [Float] Body param: Timeout in ms to wait for DOM to settle
449
+ #
450
+ # @param experimental [Boolean] Body param
451
+ #
452
+ # @param self_heal [Boolean] Body param: Enable self-healing for failed actions
453
+ #
454
+ # @param system_prompt [String] Body param: Custom system prompt for AI operations
455
+ #
456
+ # @param verbose [Float, Stagehand::Models::SessionStartParams::Verbose] Body param: Logging verbosity level (0=quiet, 1=normal, 2=debug)
457
+ #
458
+ # @param wait_for_captcha_solves [Boolean] Body param: Wait for captcha solves (deprecated, v2 only)
459
+ #
460
+ # @param x_stream_response [Symbol, Stagehand::Models::SessionStartParams::XStreamResponse] Header param: Whether to stream the response via SSE
461
+ #
462
+ # @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}, nil]
463
+ #
464
+ # @return [Stagehand::Models::SessionStartResponse]
465
+ #
466
+ # @see Stagehand::Models::SessionStartParams
467
+ def start(params)
468
+ parsed, options = Stagehand::SessionStartParams.dump_request(params)
469
+ header_params = {x_stream_response: "x-stream-response"}
470
+ @client.request(
471
+ method: :post,
472
+ path: "v1/sessions/start",
473
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
474
+ body: parsed.except(*header_params.keys),
475
+ model: Stagehand::Models::SessionStartResponse,
476
+ options: options
477
+ )
478
+ end
479
+
480
+ # @api private
481
+ #
482
+ # @param client [Stagehand::Client]
483
+ def initialize(client:)
484
+ @client = client
485
+ end
486
+ end
487
+ end
488
+ end
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Stagehand
2
- VERSION = "0.0.4"
4
+ VERSION = "3.5.2"
3
5
  end
data/lib/stagehand.rb CHANGED
@@ -1,33 +1,78 @@
1
- require 'httparty'
2
- require 'stagehand/client'
3
- require 'stagehand/rack/middleware'
4
- require 'stagehand/railtie' if defined? ::Rails::Railtie
5
- require 'stagehand/version'
6
- require 'yajl'
1
+ # frozen_string_literal: true
7
2
 
8
- module Stagehand
9
- class Config
10
- attr_accessor :client_id, :client_secret, :client_host, :resource_host
11
- end
3
+ # Standard libraries.
4
+ # rubocop:disable Lint/RedundantRequireStatement
5
+ require "English"
6
+ require "base64"
7
+ require "cgi"
8
+ require "date"
9
+ require "erb"
10
+ require "etc"
11
+ require "json"
12
+ require "net/http"
13
+ require "openssl"
14
+ require "pathname"
15
+ require "rbconfig"
16
+ require "securerandom"
17
+ require "set"
18
+ require "stringio"
19
+ require "time"
20
+ require "uri"
21
+ # rubocop:enable Lint/RedundantRequireStatement
12
22
 
13
- class << self
14
- def config
15
- @@config ||= Config.new
16
- end
23
+ # We already ship the preferred sorbet manifests in the package itself.
24
+ # `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
25
+ if Object.const_defined?(:Tapioca) &&
26
+ caller.chain([$PROGRAM_NAME]).chain(ARGV).any?(/tapioca/) &&
27
+ ARGV.none?(/dsl/)
28
+ return
29
+ end
17
30
 
18
- def configure
19
- yield self.config
20
- end
21
-
22
- # return Stagehand::Client
23
- def new(options={})
24
- Stagehand::Client.new(options)
25
- end
31
+ # Gems.
32
+ require "connection_pool"
26
33
 
27
- # Delegate to Stagehand::Client
28
- def method_missing(method, *args, &block)
29
- return super unless new.respond_to?(method)
30
- new.send(method, *args, &block)
31
- end
32
- end
33
- end
34
+ # Package files.
35
+ require_relative "stagehand/version"
36
+ require_relative "stagehand/internal/util"
37
+ require_relative "stagehand/internal/type/converter"
38
+ require_relative "stagehand/internal/type/unknown"
39
+ require_relative "stagehand/internal/type/boolean"
40
+ require_relative "stagehand/internal/type/file_input"
41
+ require_relative "stagehand/internal/type/enum"
42
+ require_relative "stagehand/internal/type/union"
43
+ require_relative "stagehand/internal/type/array_of"
44
+ require_relative "stagehand/internal/type/hash_of"
45
+ require_relative "stagehand/internal/type/base_model"
46
+ require_relative "stagehand/internal/type/base_page"
47
+ require_relative "stagehand/internal/type/base_stream"
48
+ require_relative "stagehand/internal/type/request_parameters"
49
+ require_relative "stagehand/internal"
50
+ require_relative "stagehand/request_options"
51
+ require_relative "stagehand/file_part"
52
+ require_relative "stagehand/errors"
53
+ require_relative "stagehand/internal/transport/base_client"
54
+ require_relative "stagehand/internal/transport/pooled_net_requester"
55
+ require_relative "stagehand/client"
56
+ require_relative "stagehand/internal/stream"
57
+ require_relative "stagehand/models/action"
58
+ require_relative "stagehand/models/model_config"
59
+ require_relative "stagehand/models/session_act_params"
60
+ require_relative "stagehand/models/session_act_response"
61
+ require_relative "stagehand/models/session_end_params"
62
+ require_relative "stagehand/models/session_end_response"
63
+ require_relative "stagehand/models/session_execute_params"
64
+ require_relative "stagehand/models/session_execute_response"
65
+ require_relative "stagehand/models/session_extract_params"
66
+ require_relative "stagehand/models/session_extract_response"
67
+ require_relative "stagehand/models/session_navigate_params"
68
+ require_relative "stagehand/models/session_navigate_response"
69
+ require_relative "stagehand/models/session_observe_params"
70
+ require_relative "stagehand/models/session_observe_response"
71
+ require_relative "stagehand/models/session_replay_params"
72
+ require_relative "stagehand/models/session_replay_response"
73
+ require_relative "stagehand/models/session_start_params"
74
+ require_relative "stagehand/models/session_start_response"
75
+ require_relative "stagehand/models/stream_event"
76
+ require_relative "stagehand/models"
77
+ require_relative "stagehand/resources/sessions"
78
+ require_relative "stagehand/local"
data/manifest.yaml ADDED
@@ -0,0 +1,17 @@
1
+ dependencies:
2
+ - English
3
+ - base64
4
+ - cgi
5
+ - date
6
+ - erb
7
+ - etc
8
+ - json
9
+ - net/http
10
+ - openssl
11
+ - pathname
12
+ - rbconfig
13
+ - securerandom
14
+ - set
15
+ - stringio
16
+ - time
17
+ - uri