@bctrl/sdk 1.0.1

package/dist/storage/client.js

@@ -0,0 +1,329 @@
+// ============================================================================
+// 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

@@ -0,0 +1,2 @@
+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

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

package/dist/telemetry.d.ts

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

@@ -0,0 +1,93 @@
+// ============================================================================
+// 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

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

package/dist/updates/client.js

@@ -0,0 +1,128 @@
+import { UpdateEventSchema } from '../contracts/public-api.js';
+import { parseErrorDetails, parseJsonResponse } from '../utils/http.js';
+import { SDK_VERSION } from '../version.js';
+function buildHeaders(apiKey, accept) {
+    const headers = {
+        'x-sdk-version': SDK_VERSION,
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (accept) {
+        headers.Accept = accept;
+    }
+    return headers;
+}
+export class UpdatesClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async *stream(signal) {
+        const token = await this.issueToken();
+        const response = await fetch(`${this.baseUrl}/updates/stream?token=${encodeURIComponent(token)}`, {
+            method: 'GET',
+            headers: buildHeaders(this.apiKey, 'text/event-stream'),
+            signal,
+        });
+        if (!response.ok) {
+            const details = parseErrorDetails(await response.text().catch(() => ''));
+            throw new Error(`Open updates stream: ${details.message}`);
+        }
+        const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+        if (!contentType.includes('text/event-stream')) {
+            throw new Error(`Open updates stream: unsupported content type '${contentType || 'unknown'}'`);
+        }
+        if (!response.body) {
+            throw new Error('Open updates stream: response did not include a body');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let eventName = 'message';
+        const dataLines = [];
+        const flushEvent = () => {
+            if (dataLines.length === 0) {
+                eventName = 'message';
+                return null;
+            }
+            const raw = dataLines.join('\n');
+            dataLines.length = 0;
+            const currentEventName = eventName;
+            eventName = 'message';
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+            if (!parsed || typeof parsed !== 'object') {
+                return null;
+            }
+            if (currentEventName === 'connected') {
+                return null;
+            }
+            const normalized = UpdateEventSchema.safeParse(parsed);
+            return normalized.success ? normalized.data : null;
+        };
+        try {
+            while (!signal?.aborted) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                while (true) {
+                    const newlineIndex = buffer.indexOf('\n');
+                    if (newlineIndex < 0)
+                        break;
+                    let line = buffer.slice(0, newlineIndex);
+                    buffer = buffer.slice(newlineIndex + 1);
+                    if (line.endsWith('\r')) {
+                        line = line.slice(0, -1);
+                    }
+                    if (line.length === 0) {
+                        const update = flushEvent();
+                        if (update) {
+                            yield update;
+                        }
+                        continue;
+                    }
+                    if (line.startsWith(':'))
+                        continue;
+                    const separator = line.indexOf(':');
+                    const field = separator >= 0 ? line.slice(0, separator) : line;
+                    const rawValue = separator >= 0 ? line.slice(separator + 1) : '';
+                    const valueText = rawValue.startsWith(' ') ? rawValue.slice(1) : rawValue;
+                    if (field === 'event') {
+                        eventName = valueText;
+                        continue;
+                    }
+                    if (field === 'data') {
+                        dataLines.push(valueText);
+                    }
+                }
+            }
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    async issueToken() {
+        const response = await fetch(`${this.baseUrl}/updates/token`, {
+            method: 'POST',
+            headers: buildHeaders(this.apiKey, 'application/json'),
+        });
+        if (!response.ok) {
+            const details = parseErrorDetails(await response.text().catch(() => ''));
+            throw new Error(`Create updates token: ${details.message}`);
+        }
+        const payload = await parseJsonResponse(response, 'Create updates token');
+        return payload.token;
+    }
+}

package/dist/updates/index.d.ts

@@ -0,0 +1 @@
+export * from './client.js';

package/dist/updates/index.js

@@ -0,0 +1 @@
+export * from './client.js';

package/dist/utils/http.d.ts

@@ -0,0 +1,39 @@
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const LONG_TIMEOUT_MS = 120000;
+/**
+ * Safely parse JSON response from a fetch Response.
+ * Throws a descriptive error if parsing fails.
+ *
+ * @param response - The fetch Response object
+ * @param context - Context string for error messages (e.g., "Create session", "RPC browser.newPage")
+ * @returns Parsed JSON data
+ * @throws Error if JSON parsing fails
+ */
+export declare function parseJsonResponse<T>(response: Response, context: string): Promise<T>;
+/**
+ * Extract a readable error message from an HTTP response body.
+ * Supports plain text and common JSON payload shapes ({ error }, { message }).
+ */
+export interface ParsedHttpError {
+    message: string;
+    code?: string;
+}
+/**
+ * Parse a server error body into a normalized message + optional machine code.
+ */
+export declare function parseErrorDetails(bodyText: string): ParsedHttpError;
+/**
+ * Backward-compatible helper for call sites that only need the message text.
+ */
+export declare function parseErrorMessage(bodyText: string): string;
+/**
+ * Fetch with automatic timeout using AbortController.
+ * Throws a descriptive error if the request times out.
+ *
+ * @param url - The URL to fetch
+ * @param options - Standard fetch options (headers, method, body, etc.)
+ * @param timeoutMs - Timeout in milliseconds (default: DEFAULT_TIMEOUT_MS)
+ * @returns The fetch Response object
+ * @throws Error if request times out or fails
+ */
+export declare function fetchWithTimeout(url: string, options?: RequestInit, timeoutMs?: number): Promise<Response>;