@bctrl/sdk 1.0.1 → 1.0.3

package/dist/internal/transport.js

@@ -1,29 +0,0 @@
-/**
- * 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

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

package/dist/playwright.js

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

package/dist/puppeteer.d.ts

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

package/dist/puppeteer.js

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

package/dist/selenium.d.ts

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

package/dist/selenium.js

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

package/dist/stagehand.d.ts

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

package/dist/stagehand.js

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

package/dist/storage/client.d.ts

@@ -1,151 +0,0 @@
-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>;
-}

package/dist/storage/client.js

@@ -1,329 +0,0 @@
-// ============================================================================
-// Storage Client - SDK client for R2 storage operations
-// ============================================================================
-import { StorageBrowseResponseSchema, StorageReadResponseSchema, } from '../contracts/storage.js';
-import { SDK_VERSION } from '../version.js';
-import { fetchWithTimeout, parseJsonResponse, LONG_TIMEOUT_MS } from '../utils/http.js';
-import { stripTrailingSlash } from '../utils/url.js';
-// ============================================================================
-// Storage Client
-// ============================================================================
-/**
- * Client for interacting with workspace storage.
- */
-export class StorageClient {
-    baseUrl;
-    workspace;
-    apiKey;
-    sessionId;
-    constructor(baseUrl, workspace, apiKey, sessionId) {
-        this.baseUrl = baseUrl;
-        this.workspace = workspace;
-        this.apiKey = apiKey;
-        this.sessionId = sessionId;
-    }
-    /**
-     * Get headers for API requests.
-     */
-    getHeaders(contentType) {
-        const headers = {
-            'x-sdk-version': SDK_VERSION,
-        };
-        if (this.apiKey) {
-            headers['Authorization'] = `Bearer ${this.apiKey}`;
-        }
-        if (this.sessionId) {
-            headers['x-session-id'] = this.sessionId;
-        }
-        if (contentType) {
-            headers['Content-Type'] = contentType;
-        }
-        return headers;
-    }
-    /**
-     * Clone this client for another workspace while preserving auth/session binding.
-     */
-    forWorkspace(workspace) {
-        return new StorageClient(this.baseUrl, workspace, this.apiKey, this.sessionId);
-    }
-    /**
-     * Build URL for object-catalog endpoints.
-     */
-    buildObjectsUrl(path = '') {
-        const base = stripTrailingSlash(this.baseUrl);
-        return `${base}/storage/objects${path}`;
-    }
-    resolveWorkspace(workspace) {
-        const value = (workspace || this.workspace).trim();
-        if (!value) {
-            throw new Error('Workspace is required');
-        }
-        return value;
-    }
-    encodePath(filePath) {
-        return filePath
-            .split('/')
-            .filter((segment) => segment.length > 0)
-            .map((segment) => encodeURIComponent(segment))
-            .join('/');
-    }
-    buildWorkspaceUrl(path, workspace, params = {}) {
-        const query = new URLSearchParams({ workspace });
-        for (const [key, value] of Object.entries(params)) {
-            if (value === undefined || value === null || value === '')
-                continue;
-            query.set(key, String(value));
-        }
-        return this.buildObjectsUrl(`${path}?${query.toString()}`);
-    }
-    toBlob(data, contentType) {
-        if (data instanceof Blob)
-            return data;
-        const copy = new Uint8Array(data);
-        return new Blob([copy], contentType ? { type: contentType } : undefined);
-    }
-    /**
-     * 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)
-     */
-    async upload(filePath, data, filename) {
-        const workspace = this.resolveWorkspace();
-        const uploaded = await this.uploadObject(data, {
-            workspace,
-            path: filePath,
-            source: 'upload',
-            filename,
-        });
-        return {
-            success: true,
-            key: uploaded.objectKey,
-            filename: uploaded.filename,
-        };
-    }
-    /**
-     * 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
-     */
-    async uploadObject(data, options = {}) {
-        const formData = new FormData();
-        const workspace = this.resolveWorkspace(options.workspace);
-        const logicalPath = options.path?.trim() || undefined;
-        const source = options.source?.trim() || 'upload';
-        const filename = options.filename?.trim() ||
-            (logicalPath ? logicalPath.split('/').pop() : null) ||
-            'file';
-        // Multipart parsing is sequential; send metadata fields before file.
-        formData.append('workspace', workspace);
-        formData.append('source', source);
-        if (logicalPath)
-            formData.append('path', logicalPath);
-        if (options.runtimeId)
-            formData.append('runtimeId', options.runtimeId);
-        if (options.driver)
-            formData.append('driver', options.driver);
-        if (options.target)
-            formData.append('target', options.target);
-        formData.append('file', this.toBlob(data), filename);
-        const response = await fetchWithTimeout(this.buildObjectsUrl(''), {
-            method: 'POST',
-            headers: this.getHeaders(),
-            body: formData,
-        }, LONG_TIMEOUT_MS);
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(`Upload object failed: ${error.error || response.statusText}`);
-        }
-        return parseJsonResponse(response, 'Upload storage object');
-    }
-    /**
-     * Get a file by logical path as raw bytes.
-     */
-    async get(filePath) {
-        const workspace = this.resolveWorkspace();
-        const encodedPath = this.encodePath(filePath);
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl(`/by-path/get/${encodedPath}`, workspace), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        }, LONG_TIMEOUT_MS);
-        if (!response.ok) {
-            throw new Error(`Get failed: ${response.statusText}`);
-        }
-        const arrayBuffer = await response.arrayBuffer();
-        return Buffer.from(arrayBuffer);
-    }
-    /**
-     * Get a presigned URL for direct download by logical path.
-     */
-    async getDownloadUrl(filePath) {
-        const workspace = this.resolveWorkspace();
-        const encodedPath = this.encodePath(filePath);
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl(`/by-path/presign-download/${encodedPath}`, workspace), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to get download URL: ${response.statusText}`);
-        }
-        const { url } = await parseJsonResponse(response, 'Get download URL');
-        return url;
-    }
-    /**
-     * Browse files/folders by logical prefix (hierarchical listing with cursor pagination).
-     */
-    async browse(options = {}) {
-        const workspace = this.resolveWorkspace();
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl('/by-path/browse', workspace, {
-            prefix: options.prefix,
-            cursor: options.cursor,
-            limit: options.limit,
-        }), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Browse failed: ${response.statusText}`);
-        }
-        const data = await parseJsonResponse(response, 'Browse files');
-        return StorageBrowseResponseSchema.parse(data);
-    }
-    /**
-     * Read a UTF-8 text preview by logical path.
-     */
-    async read(filePath, maxBytes) {
-        const workspace = this.resolveWorkspace();
-        const encodedPath = this.encodePath(filePath);
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl(`/by-path/read/${encodedPath}`, workspace, {
-            maxBytes,
-        }), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Read failed: ${response.statusText}`);
-        }
-        const data = await parseJsonResponse(response, 'Read file text preview');
-        return StorageReadResponseSchema.parse(data);
-    }
-    /**
-     * List object metadata from the storage catalog.
-     */
-    async listObjects(options = {}) {
-        const workspace = this.resolveWorkspace(options.workspace);
-        const params = new URLSearchParams({ workspace });
-        if (options.runtimeId)
-            params.set('runtimeId', options.runtimeId);
-        if (options.source)
-            params.set('source', options.source);
-        if (options.driver)
-            params.set('driver', options.driver);
-        if (options.target)
-            params.set('target', options.target);
-        if (options.pathPrefix)
-            params.set('pathPrefix', options.pathPrefix);
-        if (typeof options.limit === 'number')
-            params.set('limit', String(options.limit));
-        if (typeof options.offset === 'number')
-            params.set('offset', String(options.offset));
-        const response = await fetchWithTimeout(this.buildObjectsUrl(`?${params.toString()}`), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`List objects failed: ${response.statusText}`);
-        }
-        const { objects } = await parseJsonResponse(response, 'List storage objects');
-        return objects;
-    }
-    /**
-     * Download an object by catalog ID.
-     */
-    async downloadObject(id) {
-        const response = await fetchWithTimeout(this.buildObjectsUrl(`/${encodeURIComponent(id)}/download`), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        }, LONG_TIMEOUT_MS);
-        if (!response.ok) {
-            throw new Error(`Object download failed: ${response.statusText}`);
-        }
-        const arrayBuffer = await response.arrayBuffer();
-        return Buffer.from(arrayBuffer);
-    }
-    /**
-     * Get a presigned URL for direct download by object ID.
-     */
-    async getObjectDownloadUrl(id) {
-        const response = await fetchWithTimeout(this.buildObjectsUrl(`/${encodeURIComponent(id)}/presign-download`), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to get object download URL: ${response.statusText}`);
-        }
-        const { url } = await parseJsonResponse(response, 'Get object download URL');
-        return url;
-    }
-    /**
-     * Get all downloads as a ZIP file.
-     */
-    async getDownloadsZip() {
-        const workspace = this.resolveWorkspace();
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl('/downloads', workspace), {
-            method: 'GET',
-            headers: this.getHeaders(),
-        }, LONG_TIMEOUT_MS);
-        if (!response.ok) {
-            if (response.status === 404) {
-                throw new Error('No downloads found');
-            }
-            throw new Error(`Failed to get downloads: ${response.statusText}`);
-        }
-        const arrayBuffer = await response.arrayBuffer();
-        return Buffer.from(arrayBuffer);
-    }
-    /**
-     * Delete a file by logical path.
-     */
-    async delete(filePath) {
-        const workspace = this.resolveWorkspace();
-        const encodedPath = this.encodePath(filePath);
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl(`/by-path/${encodedPath}`, workspace), {
-            method: 'DELETE',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Delete failed: ${response.statusText}`);
-        }
-    }
-    /**
-     * Delete an object by catalog ID.
-     */
-    async deleteObject(id) {
-        const response = await fetchWithTimeout(this.buildObjectsUrl(`/${encodeURIComponent(id)}`), {
-            method: 'DELETE',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Delete object failed: ${response.statusText}`);
-        }
-    }
-    /**
-     * Delete all files for this workspace.
-     */
-    async deleteAll() {
-        const workspace = this.resolveWorkspace();
-        const response = await fetchWithTimeout(this.buildWorkspaceUrl('', workspace), {
-            method: 'DELETE',
-            headers: this.getHeaders(),
-        });
-        if (!response.ok) {
-            throw new Error(`Delete all failed: ${response.statusText}`);
-        }
-        const result = await parseJsonResponse(response, 'Delete all');
-        return result.deletedCount;
-    }
-}

