@bctrl/sdk 1.0.9 → 1.0.10

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 (2) hide show
  1. package/README.md +115 -71
  2. package/package.json +53 -51
package/README.md CHANGED
@@ -1,72 +1,116 @@
1
- # @bctrl/sdk
2
-
3
- TypeScript SDK for BCTRL v1 spaces, browser runtimes, invocations, runs, and files.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install @bctrl/sdk
9
- ```
10
-
11
- Node 18+ is required.
12
-
13
- ## Quick start
14
-
15
- ```ts
16
- import { Bctrl } from '@bctrl/sdk';
17
- import { z } from 'zod';
18
-
19
- const bctrl = new Bctrl({
20
- apiKey: process.env.BCTRL_API_KEY!,
21
- });
22
-
23
- const runtime = await bctrl.runtimes.create({
24
- type: 'browser',
25
- name: 'browser-task',
26
- });
27
- const started = await bctrl.runtimes.start(runtime.id);
28
- console.log(started.runId, started.connectUrl);
29
-
30
- const invocation = await bctrl.runtimes.invocations.createAndWait(
31
- started.runtimeId,
32
- {
33
- action: 'extract',
34
- instruction: 'Extract the page title.',
35
- schema: z.object({
36
- title: z.string(),
37
- }),
38
- },
1
+ # @bctrl/sdk
2
+
3
+ TypeScript and JavaScript SDK for BCTRL cloud browser automation. Create browser runtimes, start live sessions, run hosted browser agents, inspect runs, and manage platform resources from Node.js.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @bctrl/sdk
9
+ ```
10
+
11
+ Requires Node.js 22.14 or newer.
12
+
13
+ ## Quick Start
14
+
15
+ ```ts
16
+ import { Bctrl } from '@bctrl/sdk';
17
+
18
+ const bctrl = new Bctrl({
19
+ apiKey: process.env.BCTRL_API_KEY!,
20
+ });
21
+
22
+ const runtime = await bctrl.runtimes.create({
23
+ type: 'browser',
24
+ name: 'browser-task',
25
+ });
26
+
27
+ const started = await bctrl.runtimes.start(runtime.id);
28
+ console.log(started.runId, started.connectUrl);
29
+
30
+ await bctrl.runtimes.targets.create(started.runtimeId, {
31
+ uri: 'https://example.com',
32
+ activate: true,
33
+ });
34
+
35
+ await bctrl.runtimes.stop(started.runtimeId);
36
+ ```
37
+
38
+ ## Hosted Invocations
39
+
40
+ Use invocations when you want BCTRL to drive the browser for you.
41
+
42
+ ```ts
43
+ import { Bctrl } from '@bctrl/sdk';
44
+ import { z } from 'zod';
45
+
46
+ const bctrl = new Bctrl();
47
+
48
+ const invocation = await bctrl.runtimes.invocations.createAndWait(
49
+ '<runtime-id>',
50
+ {
51
+ action: 'extract',
52
+ instruction: 'Extract the product name and price.',
53
+ schema: z.object({
54
+ name: z.string(),
55
+ price: z.string(),
56
+ }),
57
+ },
39
58
  { timeoutSeconds: 60 }
40
- );
41
-
42
- console.log(invocation.status, invocation.output);
43
-
44
- await bctrl.runtimes.stop(started.runtimeId);
45
- ```
46
-
47
- The public SDK targets `https://api.bctrl.ai/v1`. For local development, pass a
48
- local origin or v1 base URL:
49
-
50
- ```ts
51
- const bctrl = new Bctrl({
52
- apiKey: process.env.BCTRL_API_KEY!,
53
- baseUrl: 'http://localhost:8787',
54
- });
55
- ```
56
-
57
- `baseUrl` may include or omit `/v1`; the client normalizes either form.
58
-
59
- ## Entry points
60
-
61
- - `@bctrl/sdk`: v1 client, resources, errors, and public types
62
-
63
- ## Documentation
64
-
65
- - SDK reference: https://platform.bctrl.ai/api-reference/sdk/overview
66
- - Product site: https://bctrl.ai
67
-
68
- ## Telemetry
69
-
70
- The published SDK does not include vendor-owned telemetry or usage analytics.
71
-
72
- If you want observability around SDK calls, instrument your application directly with your own logging or error tracking.
59
+ );
60
+
61
+ console.log(invocation.status, invocation.output);
62
+ ```
63
+
64
+ The SDK accepts Zod schemas or plain JSON Schema for structured extraction. On the wire, they are sent as `outputSchema`.
65
+
66
+ ## Configuration
67
+
68
+ The client reads `BCTRL_API_KEY` by default:
69
+
70
+ ```ts
71
+ const bctrl = new Bctrl();
72
+ ```
73
+
74
+ You can also pass configuration explicitly:
75
+
76
+ ```ts
77
+ const bctrl = new Bctrl({
78
+ apiKey: 'bctrl_...',
79
+ timeoutMs: 30_000,
80
+ maxRetries: 2,
81
+ });
82
+ ```
83
+
84
+ For subaccount-scoped calls:
85
+
86
+ ```ts
87
+ const scoped = bctrl.withSubaccount('<subaccount-id>');
88
+ ```
89
+
90
+ ## Errors
91
+
92
+ API failures throw typed errors with status, code, request id, and response body context:
93
+
94
+ ```ts
95
+ import { BctrlApiError } from '@bctrl/sdk';
96
+
97
+ try {
98
+ await bctrl.runtimes.get('<runtime-id>');
99
+ } catch (error) {
100
+ if (error instanceof BctrlApiError) {
101
+ console.error(error.status, error.code, error.requestId);
102
+ }
103
+ }
104
+ ```
105
+
106
+ The client retries retryable GET requests by default. Mutating requests are retried only when you provide an idempotency key.
107
+
108
+ ## Documentation
109
+
110
+ - SDK guide: https://platform.bctrl.ai/sdk
111
+ - API reference: https://platform.bctrl.ai/api-reference
112
+ - Product: https://bctrl.ai
113
+
114
+ ## Telemetry
115
+
116
+ The SDK does not include vendor-owned telemetry or usage analytics. Instrument your application directly if you want request logging or tracing.
package/package.json CHANGED
@@ -1,51 +1,53 @@
1
- {
2
- "name": "@bctrl/sdk",
3
- "version": "1.0.9",
4
- "description": "BCTRL SDK - Remote browser automation",
5
- "repository": {
6
- "type": "git",
7
- "url": "https://github.com/bctrlhq/sdk-js.git"
8
- },
9
- "main": "./dist/index.js",
10
- "types": "./dist/index.d.ts",
11
- "type": "module",
12
- "exports": {
13
- ".": {
14
- "types": "./dist/index.d.ts",
15
- "import": "./dist/index.js"
16
- },
17
- "./node": {
18
- "types": "./dist/node.d.ts",
19
- "import": "./dist/node.js"
20
- }
21
- },
22
- "keywords": [],
23
- "author": "",
24
- "license": "ISC",
25
- "engines": {
26
- "node": ">=22.14.0"
27
- },
28
- "dependencies": {
29
- "zod": "^4.4.3"
30
- },
31
- "devDependencies": {
32
- "@types/node": "^25.0.3",
33
- "@typescript-eslint/eslint-plugin": "^8.56.0",
34
- "@typescript-eslint/parser": "^8.56.0",
35
- "eslint": "^10.0.0",
36
- "tsx": "^4.21.0",
37
- "typescript": "^5.9.3"
38
- },
39
- "files": [
40
- "dist"
41
- ],
42
- "scripts": {
43
- "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
44
- "build": "pnpm run clean && tsc -p tsconfig.json",
45
- "dev": "tsc --watch",
46
- "test": "tsx --test tests/v1/*.test.ts tests/v1/e2e/*.test.ts",
47
- "test:v1": "tsx --test tests/v1/*.test.ts tests/v1/e2e/*.test.ts",
48
- "test:v1:e2e": "BCTRL_E2E=1 tsx --test tests/v1/e2e/**/*.test.ts",
49
- "typecheck": "tsc --noEmit"
50
- }
51
- }
1
+ {
2
+ "name": "@bctrl/sdk",
3
+ "version": "1.0.10",
4
+ "description": "BCTRL SDK - Remote browser automation",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/bctrlhq/sdk-js.git"
8
+ },
9
+ "main": "./dist/index.js",
10
+ "types": "./dist/index.d.ts",
11
+ "type": "module",
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/index.d.ts",
15
+ "import": "./dist/index.js"
16
+ },
17
+ "./node": {
18
+ "types": "./dist/node.d.ts",
19
+ "import": "./dist/node.js"
20
+ }
21
+ },
22
+ "scripts": {
23
+ "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
24
+ "build": "pnpm run clean && tsc -p tsconfig.json",
25
+ "prepack": "pnpm run build",
26
+ "dev": "tsc --watch",
27
+ "test": "tsx --test tests/v1/*.test.ts tests/v1/e2e/*.test.ts",
28
+ "test:v1": "tsx --test tests/v1/*.test.ts tests/v1/e2e/*.test.ts",
29
+ "test:v1:e2e": "BCTRL_E2E=1 tsx --test tests/v1/e2e/**/*.test.ts",
30
+ "typecheck": "tsc --noEmit"
31
+ },
32
+ "keywords": [],
33
+ "author": "",
34
+ "license": "ISC",
35
+ "engines": {
36
+ "node": ">=22.14.0"
37
+ },
38
+ "dependencies": {
39
+ "zod": "^4.4.3"
40
+ },
41
+ "packageManager": "pnpm@10.12.4",
42
+ "devDependencies": {
43
+ "@types/node": "^25.0.3",
44
+ "@typescript-eslint/eslint-plugin": "^8.56.0",
45
+ "@typescript-eslint/parser": "^8.56.0",
46
+ "eslint": "^10.0.0",
47
+ "tsx": "^4.21.0",
48
+ "typescript": "^5.9.3"
49
+ },
50
+ "files": [
51
+ "dist"
52
+ ]
53
+ }