cloudcruise 1.2.1 → 1.4.0

package/dist/CloudCruise.js

@@ -5,6 +5,8 @@ import { WorkflowsClient } from './workflows/WorkflowsClient.js';
 import { RunsClient } from './runs/RunsClient.js';
 import { WebhookClient } from './webhook/WebhookClient.js';
 import { ConnectionManager } from './utils/connectionManager.js';
+import { inputValidationErrorFromResponse } from './workflows/validation.js';
+import { clientIdentityHeaders } from './clientIdentity.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]);
@@ -75,6 +77,7 @@ export class CloudCruise {
     async makeRequest(method, path, body) {
         const url = `${this.baseUrl}${path}`;
         const headers = {
+            ...clientIdentityHeaders(),
             'Content-Type': 'application/json',
             'cc-key': this.apiKey
         };
@@ -87,13 +90,25 @@ export class CloudCruise {
             if (!response.ok) {
                 const errorText = await response.text();
                 let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+                let errorJson;
                 try {
-                    const errorJson = JSON.parse(errorText);
-                    errorMessage = errorJson.message || errorJson.error || errorMessage;
+                    errorJson = JSON.parse(errorText);
                 }
                 catch {
                     // Use HTTP status if we can't parse error response
                 }
+                if (typeof errorJson === 'object' &&
+                    errorJson !== null &&
+                    !Array.isArray(errorJson)) {
+                    const errorBody = errorJson;
+                    const validationError = inputValidationErrorFromResponse(errorBody, body);
+                    if (validationError)
+                        throw validationError;
+                    errorMessage =
+                        (typeof errorBody.message === 'string' && errorBody.message) ||
+                            (typeof errorBody.error === 'string' && errorBody.error) ||
+                            errorMessage;
+                }
                 throw new Error(errorMessage);
             }
             const contentType = response.headers.get('content-type');

package/dist/clientIdentity.d.ts

@@ -0,0 +1 @@
+export declare function clientIdentityHeaders(): Record<string, string>;

package/dist/clientIdentity.js

@@ -0,0 +1,9 @@
+import { detectAgent } from 'std-env';
+import { SDK_VERSION } from './version.js';
+export function clientIdentityHeaders() {
+    const agent = detectAgent().name;
+    return {
+        'X-CloudCruise-Client': `sdk-js/${SDK_VERSION}`,
+        ...(agent ? { 'X-CloudCruise-Agent': agent } : {})
+    };
+}

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { WorkflowsClient } from './workflows/WorkflowsClient.js';
 export { RunsClient } from './runs/RunsClient.js';
 export { WebhookClient } from './webhook/WebhookClient.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 { Workflow, WorkflowInputSchema, WorkflowVaultCredentialSchema, WorkflowVaultSchema, WorkflowMetadata, InvalidTypeDetail, SchemaErrorDetail } 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, LiveViewConnection } from './runs/types.js';
 export { EventType } from './events/types.js';
 export type { WebhookMessage, RunEventMessage, AvailableAction, PopupRetry, PopupContext, InputRequiredReason, ExecutionInputRequiredPayload, AgentErrorAnalysisPayload } from './events/types.js';

package/dist/utils/connectionManager.js

@@ -2,6 +2,7 @@ import { openSSE } from './sse.js';
 import { SimpleEventEmitter } from './events.js';
 import { AsyncEventQueue } from './asyncQueue.js';
 import { EventType } from '../events/types.js';
+import { clientIdentityHeaders } from '../clientIdentity.js';
 function isFinalEvent(eventType) {
     return (eventType === EventType.ExecutionSuccess ||
         eventType === EventType.ExecutionFailed ||
@@ -121,6 +122,7 @@ export class ConnectionManager {
             await this.ensureClientId();
         this.connecting = true;
         const headers = {
+            ...clientIdentityHeaders(),
             'cc-key': this.apiKey
         };
         const url = `${this.baseUrl}/run/clients/${this.clientId}/events`;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "1.4.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const SDK_VERSION = '1.4.0';

package/dist/workflows/WorkflowsClient.js

@@ -1,4 +1,4 @@
-import { InputValidationError } from './types.js';
+import { validateInputSchema } from './validation.js';
 export class WorkflowsClient {
     makeRequest;
     constructor(makeRequest) {
@@ -16,7 +16,14 @@ export class WorkflowsClient {
      */
     async getWorkflowMetadata(workflowId) {
         const path = `/workflows/${workflowId}/metadata`;
-        return await this.makeRequest('GET', path);
+        const response = await this.makeRequest('GET', path);
+        if (response &&
+            typeof response === 'object' &&
+            !('input_schema' in response) &&
+            response.metadata) {
+            return response.metadata;
+        }
+        return response;
     }
     /**
      * Validates a payload against a workflow's input schema.
@@ -24,74 +31,6 @@ export class WorkflowsClient {
      */
     async validateWorkflowInput(workflowId, payload) {
         const { input_schema } = await this.getWorkflowMetadata(workflowId);
-        const schema = input_schema ?? {};
-        const properties = schema.properties ?? {};
-        const required = schema.required ?? [];
-        const disallowExtras = schema.additionalProperties === false;
-        // Check only required keys for presence and type
-        const missingRequired = required.filter((key) => payload[key] === undefined);
-        const invalidTypes = [];
-        const detectType = (v) => {
-            if (v === null)
-                return 'null';
-            if (Array.isArray(v))
-                return 'array';
-            if (typeof v === 'number')
-                return Number.isInteger(v) ? 'integer' : 'number';
-            return typeof v;
-        };
-        const allowedTypes = new Set(['array', 'boolean', 'integer', 'number', 'object', 'string', 'null']);
-        const expectedTypesOf = (def) => {
-            if (!def)
-                return [];
-            // Normalize to array-of-strings from either string | string[] | { type: string | string[] }
-            const raw = (typeof def === 'object' && !Array.isArray(def)) ? def.type : def;
-            if (!raw)
-                return [];
-            const arr = Array.isArray(raw) ? raw : [raw];
-            return arr
-                .map((t) => String(t).toLowerCase())
-                .filter((t) => allowedTypes.has(t));
-        };
-        const matches = (expected, actual) => {
-            if (expected.length === 0)
-                return true; // unknown => don't enforce
-            if (expected.includes(actual))
-                return true;
-            if (actual === 'integer' && expected.includes('number'))
-                return true;
-            return false;
-        };
-        // Validate types for:
-        // - all required keys that are present
-        // - optional keys if they exist in the payload
-        for (const [key, schemaDef] of Object.entries(properties)) {
-            if (payload[key] === undefined)
-                continue; // optional and not provided
-            const expected = expectedTypesOf(schemaDef);
-            const actual = detectType(payload[key]);
-            if (!matches(expected, actual)) {
-                const exp = expected.length ? expected : ['any'];
-                invalidTypes.push({ field: key, expected_display: exp.join(' | '), actual });
-            }
-        }
-        // If additionalProperties is false, collect unknown keys present in payload
-        const unknownKeys = disallowExtras
-            ? Object.keys(payload).filter((k) => !(k in properties))
-            : [];
-        if (missingRequired.length || invalidTypes.length || unknownKeys.length) {
-            const parts = [];
-            if (missingRequired.length)
-                parts.push(`missing required: ${missingRequired.join(', ')}`);
-            if (invalidTypes.length) {
-                parts.push(invalidTypes
-                    .map((e) => `${e.field}: expected ${e.expected_display}, got ${e.actual}`)
-                    .join('; '));
-            }
-            if (unknownKeys.length)
-                parts.push(`unknown keys: ${unknownKeys.join(', ')}`);
-            const message = `Workflow input validation failed: ${parts.join(' | ')}`;
-            throw new InputValidationError(message, missingRequired, invalidTypes, unknownKeys);
-        }
+        validateInputSchema(input_schema ?? {}, payload);
     }
 }

package/dist/workflows/types.d.ts

@@ -15,27 +15,43 @@ export interface Workflow {
     enable_service_unavailable_recovery: boolean;
     enable_action_timing_recovery: boolean;
 }
-export type WorkflowPropertySchema = string | string[] | {
+export type WorkflowPropertySchema = boolean | string | string[] | {
     type?: string | string[];
     [key: string]: unknown;
 };
 export interface WorkflowInputSchema {
-    type?: 'object';
+    type?: string | string[];
     properties?: Record<string, WorkflowPropertySchema>;
     required?: string[];
-    additionalProperties?: boolean;
+    additionalProperties?: WorkflowPropertySchema;
+    [key: string]: unknown;
 }
+export interface WorkflowVaultCredentialSchema {
+    type: 'credential';
+    domain: string;
+    example?: string;
+}
+export type WorkflowVaultSchema = Record<string, WorkflowVaultCredentialSchema>;
 export interface WorkflowMetadata {
     input_schema: WorkflowInputSchema;
+    workspace_id?: string;
+    vault_schema?: WorkflowVaultSchema;
 }
 export interface InvalidTypeDetail {
     field: string;
     expected_display: string;
     actual: string;
 }
+export interface SchemaErrorDetail {
+    instancePath: string;
+    schemaPath: string;
+    keyword: string;
+    message: string;
+}
 export declare class InputValidationError extends Error {
     readonly missingRequired: string[];
     readonly invalidTypes: InvalidTypeDetail[];
     readonly unknownKeys: string[];
-    constructor(message?: string, missingRequired?: string[], invalidTypes?: InvalidTypeDetail[], unknownKeys?: string[]);
+    readonly schemaErrors: SchemaErrorDetail[];
+    constructor(message?: string, missingRequired?: string[], invalidTypes?: InvalidTypeDetail[], unknownKeys?: string[], schemaErrors?: SchemaErrorDetail[]);
 }

package/dist/workflows/types.js

@@ -5,11 +5,13 @@ export class InputValidationError extends Error {
     missingRequired;
     invalidTypes;
     unknownKeys;
-    constructor(message = 'Input validation failed', missingRequired = [], invalidTypes = [], unknownKeys = []) {
+    schemaErrors;
+    constructor(message = 'Input validation failed', missingRequired = [], invalidTypes = [], unknownKeys = [], schemaErrors = []) {
         super(message);
         this.name = 'InputValidationError';
         this.missingRequired = missingRequired;
         this.invalidTypes = invalidTypes;
         this.unknownKeys = unknownKeys;
+        this.schemaErrors = schemaErrors;
     }
 }

package/dist/workflows/validation.d.ts

@@ -0,0 +1,3 @@
+import { InputValidationError, type WorkflowInputSchema } from './types.js';
+export declare function validateInputSchema(schema: WorkflowInputSchema, payload: Record<string, unknown>): void;
+export declare function inputValidationErrorFromResponse(response: Record<string, unknown>, requestBody?: unknown): InputValidationError | undefined;

package/dist/workflows/validation.js

@@ -0,0 +1,354 @@
+import Ajv from 'ajv';
+import { InputValidationError } from './types.js';
+const ajv = new Ajv({
+    allErrors: true,
+    strict: true,
+    validateFormats: false,
+    addUsedSchema: false,
+    removeAdditional: false,
+    strictSchema: false,
+    keywords: ['example']
+});
+const singleSchemaKeywords = new Set([
+    'additionalItems',
+    'additionalProperties',
+    'contains',
+    'else',
+    'if',
+    'not',
+    'propertyNames',
+    'then'
+]);
+const arraySchemaKeywords = new Set(['allOf', 'anyOf', 'oneOf']);
+const mappingSchemaKeywords = new Set([
+    'definitions',
+    'patternProperties',
+    'properties'
+]);
+export function validateInputSchema(schema, payload) {
+    const externalRef = firstExternalRef(schema);
+    if (externalRef) {
+        const detail = {
+            instancePath: '',
+            schemaPath: externalRef.path,
+            keyword: '$ref',
+            message: `external reference is not allowed: ${externalRef.ref}`
+        };
+        throw new InputValidationError(`Workflow input schema is invalid: ${detail.message}`, [], [], [], [detail]);
+    }
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const detail = {
+            instancePath: '',
+            schemaPath: '#',
+            keyword: 'schema',
+            message
+        };
+        throw new InputValidationError(`Workflow input schema is invalid: ${message}`, [], [], [], [detail]);
+    }
+    if (validate(payload))
+        return;
+    const errors = [...(validate.errors ?? [])].sort(compareErrors);
+    const schemaErrors = errors.map(toSchemaError);
+    const missingRequired = missingRequiredFields(errors);
+    const invalidTypes = invalidTypeDetails(errors, payload);
+    const unknownKeys = unknownPropertyNames(errors);
+    throw new InputValidationError(validationMessage(schemaErrors, missingRequired, invalidTypes, unknownKeys), missingRequired, invalidTypes, unknownKeys, schemaErrors);
+}
+export function inputValidationErrorFromResponse(response, requestBody) {
+    const rawErrors = response.run_input_variables_errors;
+    if (!Array.isArray(rawErrors))
+        return undefined;
+    const schema = isObject(response.input_schema) ? response.input_schema : {};
+    const payload = isObject(requestBody) && isObject(requestBody.run_input_variables)
+        ? requestBody.run_input_variables
+        : {};
+    const schemaErrors = [];
+    const missingRequired = [];
+    const invalidTypes = [];
+    const unknownKeys = [];
+    for (const rawError of rawErrors) {
+        if (!isObject(rawError))
+            continue;
+        const field = String(rawError.field ?? '');
+        const keyword = String(rawError.keyword ?? 'validation');
+        const message = String(rawError.message ?? 'Invalid value');
+        const expected = isObject(rawError.expected) ? rawError.expected : {};
+        const instancePath = field.startsWith('/') ? field : '';
+        const schemaPath = field.startsWith('#')
+            ? field
+            : schemaPathForInstance(schema, instancePath, keyword);
+        schemaErrors.push({ instancePath, schemaPath, keyword, message });
+        if (keyword === 'required') {
+            const missingProperty = expected.missingProperty;
+            if (typeof missingProperty === 'string') {
+                const missingField = instancePath
+                    ? `${instancePath}/${escapePointer(missingProperty)}`
+                    : missingProperty;
+                pushUnique(missingRequired, missingField);
+            }
+        }
+        else if (keyword === 'type') {
+            const expectedType = expected.type;
+            const expectedTypes = Array.isArray(expectedType)
+                ? expectedType.map(String)
+                : String(expectedType ?? 'any').split(',');
+            invalidTypes.push({
+                field: displayField(instancePath),
+                expected_display: expectedTypes.join(' | '),
+                actual: detectType(valueAtPointer(payload, instancePath))
+            });
+        }
+        else if (keyword === 'additionalProperties') {
+            const additionalProperty = expected.additionalProperty;
+            if (typeof additionalProperty === 'string') {
+                const unknownField = instancePath
+                    ? `${instancePath}/${escapePointer(additionalProperty)}`
+                    : additionalProperty;
+                pushUnique(unknownKeys, unknownField);
+            }
+        }
+    }
+    if (!schemaErrors.length) {
+        schemaErrors.push({
+            instancePath: '',
+            schemaPath: '',
+            keyword: 'validation',
+            message: String(response.message ?? 'Validation failed for run_input_variables')
+        });
+    }
+    return new InputValidationError(validationMessage(schemaErrors, missingRequired, invalidTypes, unknownKeys), missingRequired, invalidTypes, unknownKeys, schemaErrors);
+}
+function firstExternalRef(schema, path = []) {
+    if (!isObject(schema))
+        return undefined;
+    if (typeof schema.$ref === 'string' && !schema.$ref.startsWith('#')) {
+        return {
+            path: jsonPointer([...path, '$ref'], '#'),
+            ref: schema.$ref
+        };
+    }
+    for (const keyword of singleSchemaKeywords) {
+        const found = firstExternalRef(schema[keyword], [...path, keyword]);
+        if (found)
+            return found;
+    }
+    const items = schema.items;
+    if (Array.isArray(items)) {
+        for (const [index, child] of items.entries()) {
+            const found = firstExternalRef(child, [...path, 'items', index]);
+            if (found)
+                return found;
+        }
+    }
+    else {
+        const found = firstExternalRef(items, [...path, 'items']);
+        if (found)
+            return found;
+    }
+    for (const keyword of arraySchemaKeywords) {
+        const children = schema[keyword];
+        if (!Array.isArray(children))
+            continue;
+        for (const [index, child] of children.entries()) {
+            const found = firstExternalRef(child, [...path, keyword, index]);
+            if (found)
+                return found;
+        }
+    }
+    for (const keyword of mappingSchemaKeywords) {
+        const children = schema[keyword];
+        if (!isObject(children))
+            continue;
+        for (const [name, child] of Object.entries(children)) {
+            const found = firstExternalRef(child, [...path, keyword, name]);
+            if (found)
+                return found;
+        }
+    }
+    const dependencies = schema.dependencies;
+    if (isObject(dependencies)) {
+        for (const [name, child] of Object.entries(dependencies)) {
+            if (!isObject(child))
+                continue;
+            const found = firstExternalRef(child, [...path, 'dependencies', name]);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+function compareErrors(left, right) {
+    return (left.instancePath.localeCompare(right.instancePath) ||
+        left.schemaPath.localeCompare(right.schemaPath) ||
+        left.keyword.localeCompare(right.keyword) ||
+        (left.message ?? '').localeCompare(right.message ?? ''));
+}
+function toSchemaError(error) {
+    return {
+        instancePath: error.instancePath,
+        schemaPath: error.schemaPath,
+        keyword: error.keyword,
+        message: error.message ?? 'validation failed'
+    };
+}
+function missingRequiredFields(errors) {
+    const fields = [];
+    for (const error of errors) {
+        if (error.keyword !== 'required')
+            continue;
+        const missingProperty = String(error.params.missingProperty);
+        const field = error.instancePath
+            ? `${error.instancePath}/${escapePointer(missingProperty)}`
+            : missingProperty;
+        pushUnique(fields, field);
+    }
+    return fields;
+}
+function invalidTypeDetails(errors, payload) {
+    const details = [];
+    for (const error of errors) {
+        if (error.keyword !== 'type')
+            continue;
+        const expected = String(error.params.type).split(',').join(' | ');
+        const value = valueAtPointer(payload, error.instancePath);
+        details.push({
+            field: displayField(error.instancePath),
+            expected_display: expected,
+            actual: detectType(value)
+        });
+    }
+    return details;
+}
+function unknownPropertyNames(errors) {
+    const fields = [];
+    for (const error of errors) {
+        if (error.keyword !== 'additionalProperties')
+            continue;
+        const property = String(error.params.additionalProperty);
+        const field = error.instancePath
+            ? `${error.instancePath}/${escapePointer(property)}`
+            : property;
+        pushUnique(fields, field);
+    }
+    return fields;
+}
+function validationMessage(schemaErrors, missingRequired, invalidTypes, unknownKeys) {
+    const parts = [];
+    if (missingRequired.length) {
+        parts.push(`missing required: ${missingRequired.join(', ')}`);
+    }
+    if (invalidTypes.length) {
+        parts.push(invalidTypes
+            .map((error) => `${error.field}: expected ${error.expected_display}, got ${error.actual}`)
+            .join('; '));
+    }
+    if (unknownKeys.length) {
+        parts.push(`unknown keys: ${unknownKeys.join(', ')}`);
+    }
+    const extraErrors = schemaErrors.filter((error) => !['required', 'type', 'additionalProperties'].includes(error.keyword));
+    if (extraErrors.length) {
+        parts.push(extraErrors
+            .map((error) => `${error.instancePath || '/'}: ${error.message}`)
+            .join('; '));
+    }
+    return `Workflow input validation failed: ${parts.join(' | ')}`;
+}
+function valueAtPointer(value, pointer) {
+    if (!pointer)
+        return value;
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~'))
+        .reduce((current, part) => {
+        if (Array.isArray(current))
+            return current[Number(part)];
+        if (isObject(current))
+            return current[part];
+        return undefined;
+    }, value);
+}
+function displayField(instancePath) {
+    if (!instancePath)
+        return '$';
+    const withoutPrefix = instancePath.slice(1);
+    return withoutPrefix.includes('/') ? instancePath : withoutPrefix;
+}
+function schemaPathForInstance(schema, instancePath, keyword) {
+    let current = schema;
+    const schemaPath = [];
+    const parts = instancePath
+        ? instancePath
+            .slice(1)
+            .split('/')
+            .map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~'))
+        : [];
+    for (const part of parts) {
+        if (!isObject(current))
+            return '';
+        const properties = current.properties;
+        if (isObject(properties) && part in properties) {
+            current = properties[part];
+            schemaPath.push('properties', part);
+            continue;
+        }
+        const items = current.items;
+        if (isObject(items) && /^\d+$/.test(part)) {
+            current = items;
+            schemaPath.push('items');
+            continue;
+        }
+        const patternProperties = current.patternProperties;
+        if (isObject(patternProperties)) {
+            const match = Object.entries(patternProperties).find(([pattern]) => {
+                try {
+                    return new RegExp(pattern).test(part);
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (match) {
+                current = match[1];
+                schemaPath.push('patternProperties', match[0]);
+                continue;
+            }
+        }
+        return '';
+    }
+    if (isObject(current) && keyword in current) {
+        schemaPath.push(keyword);
+        return jsonPointer(schemaPath, '#');
+    }
+    return '';
+}
+function detectType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'number';
+    }
+    return typeof value;
+}
+function jsonPointer(path, prefix = '') {
+    if (!path.length)
+        return prefix;
+    return `${prefix}/${path.map((part) => escapePointer(String(part))).join('/')}`;
+}
+function escapePointer(value) {
+    return value.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function pushUnique(values, value) {
+    if (!values.includes(value))
+        values.push(value);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudcruise",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {
@@ -19,8 +19,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "build": "node scripts/sync-version.mjs && tsc",
+    "dev": "node scripts/sync-version.mjs && tsc --watch",
     "prepublishOnly": "npm run build",
     "test": "pnpm build && node --test test/*.test.js"
   },
@@ -30,5 +30,14 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "std-env": "^4.3.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "fast-uri": "3.1.8"
+    }
   }
 }