package/dist/storage/index.d.ts

@@ -1,2 +0,0 @@
-export { StorageClient } from './client.js';
-export type { StorageBrowseOptions, StorageBrowseFile, StorageBrowseResult, StorageReadResult, UploadResult, PresignedUrlResult, StorageObject, ListObjectsOptions, ListObjectsResult, UploadObjectOptions, UploadObjectResult, } from './client.js';

package/dist/storage/index.js

@@ -1,4 +0,0 @@
-// ============================================================================
-// Storage Module - SDK storage client exports
-// ============================================================================
-export { StorageClient } from './client.js';

package/dist/telemetry.d.ts

@@ -1,18 +0,0 @@
-/**
- * Initialize the isolated Sentry client for SDK telemetry.
- * Idempotent — safe to call multiple times (e.g. from multiple Bctrl instances).
- * Uses a separate client instance to avoid conflicts with user's Sentry.
- */
-export declare function init(): void;
-/**
- * Disable telemetry. Once called, no events will be sent.
- */
-export declare function disable(): void;
-/**
- * Capture an error and send it to Sentry (if telemetry is enabled).
- */
-export declare function captureError(err: Error, context?: Record<string, unknown>): void;
-/**
- * Check if telemetry is currently enabled.
- */
-export declare function isEnabled(): boolean;

