@bctrl/sdk 1.0.1

package/dist/index.js

@@ -0,0 +1,23 @@
+// ============================================================================
+// BCTRL SDK - Core Entry Point
+// ============================================================================
+//
+// Keep the root entrypoint lean.
+// Driver-specific classes and types are exposed via subpath exports:
+// - <package>/puppeteer
+// - <package>/playwright
+// - <package>/stagehand
+// - <package>/selenium
+//
+export { z } from 'zod';
+// Core errors
+export { BctrlError, AutomationError, AutomationError as SdkAutomationError, SessionError, TimeoutError, AuthenticationError, fromErrorResponse, isBctrlError, isAutomationError, isSessionError, isTimeoutError, isAuthenticationError, getAutomationHint, } from './errors.js';
+// Service clients
+export * from './storage/index.js';
+export * from './ai-credentials/index.js';
+export * from './browser-extensions/index.js';
+export * from './browser-profiles/index.js';
+export * from './vault/index.js';
+export * from './updates/index.js';
+export * from './workspaces/index.js';
+export { Bctrl } from './bctrl.js';

package/dist/internal/dev-client.d.ts

@@ -0,0 +1,5 @@
+import { type Bctrl, type BctrlOptions } from '../bctrl.js';
+export interface InternalBctrlOptions extends BctrlOptions {
+    apiOrigin?: string;
+}
+export declare function createInternalBctrl(options: InternalBctrlOptions): Bctrl;

package/dist/internal/dev-client.js

@@ -0,0 +1,9 @@
+import { createInternalBctrlClient } from '../bctrl.js';
+import { resolveInternalApiBaseUrl } from '../config.js';
+export function createInternalBctrl(options) {
+    return createInternalBctrlClient({
+        apiKey: options.apiKey,
+        telemetry: options.telemetry,
+        apiBaseUrl: resolveInternalApiBaseUrl(options.apiOrigin),
+    });
+}

package/dist/internal/rpc-targets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: scripts/generate/rpc-targets-config.ts
+ * Run `pnpm generate:rpc-targets` to regenerate.
+ */
+/**
+ * All valid SDK RPC target types.
+ * Generated from driver handler configurations.
+ */
+export declare const RPC_TARGETS: readonly ["browser", "browserUse", "consoleMessage", "context", "cua", "desktop", "dialog", "element", "fileChooser", "frame", "httpRequest", "httpResponse", "jsHandle", "locator", "page", "response", "selenium", "selenium-element", "stagehand", "target", "worker"];
+export type RpcTarget = (typeof RPC_TARGETS)[number];
+export declare const HANDLE_TARGETS: ReadonlySet<RpcTarget>;
+export declare const PAGE_REF_TARGETS: ReadonlySet<RpcTarget>;
+export declare const CONTEXT_REF_TARGETS: ReadonlySet<RpcTarget>;
+export declare const SCREENSHOT_ARTIFACT_TARGETS: ReadonlySet<RpcTarget>;
+export declare const PDF_ARTIFACT_TARGETS: ReadonlySet<RpcTarget>;

package/dist/internal/rpc-targets.js

@@ -0,0 +1,58 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: scripts/generate/rpc-targets-config.ts
+ * Run `pnpm generate:rpc-targets` to regenerate.
+ */
+/**
+ * All valid SDK RPC target types.
+ * Generated from driver handler configurations.
+ */
+export const RPC_TARGETS = [
+    'browser',
+    'browserUse',
+    'consoleMessage',
+    'context',
+    'cua',
+    'desktop',
+    'dialog',
+    'element',
+    'fileChooser',
+    'frame',
+    'httpRequest',
+    'httpResponse',
+    'jsHandle',
+    'locator',
+    'page',
+    'response',
+    'selenium',
+    'selenium-element',
+    'stagehand',
+    'target',
+    'worker',
+];
+export const HANDLE_TARGETS = new Set([
+    'consoleMessage',
+    'dialog',
+    'element',
+    'frame',
+    'jsHandle',
+    'worker',
+]);
+export const PAGE_REF_TARGETS = new Set([
+    'browserUse',
+    'locator',
+    'page',
+    'stagehand',
+]);
+export const CONTEXT_REF_TARGETS = new Set([
+    'context',
+]);
+export const SCREENSHOT_ARTIFACT_TARGETS = new Set([
+    'element',
+    'locator',
+    'page',
+]);
+export const PDF_ARTIFACT_TARGETS = new Set([
+    'page',
+]);

