@bctrl/sdk 1.0.1

package/dist/utils/http.js

@@ -0,0 +1,88 @@
+// ============================================================================
+// HTTP Utilities - Shared utilities for HTTP requests
+// ============================================================================
+import { TimeoutError } from '../errors.js';
+import * as telemetry from '../telemetry.js';
+// Default timeout for HTTP requests (30 seconds for normal, 120 seconds for long operations)
+export const DEFAULT_TIMEOUT_MS = 30000;
+export 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 async function parseJsonResponse(response, context) {
+    try {
+        return (await response.json());
+    }
+    catch (err) {
+        throw new Error(`${context}: Failed to parse response as JSON - ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Parse a server error body into a normalized message + optional machine code.
+ */
+export function parseErrorDetails(bodyText) {
+    const text = bodyText.trim();
+    if (!text)
+        return { message: 'Unknown error' };
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'string' && parsed.trim())
+            return { message: parsed.trim() };
+        if (parsed && typeof parsed === 'object') {
+            const record = parsed;
+            const message = (typeof record.error === 'string' && record.error.trim()) ||
+                (typeof record.message === 'string' && record.message.trim()) ||
+                text;
+            const code = typeof record.code === 'string' && record.code.trim() ? record.code.trim() : undefined;
+            return { message, code };
+        }
+    }
+    catch {
+        // Fall through to raw text if it's not JSON
+    }
+    return { message: text };
+}
+/**
+ * Backward-compatible helper for call sites that only need the message text.
+ */
+export function parseErrorMessage(bodyText) {
+    return parseErrorDetails(bodyText).message;
+}
+/**
+ * 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 async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+        return response;
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            const timeoutErr = new TimeoutError(`Request timed out after ${timeoutMs}ms`, { timeoutMs });
+            telemetry.captureError(timeoutErr, { url, timeoutMs });
+            throw timeoutErr;
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './http.js';
+export * from './schema.js';
+export * from './logger.js';
+export * from './url.js';

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export * from './http.js';
+export * from './schema.js';
+export * from './logger.js';
+export * from './url.js';

package/dist/utils/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Log levels for the SDK logger.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Log handler function type.
+ */
+export type LogHandler = (level: LogLevel, message: string, ...args: unknown[]) => void;
+/**
+ * SDK Logger - call methods directly or configure via setLogLevel/setLogHandler.
+ */
+export declare const logger: {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    /**
+     * Set the minimum log level.
+     * Levels: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+     */
+    setLevel: (level: LogLevel) => void;
+    /**
+     * Set a custom log handler.
+     * Useful for integrating with your application's logging system.
+     */
+    setHandler: (handler: LogHandler) => void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,74 @@
+// ============================================================================
+// SDK Logger - Lightweight logging for debugging
+// ============================================================================
+/**
+ * Default log handler that uses console methods.
+ */
+const defaultHandler = (level, message, ...args) => {
+    if (level === 'silent')
+        return;
+    const prefix = `[bctrl-sdk]`;
+    switch (level) {
+        case 'debug':
+            console.debug(prefix, message, ...args);
+            break;
+        case 'info':
+            console.info(prefix, message, ...args);
+            break;
+        case 'warn':
+            console.warn(prefix, message, ...args);
+            break;
+        case 'error':
+            console.error(prefix, message, ...args);
+            break;
+    }
+};
+const config = {
+    level: process.env.BCTRL_LOG_LEVEL || 'warn',
+    handler: defaultHandler,
+};
+const levelOrder = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+function shouldLog(level) {
+    return levelOrder[level] >= levelOrder[config.level];
+}
+/**
+ * SDK Logger - call methods directly or configure via setLogLevel/setLogHandler.
+ */
+export const logger = {
+    debug: (message, ...args) => {
+        if (shouldLog('debug'))
+            config.handler('debug', message, ...args);
+    },
+    info: (message, ...args) => {
+        if (shouldLog('info'))
+            config.handler('info', message, ...args);
+    },
+    warn: (message, ...args) => {
+        if (shouldLog('warn'))
+            config.handler('warn', message, ...args);
+    },
+    error: (message, ...args) => {
+        if (shouldLog('error'))
+            config.handler('error', message, ...args);
+    },
+    /**
+     * Set the minimum log level.
+     * Levels: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+     */
+    setLevel: (level) => {
+        config.level = level;
+    },
+    /**
+     * Set a custom log handler.
+     * Useful for integrating with your application's logging system.
+     */
+    setHandler: (handler) => {
+        config.handler = handler;
+    },
+};

package/dist/utils/schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Schema utilities for converting Zod schemas to JSON Schema.
+ * Allows SDK users to pass Zod schemas directly, which are converted
+ * to JSON Schema for transmission over HTTP.
+ */
+import type { ZodType } from 'zod';
+/**
+ * Check if a value is a Zod schema.
+ * Zod 4 schemas have _zod property and toJSONSchema method.
+ */
+export declare function isZodSchema(value: unknown): value is ZodType;
+/**
+ * Convert a schema (Zod or JSON Schema) to JSON Schema format.
+ * If already a JSON Schema object, returns as-is.
+ * If a Zod schema, converts using Zod 4's native toJSONSchema().
+ */
+export declare function toJsonSchema(schema: unknown): Record<string, unknown>;

package/dist/utils/schema.js

@@ -0,0 +1,31 @@
+/**
+ * Schema utilities for converting Zod schemas to JSON Schema.
+ * Allows SDK users to pass Zod schemas directly, which are converted
+ * to JSON Schema for transmission over HTTP.
+ */
+/**
+ * Check if a value is a Zod schema.
+ * Zod 4 schemas have _zod property and toJSONSchema method.
+ */
+export function isZodSchema(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '_zod' in value &&
+        typeof value.toJSONSchema === 'function');
+}
+/**
+ * Convert a schema (Zod or JSON Schema) to JSON Schema format.
+ * If already a JSON Schema object, returns as-is.
+ * If a Zod schema, converts using Zod 4's native toJSONSchema().
+ */
+export function toJsonSchema(schema) {
+    if (isZodSchema(schema)) {
+        // Use Zod 4's native toJSONSchema method
+        const result = schema.toJSONSchema();
+        // Remove $schema wrapper if present
+        const { $schema, ...jsonSchema } = result;
+        return jsonSchema;
+    }
+    // Assume it's already a JSON Schema object
+    return schema;
+}

package/dist/utils/url.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Remove a single trailing slash from a URL-like string.
+ * Preserves previous behavior of `.replace(/\/$/, '')`.
+ */
+export declare function stripTrailingSlash(value: string): string;

package/dist/utils/url.js

@@ -0,0 +1,7 @@
+/**
+ * Remove a single trailing slash from a URL-like string.
+ * Preserves previous behavior of `.replace(/\/$/, '')`.
+ */
+export function stripTrailingSlash(value) {
+    return value.endsWith('/') ? value.slice(0, -1) : value;
+}

package/dist/vault/client.d.ts

@@ -0,0 +1,43 @@
+import type { VaultCredential, VaultCredentialInput, VaultCredentialMeta } from '../contracts/vault.js';
+type VaultListKeyOptions = {
+    prefix?: string;
+};
+type VaultListMetaOptions = {
+    meta: true;
+    prefix?: string;
+    origin?: string;
+    hasTotp?: boolean;
+    limit?: number;
+};
+export declare class VaultClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly sessionId?;
+    constructor(baseUrl: string, apiKey?: string | undefined, sessionId?: string | undefined);
+    private headers;
+    /**
+     * Get a credential from the vault.
+     * Returns null if not found.
+     */
+    get(key: string): Promise<VaultCredential | null>;
+    /**
+     * Set (create/update) a credential in the vault.
+     */
+    set(key: string, credential: VaultCredentialInput): Promise<void>;
+    /**
+     * Delete a credential from the vault.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List credential keys with optional prefix.
+     */
+    list(): Promise<string[]>;
+    list(prefix: string): Promise<string[]>;
+    list(options: VaultListKeyOptions): Promise<string[]>;
+    list(options: VaultListMetaOptions): Promise<VaultCredentialMeta[]>;
+    /**
+     * Get current TOTP code for a credential.
+     */
+    totp(key: string): Promise<string>;
+}
+export {};

package/dist/vault/client.js

@@ -0,0 +1,123 @@
+/**
+ * VaultClient — SDK client for vault credential management.
+ *
+ * Thin HTTP client that mirrors the control plane vault API.
+ * Same pattern as StorageClient.
+ */
+import { fetchWithTimeout, parseJsonResponse } from '../utils/http.js';
+import { SDK_VERSION } from '../version.js';
+// ============================================================================
+// VaultClient
+// ============================================================================
+export class VaultClient {
+    baseUrl;
+    apiKey;
+    sessionId;
+    constructor(baseUrl, apiKey, sessionId) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.sessionId = sessionId;
+    }
+    headers(withJsonBody = false) {
+        const h = {
+            'x-sdk-version': SDK_VERSION,
+        };
+        if (withJsonBody)
+            h['Content-Type'] = 'application/json';
+        if (this.apiKey)
+            h['Authorization'] = `Bearer ${this.apiKey}`;
+        if (this.sessionId)
+            h['x-session-id'] = this.sessionId;
+        return h;
+    }
+    /**
+     * Get a credential from the vault.
+     * Returns null if not found.
+     */
+    async get(key) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/vault/${encodeVaultKey(key)}`, {
+            headers: this.headers(),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Vault get failed: ${await res.text()}`);
+        return parseJsonResponse(res, 'Vault get');
+    }
+    /**
+     * Set (create/update) a credential in the vault.
+     */
+    async set(key, credential) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/vault/${encodeVaultKey(key)}`, {
+            method: 'PUT',
+            headers: this.headers(true),
+            body: JSON.stringify(credential),
+        });
+        if (!res.ok)
+            throw new Error(`Vault set failed: ${await res.text()}`);
+    }
+    /**
+     * Delete a credential from the vault.
+     */
+    async delete(key) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/vault/${encodeVaultKey(key)}`, {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Vault delete failed: ${await res.text()}`);
+    }
+    async list(input) {
+        const params = new URLSearchParams();
+        if (typeof input === 'string') {
+            params.set('prefix', input);
+        }
+        else if (input) {
+            if ('meta' in input && input.meta === true) {
+                params.set('meta', '1');
+                if (input.prefix)
+                    params.set('prefix', input.prefix);
+                if (input.origin)
+                    params.set('origin', input.origin);
+                if (typeof input.hasTotp === 'boolean')
+                    params.set('hasTotp', String(input.hasTotp));
+                if (typeof input.limit === 'number')
+                    params.set('limit', String(input.limit));
+            }
+            else if (input.prefix) {
+                params.set('prefix', input.prefix);
+            }
+        }
+        const query = params.toString();
+        const suffix = query ? `?${query}` : '';
+        const res = await fetchWithTimeout(`${this.baseUrl}/vault${suffix}`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Vault list failed: ${await res.text()}`);
+        if (typeof input === 'object' && input && 'meta' in input && input.meta === true) {
+            const data = await parseJsonResponse(res, 'Vault list (metadata)');
+            return data.items;
+        }
+        const data = await parseJsonResponse(res, 'Vault list');
+        return data.keys;
+    }
+    /**
+     * Get current TOTP code for a credential.
+     */
+    async totp(key) {
+        const res = await fetchWithTimeout(`${this.baseUrl}/vault/${encodeVaultKey(key)}/totp`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Vault TOTP failed: ${await res.text()}`);
+        const data = await parseJsonResponse(res, 'Vault TOTP');
+        return data.code;
+    }
+}
+/**
+ * Encode each segment of a slash-separated vault key.
+ */
+function encodeVaultKey(key) {
+    return key.split('/').map(encodeURIComponent).join('/');
+}

package/dist/vault/index.d.ts

@@ -0,0 +1 @@
+export { VaultClient } from './client.js';

package/dist/vault/index.js

@@ -0,0 +1 @@
+export { VaultClient } from './client.js';

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const SDK_VERSION = pkg.version;