package/dist/telemetry.js

@@ -1,93 +0,0 @@
-// ============================================================================
-// SDK Telemetry - Isolated Sentry client for error tracking
-// ============================================================================
-//
-// Uses a dedicated Sentry client that won't conflict with the user's own Sentry.
-// Respects the `telemetry: false` opt-out in BctrlOptions.
-// Strips auth headers and sensitive data before sending events.
-// ============================================================================
-import { NodeClient, Scope, makeNodeTransport, defaultStackParser, } from '@sentry/node';
-import { SDK_VERSION } from './version.js';
-let sentryClient;
-let enabled = true;
-function isRemoteTelemetryEnabled() {
-    return process.env.NODE_ENV !== 'development' || process.env.OBS_REMOTE === 'true';
-}
-/**
- * Initialize the isolated Sentry client for SDK telemetry.
- * Idempotent — safe to call multiple times (e.g. from multiple Bctrl instances).
- * Uses a separate client instance to avoid conflicts with user's Sentry.
- */
-export function init() {
-    if (sentryClient)
-        return;
-    const dsn = process.env.SENTRY_DSN_SDK;
-    if (!dsn || !enabled || !isRemoteTelemetryEnabled())
-        return;
-    sentryClient = new NodeClient({
-        dsn,
-        release: `bctrl-sdk@${SDK_VERSION}`,
-        environment: process.env.NODE_ENV || 'production',
-        transport: makeNodeTransport,
-        stackParser: defaultStackParser,
-        integrations: [],
-        beforeSend(event) {
-            // Strip sensitive headers and data
-            if (event.request?.headers) {
-                delete event.request.headers['authorization'];
-                delete event.request.headers['x-internal-secret'];
-                delete event.request.headers['cookie'];
-            }
-            // Strip any sensitive data from breadcrumbs
-            if (event.breadcrumbs) {
-                for (const breadcrumb of event.breadcrumbs) {
-                    if (breadcrumb.data) {
-                        delete breadcrumb.data['authorization'];
-                        delete breadcrumb.data['apiKey'];
-                        delete breadcrumb.data['password'];
-                    }
-                }
-            }
-            // Tag every event with SDK version
-            event.tags = { ...event.tags, sdkVersion: SDK_VERSION };
-            return event;
-        },
-    });
-}
-/**
- * Disable telemetry. Once called, no events will be sent.
- */
-export function disable() {
-    enabled = false;
-    if (sentryClient) {
-        sentryClient.close();
-        sentryClient = undefined;
-    }
-}
-/**
- * Capture an error and send it to Sentry (if telemetry is enabled).
- */
-export function captureError(err, context) {
-    if (!enabled || !sentryClient)
-        return;
-    const scope = new Scope();
-    scope.setClient(sentryClient);
-    if (context) {
-        scope.setContext('bctrl', context);
-        if (context.endpoint)
-            scope.setTag('endpoint', String(context.endpoint));
-        if (context.method)
-            scope.setTag('method', String(context.method));
-        if (context.statusCode)
-            scope.setTag('statusCode', String(context.statusCode));
-        if (context.errorCode)
-            scope.setTag('errorCode', String(context.errorCode));
-    }
-    scope.captureException(err);
-}
-/**
- * Check if telemetry is currently enabled.
- */
-export function isEnabled() {
-    return enabled && sentryClient !== undefined;
-}

package/dist/updates/client.d.ts

@@ -1,8 +0,0 @@
-import type { UpdateEvent } from '../contracts/public-api.js';
-export declare class UpdatesClient {
-    private readonly baseUrl;
-    private readonly apiKey;
-    constructor(baseUrl: string, apiKey: string);
-    stream(signal?: AbortSignal): AsyncGenerator<UpdateEvent, void, void>;
-    private issueToken;
-}