package/dist/internal/serialization.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: packages/automation-spec/src/drivers/puppeteer/methods/types.ts
+ * Run `pnpm generate:sdk-contracts` to regenerate.
+ */
+/**
+ * Shared Types for Schema-Driven Code Generation
+ *
+ * Contains serialization schemas used across the Puppeteer SDK.
+ */
+import { z } from 'zod';
+/**
+ * Schema for serialized handle reference (returned from RPC)
+ */
+export declare const SerializedHandleSchema: z.ZodObject<{
+    __bctrl_type: z.ZodLiteral<"Handle">;
+    id: z.ZodString;
+    handleType: z.ZodString;
+}, z.core.$strip>;
+export type SerializedHandle = z.infer<typeof SerializedHandleSchema>;
+/**
+ * Schema for handle ID passed as argument (sent to RPC)
+ */
+export declare const HandleRefSchema: z.ZodObject<{
+    __bctrl_handle_id: z.ZodString;
+}, z.core.$strip>;
+export type HandleRef = z.infer<typeof HandleRefSchema>;
+/**
+ * Type guard to check if a value is a SerializedHandle.
+ */
+export declare function isSerializedHandle(value: unknown): value is SerializedHandle;

package/dist/internal/serialization.js

@@ -0,0 +1,42 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: packages/automation-spec/src/drivers/puppeteer/methods/types.ts
+ * Run `pnpm generate:sdk-contracts` to regenerate.
+ */
+/**
+ * Shared Types for Schema-Driven Code Generation
+ *
+ * Contains serialization schemas used across the Puppeteer SDK.
+ */
+import { z } from 'zod';
+// ============================================================================
+// Handle Serialization Schemas
+// ============================================================================
+/**
+ * Schema for serialized handle reference (returned from RPC)
+ */
+export const SerializedHandleSchema = z.object({
+    __bctrl_type: z.literal('Handle'),
+    id: z.string(),
+    handleType: z.string(),
+});
+/**
+ * Schema for handle ID passed as argument (sent to RPC)
+ */
+export const HandleRefSchema = z.object({
+    __bctrl_handle_id: z.string(),
+});
+/**
+ * Type guard to check if a value is a SerializedHandle.
+ */
+export function isSerializedHandle(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '__bctrl_type' in value &&
+        value.__bctrl_type === 'Handle' &&
+        'id' in value &&
+        typeof value.id === 'string' &&
+        'handleType' in value &&
+        typeof value.handleType === 'string');
+}

package/dist/internal/transport.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal SDK transport and handle helpers.
+ *
+ * These are SDK implementation details used by sessions, namespaces, and
+ * generated driver classes. They intentionally live inside the SDK so the
+ * public package does not depend on shared schema helpers for its own runtime.
+ */
+import type { RpcTarget } from './rpc-targets.js';
+export type { RpcTarget } from './rpc-targets.js';
+export type SimpleRpcSender = <T = unknown>(method: string, args: unknown[]) => Promise<T>;
+export type RpcSender = <T = unknown>(target: RpcTarget, method: string, args: unknown[], ids?: {
+    contextId?: string;
+    pageId?: string;
+}) => Promise<T>;
+export interface HasHandleId {
+    readonly handleId: string;
+}
+export declare function extractHandleId(value: string | HasHandleId | undefined | null): string | undefined;
+export declare function toHandleRef<T>(value: T | HasHandleId): T | {
+    __bctrl_handle_id: string;
+};
+export declare function serializeFunctionSource(value: Function): string;
+export declare function serializeFunctionSource(value: string): string;
+export declare function serializeFunctionSource<T>(value: T): T;

package/dist/internal/transport.js

@@ -0,0 +1,29 @@
+/**
+ * Internal SDK transport and handle helpers.
+ *
+ * These are SDK implementation details used by sessions, namespaces, and
+ * generated driver classes. They intentionally live inside the SDK so the
+ * public package does not depend on shared schema helpers for its own runtime.
+ */
+function hasHandleId(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        'handleId' in value &&
+        typeof value.handleId === 'string');
+}
+export function extractHandleId(value) {
+    if (!value)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    return value.handleId;
+}
+export function toHandleRef(value) {
+    if (hasHandleId(value)) {
+        return { __bctrl_handle_id: value.handleId };
+    }
+    return value;
+}
+export function serializeFunctionSource(value) {
+    return typeof value === 'function' ? Function.prototype.toString.call(value) : value;
+}

package/dist/playwright.d.ts

@@ -0,0 +1 @@
+export * from './drivers/playwright/index.js';

package/dist/playwright.js

@@ -0,0 +1,2 @@
+// Playwright driver entrypoint.
+export * from './drivers/playwright/index.js';

package/dist/puppeteer.d.ts

@@ -0,0 +1 @@
+export * from './drivers/puppeteer/index.js';

package/dist/puppeteer.js

@@ -0,0 +1,2 @@
+// Puppeteer driver entrypoint.
+export * from './drivers/puppeteer/index.js';

package/dist/selenium.d.ts

@@ -0,0 +1 @@
+export * from './drivers/selenium/index.js';

package/dist/selenium.js

@@ -0,0 +1,2 @@
+// Selenium driver entrypoint.
+export * from './drivers/selenium/index.js';

