cloudcruise 1.0.1 → 1.2.0

package/dist/CloudCruise.d.ts

@@ -1,4 +1,5 @@
 import { VaultClient } from './vault/VaultClient.js';
+import { SecretProvidersClient } from './secretProviders/SecretProvidersClient.js';
 import { WorkflowsClient } from './workflows/WorkflowsClient.js';
 import { RunsClient } from './runs/RunsClient.js';
 import { WebhookClient } from './webhook/WebhookClient.js';
@@ -6,7 +7,7 @@ export interface CloudCruiseParams {
     apiKey?: string;
     /**
      * CloudCruise API base URL. Authenticated requests are restricted to the
-     * production CloudCruise API origin.
+     * production CloudCruise API origin or the staging API origin.
      */
     baseUrl?: string;
     encryptionKey?: string;
@@ -16,6 +17,7 @@ export declare class CloudCruise {
     private readonly baseUrl;
     private readonly encryptionKey;
     readonly vault: VaultClient;
+    readonly secretProviders: SecretProvidersClient;
     readonly workflows: WorkflowsClient;
     readonly runs: RunsClient;
     readonly webhook: WebhookClient;

package/dist/CloudCruise.js

@@ -1,10 +1,13 @@
 import { getEnv } from './utils/env.js';
 import { VaultClient } from './vault/VaultClient.js';
+import { SecretProvidersClient } from './secretProviders/SecretProvidersClient.js';
 import { WorkflowsClient } from './workflows/WorkflowsClient.js';
 import { RunsClient } from './runs/RunsClient.js';
 import { WebhookClient } from './webhook/WebhookClient.js';
 import { ConnectionManager } from './utils/connectionManager.js';
 const DEFAULT_BASE_URL = 'https://api.cloudcruise.com';
+const STAGING_BASE_URL = 'https://staging-api.cloudcruise.app';
+const ALLOWED_BASE_URLS = new Set([DEFAULT_BASE_URL, STAGING_BASE_URL]);
 const DEFAULT_API_HOST = new URL(DEFAULT_BASE_URL).host.toLowerCase();
 function normalizeBaseUrl(baseUrl) {
     let url;
@@ -27,9 +30,9 @@ function assertBaseUrlAllowed(baseUrl) {
     if (host === DEFAULT_API_HOST && url.protocol !== 'https:') {
         throw new Error(`Refusing to send CloudCruise API key to "${baseUrl}". The default CloudCruise API host requires https:.`);
     }
-    if (baseUrl !== DEFAULT_BASE_URL) {
+    if (!ALLOWED_BASE_URLS.has(baseUrl)) {
         throw new Error(`Refusing to send CloudCruise API key to unapproved baseUrl "${baseUrl}". ` +
-            `Authenticated requests are restricted to ${DEFAULT_BASE_URL}.`);
+            `Authenticated requests are restricted to: ${Array.from(ALLOWED_BASE_URLS).join(", ")}.`);
     }
 }
 export class CloudCruise {
@@ -37,6 +40,7 @@ export class CloudCruise {
     baseUrl;
     encryptionKey;
     vault;
+    secretProviders;
     workflows;
     runs;
     webhook;
@@ -59,6 +63,7 @@ export class CloudCruise {
         // Initialize namespace clients
         this.connectionManager = new ConnectionManager(this.baseUrl, this.apiKey);
         this.vault = new VaultClient(this.makeRequest.bind(this), this.encryptionKey);
+        this.secretProviders = new SecretProvidersClient(this.makeRequest.bind(this));
         this.workflows = new WorkflowsClient(this.makeRequest.bind(this));
         this.runs = new RunsClient(this.connectionManager, this.makeRequest.bind(this), this.workflows);
         this.webhook = new WebhookClient();

package/dist/events/types.d.ts

@@ -17,7 +17,8 @@ export declare enum EventType {
     InteractionWaiting = "interaction.waiting",
     InteractionFinished = "interaction.finished",
     InteractionFailed = "interaction.failed",
-    AgentErrorAnalysis = "agent.error_analysis"
+    AgentErrorAnalysis = "agent.error_analysis",
+    ExecutionInputRequired = "execution.input_required"
 }
 export interface ExecutionQueuedPayload {
     session_id: string;
@@ -61,6 +62,37 @@ export interface AgentErrorAnalysisPayload {
     ai_analysis?: string;
     root_cause_analysis?: string;
     error_category?: string;
+    phase?: "modal_decision_dispatched" | "popup_dismiss_verified" | string;
+    session_id?: string;
+    modal_action?: string;
+    modal_action_label?: string;
+    response_time_ms?: number;
+    outcome?: "success" | "failure";
+    host?: string;
+    popup_signature?: string;
+}
+export interface AvailableAction {
+    id: string;
+    label: string;
+}
+export interface PopupRetry {
+    attempt: number;
+    max_attempts: number;
+}
+export interface PopupContext {
+    error_description: string;
+    error_sub_type?: string;
+    full_url?: string;
+    available_actions: AvailableAction[];
+    retry: PopupRetry;
+}
+export type InputRequiredReason = "input_required" | "incorrect_form_input" | "multiple_matching_results" | "non_dismissible_popup";
+export interface ExecutionInputRequiredPayload {
+    session_id: string;
+    input_variables: Record<string, any>;
+    screenshot_url: string | null;
+    reason?: InputRequiredReason;
+    popup_context?: PopupContext;
 }
 export interface ExecutionRequeuedPayload {
     session_id: string;
@@ -132,6 +164,7 @@ export type EventPayloadMap = {
     [EventType.VideoUploaded]: never;
     [EventType.ExecutionPause]: never;
     [EventType.InteractionFailed]: never;
+    [EventType.ExecutionInputRequired]: ExecutionInputRequiredPayload;
 };
 export type WebhookMessage<E extends EventType = EventType> = {
     event: E;

package/dist/events/types.js

@@ -19,4 +19,5 @@ export var EventType;
     EventType["InteractionFinished"] = "interaction.finished";
     EventType["InteractionFailed"] = "interaction.failed";
     EventType["AgentErrorAnalysis"] = "agent.error_analysis";
+    EventType["ExecutionInputRequired"] = "execution.input_required";
 })(EventType || (EventType = {}));

package/dist/index.d.ts

@@ -5,14 +5,15 @@
 export { CloudCruise } from './CloudCruise.js';
 export type { CloudCruiseParams } from './CloudCruise.js';
 export { VaultClient } from './vault/VaultClient.js';
+export { SecretProvidersClient } from './secretProviders/SecretProvidersClient.js';
 export { WorkflowsClient } from './workflows/WorkflowsClient.js';
 export { RunsClient } from './runs/RunsClient.js';
 export { WebhookClient } from './webhook/WebhookClient.js';
-export type { VaultEntry, GetVaultEntriesFilters, ProxyConfig, VaultPostPutHeadersInBody } from './vault/types.js';
+export type { VaultEntry, GetVaultEntriesFilters, ProxyConfig, VaultPostPutHeadersInBody, SecretProvider, SecretProviderItem, SecretProviderType } from './vault/types.js';
 export type { Workflow, WorkflowInputSchema, WorkflowMetadata } from './workflows/types.js';
 export type { DryRun, Metadata, RunSpecificWebhook, PayloadWebhook, StartRunRequest, StartRunResponse, UserInteractionData, VideoUrl, SignedFileUrl, SignedScreenshotUrl, RunError, WorkflowError, RunResult, GetRunResult, WebhookEvent, WebhookReplayResponse, RunHandle, RunStreamOptions, SseEventName, SseMessage, RunEventEnvelope, RunHandleEventMap } from './runs/types.js';
 export { EventType } from './events/types.js';
-export type { WebhookMessage, RunEventMessage } from './events/types.js';
+export type { WebhookMessage, RunEventMessage, AvailableAction, PopupRetry, PopupContext, InputRequiredReason, ExecutionInputRequiredPayload, AgentErrorAnalysisPayload } from './events/types.js';
 export type { WebhookVerificationOptions } from './webhook/types.js';
 export { VerificationError } from './webhook/types.js';
 export { InputValidationError } from './workflows/types.js';

package/dist/index.js

@@ -4,6 +4,7 @@
  */
 export { CloudCruise } from './CloudCruise.js';
 export { VaultClient } from './vault/VaultClient.js';
+export { SecretProvidersClient } from './secretProviders/SecretProvidersClient.js';
 export { WorkflowsClient } from './workflows/WorkflowsClient.js';
 export { RunsClient } from './runs/RunsClient.js';
 export { WebhookClient } from './webhook/WebhookClient.js';

package/dist/runs/RunsClient.d.ts

@@ -1,4 +1,5 @@
 import type { StartRunRequest, UserInteractionData, GetRunResult, WebhookReplayResponse, RunHandle, RunStreamOptions } from './types.js';
+import type { PopupContext, ExecutionInputRequiredPayload } from '../events/types.js';
 import { ConnectionManager } from '../utils/connectionManager.js';
 export declare class RunsClient {
     private readonly makeRequest;
@@ -22,6 +23,64 @@ export declare class RunsClient {
      * @param data - User input data as key-value pairs
      */
     submitUserInteraction(sessionId: string, data: UserInteractionData): Promise<void>;
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "non_dismissible_popup" by picking one of the CTA buttons surfaced in
+     * popup_context.available_actions. The backend dispatches a synthetic
+     * click on the chosen button and resumes the workflow.
+     *
+     * Only valid while the session is waiting for input. The backing endpoint
+     * returns 400 if the wait already expired (the workspace setting
+     * input_required_timeout_seconds, default 15s, max 300s).
+     *
+     * @param sessionId - The session waiting for input.
+     * @param actionId - One of the ids in popup_context.available_actions.
+     */
+    submitModalAction(sessionId: string, actionId: string): Promise<void>;
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "input_required", "incorrect_form_input", or "multiple_matching_results"
+     * by supplying the corrected/required input variables. Backend resumes from
+     * the appropriate recovery node with the new values substituted in.
+     *
+     * Mutually exclusive with submitModalAction at the endpoint level.
+     *
+     * @param sessionId - The session waiting for input.
+     * @param inputVariables - Mapping of variable name to new value.
+     */
+    submitInputVariables(sessionId: string, inputVariables: Record<string, any>): Promise<void>;
+    /**
+     * Registers a listener that auto-responds ONLY to non-dismissible modal
+     * input_required events (reason === "non_dismissible_popup"). The decider
+     * receives the popup_context and must return one of the action ids in
+     * popup_context.available_actions.
+     *
+     * The SDK never picks an action on its own. The customer's decider IS the
+     * decision point. If decider throws, the listener swallows it and skips
+     * submission; the backend's input wait will time out naturally.
+     *
+     * Other input_required reasons (incorrect_form_input, etc.) are ignored
+     * here and should be routed to onInputVariablesRequired.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onPopupDecisionRequired(handle: RunHandle, decider: (ctx: PopupContext) => string | Promise<string>, onError?: (err: unknown) => void, options?: {
+        verbose?: boolean;
+    }): () => void;
+    /**
+     * Registers a listener that auto-responds ONLY to workflow-variable
+     * input_required events (reason in {"input_required",
+     * "incorrect_form_input", "multiple_matching_results"}). The decider
+     * receives the full payload and must return the input_variables dict.
+     *
+     * Counterpart to onPopupDecisionRequired. Modal events
+     * (reason === "non_dismissible_popup") are routed there and ignored here.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onInputVariablesRequired(handle: RunHandle, decider: (payload: ExecutionInputRequiredPayload) => Record<string, any> | Promise<Record<string, any>>, onError?: (err: unknown) => void, options?: {
+        verbose?: boolean;
+    }): () => void;
     /**
      * Retrieves comprehensive results and execution details for a specific run
      * @param sessionId - The unique identifier for the workflow execution session

package/dist/runs/RunsClient.js

@@ -1,6 +1,37 @@
 import { EventType } from '../events/types.js';
 import { AsyncEventQueue } from '../utils/asyncQueue.js';
 import { SimpleEventEmitter } from '../utils/events.js';
+/**
+ * Default error reporter for the recovery helpers. Writes to console.error
+ * so submission failures surface in customer logs even if no onError
+ * callback is provided. The runtime SimpleEventEmitter ignores async-handler
+ * returns, so without this default a rejection from /new_input_variables
+ * would become a silent unhandled rejection.
+ */
+function defaultRecoverySubmitErrorLog(operation) {
+    return (err) => {
+        try {
+            const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+            console.error(`[CloudCruise SDK] ${operation} failed during recovery: ${msg}`);
+        }
+        catch {
+            // never throw from the error reporter
+        }
+    };
+}
+/**
+ * Helper for `verbose: true` mode on the recovery helpers. Writes a single
+ * line to console.error so customers can watch the recovery loop without
+ * instrumenting their own decider.
+ */
+function verboseLog(operation, message) {
+    try {
+        console.error(`[CloudCruise SDK verbose] ${operation}: ${message}`);
+    }
+    catch {
+        // never throw
+    }
+}
 export class RunsClient {
     makeRequest;
     workflows;
@@ -171,6 +202,175 @@ export class RunsClient {
         const path = `/run/${sessionId}/user_interaction`;
         await this.makeRequest('POST', path, data);
     }
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "non_dismissible_popup" by picking one of the CTA buttons surfaced in
+     * popup_context.available_actions. The backend dispatches a synthetic
+     * click on the chosen button and resumes the workflow.
+     *
+     * Only valid while the session is waiting for input. The backing endpoint
+     * returns 400 if the wait already expired (the workspace setting
+     * input_required_timeout_seconds, default 15s, max 300s).
+     *
+     * @param sessionId - The session waiting for input.
+     * @param actionId - One of the ids in popup_context.available_actions.
+     */
+    async submitModalAction(sessionId, actionId) {
+        const path = `/run/${sessionId}/new_input_variables`;
+        await this.makeRequest('POST', path, { modal_action: actionId });
+    }
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "input_required", "incorrect_form_input", or "multiple_matching_results"
+     * by supplying the corrected/required input variables. Backend resumes from
+     * the appropriate recovery node with the new values substituted in.
+     *
+     * Mutually exclusive with submitModalAction at the endpoint level.
+     *
+     * @param sessionId - The session waiting for input.
+     * @param inputVariables - Mapping of variable name to new value.
+     */
+    async submitInputVariables(sessionId, inputVariables) {
+        const path = `/run/${sessionId}/new_input_variables`;
+        await this.makeRequest('POST', path, { input_variables: inputVariables });
+    }
+    /**
+     * Registers a listener that auto-responds ONLY to non-dismissible modal
+     * input_required events (reason === "non_dismissible_popup"). The decider
+     * receives the popup_context and must return one of the action ids in
+     * popup_context.available_actions.
+     *
+     * The SDK never picks an action on its own. The customer's decider IS the
+     * decision point. If decider throws, the listener swallows it and skips
+     * submission; the backend's input wait will time out naturally.
+     *
+     * Other input_required reasons (incorrect_form_input, etc.) are ignored
+     * here and should be routed to onInputVariablesRequired.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onPopupDecisionRequired(handle, decider, onError, options) {
+        const verbose = options?.verbose === true;
+        const reportError = (err) => {
+            const reporter = onError ?? defaultRecoverySubmitErrorLog('submitModalAction');
+            try {
+                reporter(err);
+            }
+            catch {
+                // defense: a buggy onError must not crash the event loop
+            }
+        };
+        if (verbose)
+            verboseLog('onPopupDecisionRequired', 'listener registered');
+        const listener = async (event) => {
+            const payload = (event?.data?.payload ?? event?.payload);
+            if (!payload || payload.reason !== 'non_dismissible_popup' || !payload.popup_context) {
+                if (verbose) {
+                    verboseLog('onPopupDecisionRequired', `skipping reason=${payload?.reason ?? 'undefined'}`);
+                }
+                return;
+            }
+            if (verbose) {
+                const attempt = payload.popup_context.retry?.attempt;
+                const actions = payload.popup_context.available_actions?.map((a) => a.id) ?? [];
+                verboseLog('onPopupDecisionRequired', `event received attempt=${attempt} actions=${JSON.stringify(actions)}`);
+            }
+            let actionId;
+            try {
+                actionId = await decider(payload.popup_context);
+            }
+            catch (e) {
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `decider raised: ${e}`);
+                return;
+            }
+            if (typeof actionId !== 'string' || actionId.length === 0) {
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `decider returned non-string/empty (${JSON.stringify(actionId)}); skipping`);
+                return;
+            }
+            const sid = payload.session_id || handle.sessionId;
+            if (verbose)
+                verboseLog('onPopupDecisionRequired', `submitting modal_action=${JSON.stringify(actionId)} for session=${sid}`);
+            try {
+                await this.submitModalAction(sid, actionId);
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `submit ok for action=${JSON.stringify(actionId)}`);
+            }
+            catch (err) {
+                reportError(err);
+            }
+        };
+        const unsubscribe = handle.on(EventType.ExecutionInputRequired, listener);
+        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
+    }
+    /**
+     * Registers a listener that auto-responds ONLY to workflow-variable
+     * input_required events (reason in {"input_required",
+     * "incorrect_form_input", "multiple_matching_results"}). The decider
+     * receives the full payload and must return the input_variables dict.
+     *
+     * Counterpart to onPopupDecisionRequired. Modal events
+     * (reason === "non_dismissible_popup") are routed there and ignored here.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onInputVariablesRequired(handle, decider, onError, options) {
+        const verbose = options?.verbose === true;
+        const VARIABLE_REASONS = new Set([
+            'input_required',
+            'incorrect_form_input',
+            'multiple_matching_results',
+        ]);
+        const reportError = (err) => {
+            const reporter = onError ?? defaultRecoverySubmitErrorLog('submitInputVariables');
+            try {
+                reporter(err);
+            }
+            catch {
+                // defense
+            }
+        };
+        if (verbose)
+            verboseLog('onInputVariablesRequired', 'listener registered');
+        const listener = async (event) => {
+            const payload = (event?.data?.payload ?? event?.payload);
+            if (!payload || !payload.reason || !VARIABLE_REASONS.has(payload.reason)) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `skipping reason=${payload?.reason ?? 'undefined'}`);
+                return;
+            }
+            if (verbose)
+                verboseLog('onInputVariablesRequired', `event received reason=${payload.reason}`);
+            let inputVars;
+            try {
+                inputVars = await decider(payload);
+            }
+            catch (e) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `decider raised: ${e}`);
+                return;
+            }
+            if (!inputVars || typeof inputVars !== 'object' || Array.isArray(inputVars)) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `decider returned non-object (${Array.isArray(inputVars) ? 'array' : typeof inputVars}); skipping`);
+                return;
+            }
+            const sid = payload.session_id || handle.sessionId;
+            if (verbose)
+                verboseLog('onInputVariablesRequired', `submitting input_variables keys=${JSON.stringify(Object.keys(inputVars))} for session=${sid}`);
+            try {
+                await this.submitInputVariables(sid, inputVars);
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', 'submit ok');
+            }
+            catch (err) {
+                reportError(err);
+            }
+        };
+        const unsubscribe = handle.on(EventType.ExecutionInputRequired, listener);
+        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
+    }
     /**
      * Retrieves comprehensive results and execution details for a specific run
      * @param sessionId - The unique identifier for the workflow execution session

package/dist/secretProviders/SecretProvidersClient.d.ts

@@ -0,0 +1,7 @@
+import type { SecretProvider, SecretProviderItem } from '../vault/types.js';
+export declare class SecretProvidersClient {
+    private readonly makeRequest;
+    constructor(makeRequest: <T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: any) => Promise<T>);
+    list(): Promise<SecretProvider[]>;
+    listItems(secretProviderId: string): Promise<SecretProviderItem[]>;
+}

package/dist/secretProviders/SecretProvidersClient.js

@@ -0,0 +1,17 @@
+export class SecretProvidersClient {
+    makeRequest;
+    constructor(makeRequest) {
+        this.makeRequest = makeRequest;
+    }
+    async list() {
+        const response = await this.makeRequest('GET', '/secret-providers');
+        return Array.isArray(response) ? response : [response];
+    }
+    async listItems(secretProviderId) {
+        if (!secretProviderId) {
+            throw new Error('secretProviderId is required');
+        }
+        const response = await this.makeRequest('GET', `/secret-providers/${encodeURIComponent(secretProviderId)}/items`);
+        return Array.isArray(response) ? response : [response];
+    }
+}

package/dist/vault/VaultClient.d.ts

@@ -32,14 +32,10 @@ export declare class VaultClient {
      * Updates an existing vault entry
      * @param updates - Vault entry updates including required fields
      * @param updates.permissioned_user_id - Required: User identifier for the vault entry
-     * @param updates.user_name - Required: Username or email
-     * @param updates.password - Required: User password
      * @param updates.domain - Required: Target domain for the credentials
      */
     update(updates: Partial<VaultEntry> & {
         permissioned_user_id: string;
-        user_name: string;
-        password: string;
         domain: string;
     }): Promise<VaultEntry>;
     /**

package/dist/vault/VaultClient.js

@@ -1,4 +1,28 @@
 import { encryptSensitiveFields, decryptSensitiveFields } from './utils.js';
+function validateProviderPayload(entry) {
+    const hasProviderId = entry.secret_provider_id !== undefined && entry.secret_provider_id !== null;
+    const hasSecretRef = entry.secret_ref !== undefined && entry.secret_ref !== null;
+    if (hasProviderId !== hasSecretRef) {
+        throw new Error('secret_provider_id and secret_ref must be provided together');
+    }
+    if (entry.secret_cache_ttl_seconds !== undefined && entry.secret_cache_ttl_seconds !== null) {
+        if (!Number.isInteger(entry.secret_cache_ttl_seconds) || entry.secret_cache_ttl_seconds < 0) {
+            throw new Error('secret_cache_ttl_seconds must be a non-negative integer');
+        }
+        if (!hasProviderId) {
+            throw new Error('secret_cache_ttl_seconds requires secret_provider_id and secret_ref');
+        }
+    }
+    if (hasProviderId) {
+        const conflicts = ['user_name', 'password', 'tfa_secret'].filter(field => entry[field] !== undefined && entry[field] !== null);
+        if (conflicts.length > 0) {
+            throw new Error(`provider-backed vault entries cannot include ${conflicts.join(', ')}`);
+        }
+    }
+}
+function isProviderBackedPayload(entry) {
+    return entry.secret_provider_id != null && entry.secret_ref != null;
+}
 export class VaultClient {
     makeRequest;
     encryptionKey;
@@ -15,6 +39,7 @@ export class VaultClient {
             permissioned_user_id,
             ...options
         };
+        validateProviderPayload(entry);
         let processedEntry = { ...entry };
         // Encrypt sensitive fields
         processedEntry = await encryptSensitiveFields(processedEntry, this.encryptionKey);
@@ -78,8 +103,6 @@ export class VaultClient {
      * Updates an existing vault entry
      * @param updates - Vault entry updates including required fields
      * @param updates.permissioned_user_id - Required: User identifier for the vault entry
-     * @param updates.user_name - Required: Username or email
-     * @param updates.password - Required: User password
      * @param updates.domain - Required: Target domain for the credentials
      */
     async update(updates) {
@@ -87,15 +110,18 @@ export class VaultClient {
         if (!updates.permissioned_user_id) {
             throw new Error('permissioned_user_id is required for vault updates');
         }
-        if (!updates.user_name) {
-            throw new Error('user_name is required for vault updates');
-        }
-        if (!updates.password) {
-            throw new Error('password is required for vault updates');
-        }
         if (!updates.domain) {
             throw new Error('domain is required for vault updates');
         }
+        validateProviderPayload(updates);
+        if (!isProviderBackedPayload(updates)) {
+            if (!updates.user_name) {
+                throw new Error('user_name is required for vault updates');
+            }
+            if (!updates.password) {
+                throw new Error('password is required for vault updates');
+            }
+        }
         let processedEntry = { ...updates };
         // Encrypt sensitive fields
         processedEntry = await encryptSensitiveFields(processedEntry, this.encryptionKey);

package/dist/vault/types.d.ts

@@ -17,6 +17,9 @@ export interface VaultEntry {
     user_id?: string;
     password?: string;
     user_name?: string;
+    secret_provider_id?: string | null;
+    secret_ref?: string | null;
+    secret_cache_ttl_seconds?: number | null;
     tfa_secret?: string;
     user_agent?: string;
     user_alias?: string;
@@ -38,6 +41,8 @@ export interface VaultEntry {
     cookie_domain_to_store?: string | null;
     proxy?: ProxyConfig;
     proxy_string?: string | null;
+    proxy_setting?: 'random' | 'static' | 'country' | 'custom' | null;
+    proxy_value?: string | null;
     headers?: VaultPostPutHeadersInBody[];
     created_at?: string | null;
     session_data_set_at?: string | null;
@@ -48,6 +53,19 @@ export interface GetVaultEntriesFilters {
     domain?: string;
     decryptCredentials?: boolean;
 }
+export type SecretProviderType = '1password';
+export interface SecretProvider {
+    id: string;
+    provider_type: SecretProviderType;
+    name: string;
+    cache_ttl_seconds?: number | null;
+}
+export interface SecretProviderItem {
+    id: string;
+    title: string;
+    ref: string;
+    vaultName?: string | null;
+}
 /**
  * The current 2FA code for a vault entry. `expires_in_seconds` is present for
  * authenticator (TOTP) codes; `received_at` is present for email codes.

package/dist/vault/utils.d.ts

@@ -18,7 +18,8 @@ export declare function encryptData(data: any, keyHex: string): Promise<string>;
 export declare function decryptData(encryptedHex: string, keyHex: string): Promise<any>;
 /**
  * Encrypts sensitive fields in a vault entry
- * Fields encrypted: user_name, password, tfa_secret (if present)
+ * Fields encrypted: user_name, password, tfa_secret (if present), and
+ * proxy_value when proxy_setting is "custom" (the bring-your-own proxy URL).
  * @param entry - Vault entry with potentially sensitive data
  * @param encryptionKey - Hex-encoded encryption key
  * @returns Entry with encrypted sensitive fields

package/dist/vault/utils.js

@@ -51,7 +51,8 @@ export async function decryptData(encryptedHex, keyHex) {
 }
 /**
  * Encrypts sensitive fields in a vault entry
- * Fields encrypted: user_name, password, tfa_secret (if present)
+ * Fields encrypted: user_name, password, tfa_secret (if present), and
+ * proxy_value when proxy_setting is "custom" (the bring-your-own proxy URL).
  * @param entry - Vault entry with potentially sensitive data
  * @param encryptionKey - Hex-encoded encryption key
  * @returns Entry with encrypted sensitive fields
@@ -67,6 +68,22 @@ export async function encryptSensitiveFields(entry, encryptionKey) {
     if (entry.tfa_secret !== undefined) {
         encryptedEntry.tfa_secret = await encryptData(entry.tfa_secret, encryptionKey);
     }
+    // proxy_value is meaningless to the backend without proxy_setting, which is
+    // also the discriminator that tells us whether to encrypt. Fail closed: a
+    // custom proxy URL (often with embedded credentials) must never be sent in
+    // plaintext because the caller forgot the mode on a partial update.
+    if (entry.proxy_value !== undefined &&
+        entry.proxy_value !== null &&
+        (entry.proxy_setting === undefined || entry.proxy_setting === null)) {
+        throw new Error("proxy_value requires proxy_setting. Pass proxy_setting: 'custom' for a " +
+            "bring-your-own proxy URL (so it is encrypted before sending), or " +
+            "'static'/'country' for a managed proxy.");
+    }
+    if (entry.proxy_setting === 'custom' &&
+        entry.proxy_value !== undefined &&
+        entry.proxy_value !== null) {
+        encryptedEntry.proxy_value = await encryptData(entry.proxy_value, encryptionKey);
+    }
     return encryptedEntry;
 }
 /**
@@ -95,5 +112,11 @@ export async function decryptSensitiveFields(entry, encryptionKey) {
         }
         catch { }
     }
+    if (entry.proxy_setting === 'custom' && typeof entry.proxy_value === 'string') {
+        try {
+            decryptedEntry.proxy_value = await decryptData(entry.proxy_value, encryptionKey);
+        }
+        catch { }
+    }
     return decryptedEntry;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudcruise",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {