@browserbasehq/convex-stagehand 0.0.1

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 (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +477 -0
  3. package/dist/client/index.d.ts +258 -0
  4. package/dist/client/index.d.ts.map +1 -0
  5. package/dist/client/index.js +216 -0
  6. package/dist/client/index.js.map +1 -0
  7. package/dist/component/_generated/api.d.ts +36 -0
  8. package/dist/component/_generated/api.d.ts.map +1 -0
  9. package/dist/component/_generated/api.js +31 -0
  10. package/dist/component/_generated/api.js.map +1 -0
  11. package/dist/component/_generated/component.d.ts +24 -0
  12. package/dist/component/_generated/component.d.ts.map +1 -0
  13. package/dist/component/_generated/component.js +11 -0
  14. package/dist/component/_generated/component.js.map +1 -0
  15. package/dist/component/_generated/dataModel.d.ts +15 -0
  16. package/dist/component/_generated/dataModel.d.ts.map +1 -0
  17. package/dist/component/_generated/dataModel.js +11 -0
  18. package/dist/component/_generated/dataModel.js.map +1 -0
  19. package/dist/component/_generated/server.d.ts +121 -0
  20. package/dist/component/_generated/server.d.ts.map +1 -0
  21. package/dist/component/_generated/server.js +78 -0
  22. package/dist/component/_generated/server.js.map +1 -0
  23. package/dist/component/api.d.ts +90 -0
  24. package/dist/component/api.d.ts.map +1 -0
  25. package/dist/component/api.js +112 -0
  26. package/dist/component/api.js.map +1 -0
  27. package/dist/component/convex.config.d.ts +3 -0
  28. package/dist/component/convex.config.d.ts.map +1 -0
  29. package/dist/component/convex.config.js +3 -0
  30. package/dist/component/convex.config.js.map +1 -0
  31. package/dist/component/lib.d.ts +62 -0
  32. package/dist/component/lib.d.ts.map +1 -0
  33. package/dist/component/lib.js +356 -0
  34. package/dist/component/lib.js.map +1 -0
  35. package/dist/component/schema.d.ts +23 -0
  36. package/dist/component/schema.d.ts.map +1 -0
  37. package/dist/component/schema.js +14 -0
  38. package/dist/component/schema.js.map +1 -0
  39. package/dist/test.d.ts +48 -0
  40. package/dist/test.d.ts.map +1 -0
  41. package/dist/test.js +25 -0
  42. package/dist/test.js.map +1 -0
  43. package/package.json +87 -0
  44. package/src/client/index.ts +348 -0
  45. package/src/component/README.md +90 -0
  46. package/src/component/_generated/api.ts +52 -0
  47. package/src/component/_generated/component.ts +26 -0
  48. package/src/component/_generated/dataModel.ts +17 -0
  49. package/src/component/_generated/server.ts +156 -0
  50. package/src/component/api.ts +243 -0
  51. package/src/component/convex.config.ts +3 -0
  52. package/src/component/lib.ts +416 -0
  53. package/src/component/schema.ts +23 -0
  54. package/src/component/tsconfig.json +25 -0
  55. package/src/test.ts +33 -0
@@ -0,0 +1,258 @@
1
+ /**
2
+ * Stagehand Client
3
+ *
4
+ * Type-safe wrapper for the Stagehand Convex component.
5
+ * Uses Zod schemas for extraction typing.
6
+ */
7
+ import type { z } from "zod";
8
+ import type { GenericActionCtx } from "convex/server";
9
+ export type { ComponentApi } from "../component/_generated/component.js";
10
+ import type { ComponentApi } from "../component/_generated/component.js";
11
+ type ActionCtx = GenericActionCtx<any>;
12
+ export interface StagehandConfig {
13
+ browserbaseApiKey: string;
14
+ browserbaseProjectId: string;
15
+ modelApiKey: string;
16
+ modelName?: string;
17
+ }
18
+ export interface SessionInfo {
19
+ sessionId: string;
20
+ browserbaseSessionId?: string;
21
+ cdpUrl?: string;
22
+ }
23
+ export interface StartSessionOptions {
24
+ timeout?: number;
25
+ waitUntil?: "load" | "domcontentloaded" | "networkidle";
26
+ domSettleTimeoutMs?: number;
27
+ selfHeal?: boolean;
28
+ systemPrompt?: string;
29
+ }
30
+ export interface ExtractOptions {
31
+ timeout?: number;
32
+ waitUntil?: "load" | "domcontentloaded" | "networkidle";
33
+ }
34
+ export interface ActOptions {
35
+ timeout?: number;
36
+ waitUntil?: "load" | "domcontentloaded" | "networkidle";
37
+ }
38
+ export interface ObserveOptions {
39
+ timeout?: number;
40
+ waitUntil?: "load" | "domcontentloaded" | "networkidle";
41
+ }
42
+ export interface AgentOptions {
43
+ cua?: boolean;
44
+ maxSteps?: number;
45
+ systemPrompt?: string;
46
+ timeout?: number;
47
+ waitUntil?: "load" | "domcontentloaded" | "networkidle";
48
+ }
49
+ export interface ObservedAction {
50
+ description: string;
51
+ selector: string;
52
+ method: string;
53
+ arguments?: string[];
54
+ }
55
+ export interface ActResult {
56
+ success: boolean;
57
+ message: string;
58
+ actionDescription: string;
59
+ }
60
+ export interface AgentAction {
61
+ type: string;
62
+ action?: string;
63
+ reasoning?: string;
64
+ timeMs?: number;
65
+ }
66
+ export interface AgentResult {
67
+ actions: AgentAction[];
68
+ completed: boolean;
69
+ message: string;
70
+ success: boolean;
71
+ }
72
+ /**
73
+ * Stagehand client for AI-powered browser automation.
74
+ *
75
+ * @example
76
+ * ```typescript
77
+ * import { Stagehand } from "convex-stagehand";
78
+ * import { components } from "./_generated/api";
79
+ *
80
+ * const stagehand = new Stagehand(components.stagehand, {
81
+ * browserbaseApiKey: process.env.BROWSERBASE_API_KEY!,
82
+ * browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID!,
83
+ * modelApiKey: process.env.MODEL_API_KEY!,
84
+ * });
85
+ *
86
+ * export const scrape = action({
87
+ * handler: async (ctx) => {
88
+ * return await stagehand.extract(ctx, {
89
+ * url: "https://example.com",
90
+ * instruction: "Extract all product names",
91
+ * schema: z.object({ products: z.array(z.string()) }),
92
+ * });
93
+ * },
94
+ * });
95
+ * ```
96
+ */
97
+ export declare class Stagehand {
98
+ private component;
99
+ private config;
100
+ constructor(component: ComponentApi, config: StagehandConfig);
101
+ /**
102
+ * Start a new browser session.
103
+ * Returns session info including cdpUrl for direct Playwright/Puppeteer connection.
104
+ *
105
+ * @param ctx - Convex action context
106
+ * @param args - Session parameters
107
+ * @returns Session info with sessionId, browserbaseSessionId, and cdpUrl
108
+ *
109
+ * @example
110
+ * ```typescript
111
+ * const session = await stagehand.startSession(ctx, {
112
+ * url: "https://example.com",
113
+ * });
114
+ * // Use session.sessionId with other operations
115
+ * // Or connect Playwright: puppeteer.connect({ browserWSEndpoint: session.cdpUrl })
116
+ * ```
117
+ */
118
+ startSession(ctx: ActionCtx, args: {
119
+ url: string;
120
+ browserbaseSessionId?: string;
121
+ options?: StartSessionOptions;
122
+ }): Promise<SessionInfo>;
123
+ /**
124
+ * End a browser session.
125
+ *
126
+ * @param ctx - Convex action context
127
+ * @param args - Session to end
128
+ * @returns Success status
129
+ *
130
+ * @example
131
+ * ```typescript
132
+ * await stagehand.endSession(ctx, { sessionId: session.sessionId });
133
+ * ```
134
+ */
135
+ endSession(ctx: ActionCtx, args: {
136
+ sessionId: string;
137
+ }): Promise<{
138
+ success: boolean;
139
+ }>;
140
+ /**
141
+ * Extract structured data from a web page using AI.
142
+ *
143
+ * @param ctx - Convex action context
144
+ * @param args - Extraction parameters
145
+ * @returns Extracted data matching the provided schema
146
+ *
147
+ * @example
148
+ * ```typescript
149
+ * // Without session (creates and destroys its own)
150
+ * const data = await stagehand.extract(ctx, {
151
+ * url: "https://news.ycombinator.com",
152
+ * instruction: "Extract the top 5 stories with title and score",
153
+ * schema: z.object({
154
+ * stories: z.array(z.object({
155
+ * title: z.string(),
156
+ * score: z.string(),
157
+ * }))
158
+ * }),
159
+ * });
160
+ *
161
+ * // With existing session (reuses session)
162
+ * const data = await stagehand.extract(ctx, {
163
+ * sessionId: session.sessionId,
164
+ * instruction: "Extract the top 5 stories",
165
+ * schema: z.object({ ... }),
166
+ * });
167
+ * ```
168
+ */
169
+ extract<T extends z.ZodType>(ctx: ActionCtx, args: {
170
+ sessionId?: string;
171
+ url?: string;
172
+ instruction: string;
173
+ schema: T;
174
+ options?: ExtractOptions;
175
+ }): Promise<z.infer<T>>;
176
+ /**
177
+ * Execute a browser action using natural language.
178
+ *
179
+ * @param ctx - Convex action context
180
+ * @param args - Action parameters
181
+ * @returns Result of the action
182
+ *
183
+ * @example
184
+ * ```typescript
185
+ * // Without session
186
+ * const result = await stagehand.act(ctx, {
187
+ * url: "https://example.com/login",
188
+ * action: "Click the login button",
189
+ * });
190
+ *
191
+ * // With existing session
192
+ * const result = await stagehand.act(ctx, {
193
+ * sessionId: session.sessionId,
194
+ * action: "Click the submit button",
195
+ * });
196
+ * ```
197
+ */
198
+ act(ctx: ActionCtx, args: {
199
+ sessionId?: string;
200
+ url?: string;
201
+ action: string;
202
+ options?: ActOptions;
203
+ }): Promise<ActResult>;
204
+ /**
205
+ * Find available actions on a web page.
206
+ *
207
+ * @param ctx - Convex action context
208
+ * @param args - Observe parameters
209
+ * @returns List of available actions
210
+ *
211
+ * @example
212
+ * ```typescript
213
+ * const actions = await stagehand.observe(ctx, {
214
+ * url: "https://example.com",
215
+ * instruction: "Find all navigation links",
216
+ * });
217
+ * ```
218
+ */
219
+ observe(ctx: ActionCtx, args: {
220
+ sessionId?: string;
221
+ url?: string;
222
+ instruction: string;
223
+ options?: ObserveOptions;
224
+ }): Promise<ObservedAction[]>;
225
+ /**
226
+ * Execute autonomous multi-step browser automation using an AI agent.
227
+ * The agent interprets the instruction and decides what actions to take.
228
+ *
229
+ * @param ctx - Convex action context
230
+ * @param args - Agent parameters
231
+ * @returns Agent execution result with actions taken
232
+ *
233
+ * @example
234
+ * ```typescript
235
+ * // Agent creates its own session
236
+ * const result = await stagehand.agent(ctx, {
237
+ * url: "https://google.com",
238
+ * instruction: "Search for 'convex database' and extract the top 3 results",
239
+ * options: { maxSteps: 10 },
240
+ * });
241
+ *
242
+ * // Agent with existing session
243
+ * const result = await stagehand.agent(ctx, {
244
+ * sessionId: session.sessionId,
245
+ * instruction: "Fill out the form and submit",
246
+ * options: { maxSteps: 5 },
247
+ * });
248
+ * ```
249
+ */
250
+ agent(ctx: ActionCtx, args: {
251
+ sessionId?: string;
252
+ url?: string;
253
+ instruction: string;
254
+ options?: AgentOptions;
255
+ }): Promise<AgentResult>;
256
+ }
257
+ export default Stagehand;
258
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,216 @@
1
+ /**
2
+ * Stagehand Client
3
+ *
4
+ * Type-safe wrapper for the Stagehand Convex component.
5
+ * Uses Zod schemas for extraction typing.
6
+ */
7
+ import { zodToJsonSchema } from "zod-to-json-schema";
8
+ /**
9
+ * Stagehand client for AI-powered browser automation.
10
+ *
11
+ * @example
12
+ * ```typescript
13
+ * import { Stagehand } from "convex-stagehand";
14
+ * import { components } from "./_generated/api";
15
+ *
16
+ * const stagehand = new Stagehand(components.stagehand, {
17
+ * browserbaseApiKey: process.env.BROWSERBASE_API_KEY!,
18
+ * browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID!,
19
+ * modelApiKey: process.env.MODEL_API_KEY!,
20
+ * });
21
+ *
22
+ * export const scrape = action({
23
+ * handler: async (ctx) => {
24
+ * return await stagehand.extract(ctx, {
25
+ * url: "https://example.com",
26
+ * instruction: "Extract all product names",
27
+ * schema: z.object({ products: z.array(z.string()) }),
28
+ * });
29
+ * },
30
+ * });
31
+ * ```
32
+ */
33
+ export class Stagehand {
34
+ component;
35
+ config;
36
+ constructor(component, config) {
37
+ this.component = component;
38
+ this.config = config;
39
+ }
40
+ /**
41
+ * Start a new browser session.
42
+ * Returns session info including cdpUrl for direct Playwright/Puppeteer connection.
43
+ *
44
+ * @param ctx - Convex action context
45
+ * @param args - Session parameters
46
+ * @returns Session info with sessionId, browserbaseSessionId, and cdpUrl
47
+ *
48
+ * @example
49
+ * ```typescript
50
+ * const session = await stagehand.startSession(ctx, {
51
+ * url: "https://example.com",
52
+ * });
53
+ * // Use session.sessionId with other operations
54
+ * // Or connect Playwright: puppeteer.connect({ browserWSEndpoint: session.cdpUrl })
55
+ * ```
56
+ */
57
+ async startSession(ctx, args) {
58
+ return ctx.runAction(this.component.lib.startSession, {
59
+ ...this.config,
60
+ url: args.url,
61
+ browserbaseSessionId: args.browserbaseSessionId,
62
+ options: args.options,
63
+ });
64
+ }
65
+ /**
66
+ * End a browser session.
67
+ *
68
+ * @param ctx - Convex action context
69
+ * @param args - Session to end
70
+ * @returns Success status
71
+ *
72
+ * @example
73
+ * ```typescript
74
+ * await stagehand.endSession(ctx, { sessionId: session.sessionId });
75
+ * ```
76
+ */
77
+ async endSession(ctx, args) {
78
+ return ctx.runAction(this.component.lib.endSession, {
79
+ ...this.config,
80
+ sessionId: args.sessionId,
81
+ });
82
+ }
83
+ /**
84
+ * Extract structured data from a web page using AI.
85
+ *
86
+ * @param ctx - Convex action context
87
+ * @param args - Extraction parameters
88
+ * @returns Extracted data matching the provided schema
89
+ *
90
+ * @example
91
+ * ```typescript
92
+ * // Without session (creates and destroys its own)
93
+ * const data = await stagehand.extract(ctx, {
94
+ * url: "https://news.ycombinator.com",
95
+ * instruction: "Extract the top 5 stories with title and score",
96
+ * schema: z.object({
97
+ * stories: z.array(z.object({
98
+ * title: z.string(),
99
+ * score: z.string(),
100
+ * }))
101
+ * }),
102
+ * });
103
+ *
104
+ * // With existing session (reuses session)
105
+ * const data = await stagehand.extract(ctx, {
106
+ * sessionId: session.sessionId,
107
+ * instruction: "Extract the top 5 stories",
108
+ * schema: z.object({ ... }),
109
+ * });
110
+ * ```
111
+ */
112
+ async extract(ctx, args) {
113
+ const jsonSchema = zodToJsonSchema(args.schema);
114
+ // Remove $schema field as it's reserved in Convex
115
+ delete jsonSchema.$schema;
116
+ return ctx.runAction(this.component.lib.extract, {
117
+ ...this.config,
118
+ sessionId: args.sessionId,
119
+ url: args.url,
120
+ instruction: args.instruction,
121
+ schema: jsonSchema,
122
+ options: args.options,
123
+ });
124
+ }
125
+ /**
126
+ * Execute a browser action using natural language.
127
+ *
128
+ * @param ctx - Convex action context
129
+ * @param args - Action parameters
130
+ * @returns Result of the action
131
+ *
132
+ * @example
133
+ * ```typescript
134
+ * // Without session
135
+ * const result = await stagehand.act(ctx, {
136
+ * url: "https://example.com/login",
137
+ * action: "Click the login button",
138
+ * });
139
+ *
140
+ * // With existing session
141
+ * const result = await stagehand.act(ctx, {
142
+ * sessionId: session.sessionId,
143
+ * action: "Click the submit button",
144
+ * });
145
+ * ```
146
+ */
147
+ async act(ctx, args) {
148
+ return ctx.runAction(this.component.lib.act, {
149
+ ...this.config,
150
+ sessionId: args.sessionId,
151
+ url: args.url,
152
+ action: args.action,
153
+ options: args.options,
154
+ });
155
+ }
156
+ /**
157
+ * Find available actions on a web page.
158
+ *
159
+ * @param ctx - Convex action context
160
+ * @param args - Observe parameters
161
+ * @returns List of available actions
162
+ *
163
+ * @example
164
+ * ```typescript
165
+ * const actions = await stagehand.observe(ctx, {
166
+ * url: "https://example.com",
167
+ * instruction: "Find all navigation links",
168
+ * });
169
+ * ```
170
+ */
171
+ async observe(ctx, args) {
172
+ return ctx.runAction(this.component.lib.observe, {
173
+ ...this.config,
174
+ sessionId: args.sessionId,
175
+ url: args.url,
176
+ instruction: args.instruction,
177
+ options: args.options,
178
+ });
179
+ }
180
+ /**
181
+ * Execute autonomous multi-step browser automation using an AI agent.
182
+ * The agent interprets the instruction and decides what actions to take.
183
+ *
184
+ * @param ctx - Convex action context
185
+ * @param args - Agent parameters
186
+ * @returns Agent execution result with actions taken
187
+ *
188
+ * @example
189
+ * ```typescript
190
+ * // Agent creates its own session
191
+ * const result = await stagehand.agent(ctx, {
192
+ * url: "https://google.com",
193
+ * instruction: "Search for 'convex database' and extract the top 3 results",
194
+ * options: { maxSteps: 10 },
195
+ * });
196
+ *
197
+ * // Agent with existing session
198
+ * const result = await stagehand.agent(ctx, {
199
+ * sessionId: session.sessionId,
200
+ * instruction: "Fill out the form and submit",
201
+ * options: { maxSteps: 5 },
202
+ * });
203
+ * ```
204
+ */
205
+ async agent(ctx, args) {
206
+ return ctx.runAction(this.component.lib.agent, {
207
+ ...this.config,
208
+ sessionId: args.sessionId,
209
+ url: args.url,
210
+ instruction: args.instruction,
211
+ options: args.options,
212
+ });
213
+ }
214
+ }
215
+ export default Stagehand;
216
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Generated `api` utility.
3
+ *
4
+ * THIS CODE IS AUTOMATICALLY GENERATED.
5
+ *
6
+ * To regenerate, run `npx convex dev`.
7
+ * @module
8
+ */
9
+ import type * as api_ from "../api.js";
10
+ import type * as lib from "../lib.js";
11
+ import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
12
+ declare const fullApi: ApiFromModules<{
13
+ api: typeof api_;
14
+ lib: typeof lib;
15
+ }>;
16
+ /**
17
+ * A utility for referencing Convex functions in your app's public API.
18
+ *
19
+ * Usage:
20
+ * ```js
21
+ * const myFunctionReference = api.myModule.myFunction;
22
+ * ```
23
+ */
24
+ export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "public">>;
25
+ /**
26
+ * A utility for referencing Convex functions in your app's internal API.
27
+ *
28
+ * Usage:
29
+ * ```js
30
+ * const myFunctionReference = internal.myModule.myFunction;
31
+ * ```
32
+ */
33
+ export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
34
+ export declare const components: {};
35
+ export {};
36
+ //# sourceMappingURL=api.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,KAAK,GAAG,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,QAAA,MAAM,OAAO,EAAE,cAAc,CAAC;IAC5B,GAAG,EAAE,OAAO,IAAI,CAAC;IACjB,GAAG,EAAE,OAAO,GAAG,CAAC;CACjB,CAAiB,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE,SAAS,CACzB,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CACjB,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAC9B,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CACnB,CAAC;AAElB,eAAO,MAAM,UAAU,EAAqC,EAAE,CAAC"}
@@ -0,0 +1,31 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * Generated `api` utility.
4
+ *
5
+ * THIS CODE IS AUTOMATICALLY GENERATED.
6
+ *
7
+ * To regenerate, run `npx convex dev`.
8
+ * @module
9
+ */
10
+ import { anyApi, componentsGeneric } from "convex/server";
11
+ const fullApi = anyApi;
12
+ /**
13
+ * A utility for referencing Convex functions in your app's public API.
14
+ *
15
+ * Usage:
16
+ * ```js
17
+ * const myFunctionReference = api.myModule.myFunction;
18
+ * ```
19
+ */
20
+ export const api = anyApi;
21
+ /**
22
+ * A utility for referencing Convex functions in your app's internal API.
23
+ *
24
+ * Usage:
25
+ * ```js
26
+ * const myFunctionReference = internal.myModule.myFunction;
27
+ * ```
28
+ */
29
+ export const internal = anyApi;
30
+ export const components = componentsGeneric();
31
+ //# sourceMappingURL=api.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAUH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,OAAO,GAGR,MAAa,CAAC;AAEnB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAGZ,MAAa,CAAC;AAElB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAGjB,MAAa,CAAC;AAElB,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAmB,CAAC"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Generated component type.
3
+ *
4
+ * THIS CODE IS AUTOMATICALLY GENERATED.
5
+ *
6
+ * To regenerate, run `npx convex dev`.
7
+ * @module
8
+ */
9
+ import type { FunctionReference } from "convex/server";
10
+ /**
11
+ * Component API type for the Stagehand component.
12
+ * Used by the client to call component actions.
13
+ */
14
+ export type ComponentApi = {
15
+ lib: {
16
+ startSession: FunctionReference<"action", "public", any, any>;
17
+ endSession: FunctionReference<"action", "public", any, any>;
18
+ extract: FunctionReference<"action", "public", any, any>;
19
+ act: FunctionReference<"action", "public", any, any>;
20
+ observe: FunctionReference<"action", "public", any, any>;
21
+ agent: FunctionReference<"action", "public", any, any>;
22
+ };
23
+ };
24
+ //# sourceMappingURL=component.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/component.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE;QACH,YAAY,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC9D,UAAU,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC5D,OAAO,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACzD,GAAG,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACrD,OAAO,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACzD,KAAK,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;KACxD,CAAC;CACH,CAAC"}
@@ -0,0 +1,11 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * Generated component type.
4
+ *
5
+ * THIS CODE IS AUTOMATICALLY GENERATED.
6
+ *
7
+ * To regenerate, run `npx convex dev`.
8
+ * @module
9
+ */
10
+ export {};
11
+ //# sourceMappingURL=component.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/component/_generated/component.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG"}
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Generated data model types.
3
+ *
4
+ * THIS CODE IS AUTOMATICALLY GENERATED.
5
+ *
6
+ * To regenerate, run `npx convex dev`.
7
+ * @module
8
+ */
9
+ import type { DataModelFromSchemaDefinition } from "convex/server";
10
+ import type schema from "../schema.js";
11
+ /**
12
+ * The type of a document stored in Convex.
13
+ */
14
+ export type DataModel = DataModelFromSchemaDefinition<typeof schema>;
15
+ //# sourceMappingURL=dataModel.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dataModel.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/dataModel.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AAEvC;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,6BAA6B,CAAC,OAAO,MAAM,CAAC,CAAC"}
@@ -0,0 +1,11 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * Generated data model types.
4
+ *
5
+ * THIS CODE IS AUTOMATICALLY GENERATED.
6
+ *
7
+ * To regenerate, run `npx convex dev`.
8
+ * @module
9
+ */
10
+ export {};
11
+ //# sourceMappingURL=dataModel.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dataModel.js","sourceRoot":"","sources":["../../../src/component/_generated/dataModel.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG"}