package/dist/stagehand.d.ts

@@ -0,0 +1 @@
+export * from './drivers/stagehand/index.js';

package/dist/stagehand.js

@@ -0,0 +1,2 @@
+// Stagehand driver entrypoint.
+export * from './drivers/stagehand/index.js';

package/dist/storage/client.d.ts

@@ -0,0 +1,151 @@
+import { type StorageBrowseResponse, type StorageReadResponse } from '../contracts/storage.js';
+export type StorageBrowseResult = StorageBrowseResponse;
+export type StorageBrowseFile = StorageBrowseResult['files'][number];
+export type StorageReadResult = StorageReadResponse;
+export interface UploadResult {
+    success: boolean;
+    key: string;
+    filename: string;
+}
+export interface PresignedUrlResult {
+    url: string;
+    key?: string;
+    expiresIn: number;
+}
+export interface StorageObject {
+    id: string;
+    workspace: string;
+    runtimeId: string | null;
+    source: string;
+    driver: string | null;
+    target: string | null;
+    logicalPath: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    createdAt: string | null;
+    expiresAt: string | null;
+    metadata: Record<string, unknown> | null;
+}
+export interface ListObjectsOptions {
+    workspace?: string;
+    runtimeId?: string;
+    source?: string;
+    driver?: string;
+    target?: string;
+    pathPrefix?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ListObjectsResult {
+    objects: StorageObject[];
+}
+export interface UploadObjectOptions {
+    workspace?: string;
+    path?: string;
+    source?: string;
+    runtimeId?: string;
+    driver?: string;
+    target?: string;
+    filename?: string;
+}
+export interface UploadObjectResult {
+    id: string;
+    workspace: string;
+    logicalPath: string;
+    objectKey: string;
+    filename: string;
+    sizeBytes: number;
+    contentType: string;
+    expiresAt: string | null;
+}
+export interface StorageBrowseOptions {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * Client for interacting with workspace storage.
+ */
+export declare class StorageClient {
+    private readonly baseUrl;
+    private readonly workspace;
+    private readonly apiKey?;
+    private readonly sessionId?;
+    constructor(baseUrl: string, workspace: string, apiKey?: string | undefined, sessionId?: string | undefined);
+    /**
+     * Get headers for API requests.
+     */
+    private getHeaders;
+    /**
+     * Clone this client for another workspace while preserving auth/session binding.
+     */
+    forWorkspace(workspace: string): StorageClient;
+    /**
+     * Build URL for object-catalog endpoints.
+     */
+    private buildObjectsUrl;
+    private resolveWorkspace;
+    private encodePath;
+    private buildWorkspaceUrl;
+    private toBlob;
+    /**
+     * Upload a file to workspace storage.
+     *
+     * @param filePath - Logical path in storage (e.g., "uploads/document.pdf")
+     * @param data - File data as Buffer, Uint8Array, or Blob
+     * @param filename - Optional filename (defaults to last part of filePath)
+     */
+    upload(filePath: string, data: Buffer | Uint8Array | Blob, filename?: string): Promise<UploadResult>;
+    /**
+     * Upload a file and register it in the storage object catalog.
+     *
+     * @param data - File data as Buffer, Uint8Array, or Blob
+     * @param options - Metadata and upload options
+     */
+    uploadObject(data: Buffer | Uint8Array | Blob, options?: UploadObjectOptions): Promise<UploadObjectResult>;
+    /**
+     * Get a file by logical path as raw bytes.
+     */
+    get(filePath: string): Promise<Buffer>;
+    /**
+     * Get a presigned URL for direct download by logical path.
+     */
+    getDownloadUrl(filePath: string): Promise<string>;
+    /**
+     * Browse files/folders by logical prefix (hierarchical listing with cursor pagination).
+     */
+    browse(options?: StorageBrowseOptions): Promise<StorageBrowseResult>;
+    /**
+     * Read a UTF-8 text preview by logical path.
+     */
+    read(filePath: string, maxBytes?: number): Promise<StorageReadResult>;
+    /**
+     * List object metadata from the storage catalog.
+     */
+    listObjects(options?: ListObjectsOptions): Promise<StorageObject[]>;
+    /**
+     * Download an object by catalog ID.
+     */
+    downloadObject(id: string): Promise<Buffer>;
+    /**
+     * Get a presigned URL for direct download by object ID.
+     */
+    getObjectDownloadUrl(id: string): Promise<string>;
+    /**
+     * Get all downloads as a ZIP file.
+     */
+    getDownloadsZip(): Promise<Buffer>;
+    /**
+     * Delete a file by logical path.
+     */
+    delete(filePath: string): Promise<void>;
+    /**
+     * Delete an object by catalog ID.
+     */
+    deleteObject(id: string): Promise<void>;
+    /**
+     * Delete all files for this workspace.
+     */
+    deleteAll(): Promise<number>;
+}