@signstack/cli 0.1.1

package/dist/libs/signstack/base/src/lib/yaml-spec-converter.js

@@ -0,0 +1,998 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitKeyVersion = splitKeyVersion;
+exports.normalizeExpression = normalizeExpression;
+exports.extractExpressionString = extractExpressionString;
+exports.extractBlueprintInputKey = extractBlueprintInputKey;
+exports.resolveRequired = resolveRequired;
+exports.transformInputs = transformInputs;
+exports.transformExpressionInputs = transformExpressionInputs;
+exports.transformRole = transformRole;
+exports.transformField = transformField;
+exports.transformAssetObjectRefs = transformAssetObjectRefs;
+exports.transformPartialObjectRefs = transformPartialObjectRefs;
+exports.transformEnvelopes = transformEnvelopes;
+exports.transformParticipants = transformParticipants;
+exports.transformCustomFields = transformCustomFields;
+exports.transformOrchestrationToTree = transformOrchestrationToTree;
+exports.transformAction = transformAction;
+exports.transformJsonataParams = transformJsonataParams;
+exports.transformJsonataReturnType = transformJsonataReturnType;
+exports.buildHtmlConfigRefs = buildHtmlConfigRefs;
+exports.normalizeYamlFunctionsBlock = normalizeYamlFunctionsBlock;
+exports.convertYamlSpec = convertYamlSpec;
+exports.displayNameToResourceKind = displayNameToResourceKind;
+exports.resourceKindToDisplayName = resourceKindToDisplayName;
+exports.convertResourceToYamlObject = convertResourceToYamlObject;
+exports.resourceToYaml = resourceToYaml;
+const base_1 = require("./models/base");
+const jsonata_function_1 = require("./models/jsonata-function");
+const resource_edge_1 = require("./models/resource-edge");
+const yaml_1 = require("yaml");
+const workflow_1 = require("./models/workflow");
+const util_1 = require("./util");
+// ─── Utility Functions ──────────────────────────────────────────────
+const JSONPATH_ROOT_SEGMENT = /^\$\.([^.[\]]+)/;
+function splitKeyVersion(ref) {
+    if (!ref || typeof ref !== 'string')
+        return { key: ref, version: '' };
+    const [key, version] = ref.split('@');
+    return { key, version: version || '' };
+}
+function normalizeExpression(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return value;
+}
+function extractExpressionString(value) {
+    if (!value)
+        return undefined;
+    if (typeof value === 'object' && 'expression' in value)
+        return value.expression;
+    return String(value);
+}
+function extractBlueprintInputKey(value) {
+    return value.match(JSONPATH_ROOT_SEGMENT)?.[1] ?? '';
+}
+function resolveRequired(required) {
+    if (typeof required === 'boolean')
+        return required;
+    const resolved = normalizeExpression(required);
+    if (util_1.Util.isExpression(resolved))
+        return resolved;
+    return true;
+}
+// ─── Transform Helpers ──────────────────────────────────────────────
+function transformInputs(yamlInputs) {
+    return yamlInputs.map((i) => {
+        const ref = typeof i.schema === 'string'
+            ? splitKeyVersion(i.schema)
+            : { key: '', version: '' };
+        return {
+            key: i.key,
+            schemaKey: i.schemaKey ?? ref.key,
+            schemaVersion: i.schemaVersion ?? ref.version,
+            name: i.name,
+            description: i.description,
+            required: resolveRequired(i.required),
+        };
+    });
+}
+/**
+ * Like transformInputs but supports expression-based required fields.
+ * Used for template inputs where required can be `{ expression: "..." }`.
+ * @deprecated Use transformInputs instead — both now support expressions.
+ */
+function transformExpressionInputs(yamlInputs) {
+    return transformInputs(yamlInputs);
+}
+function transformRole(role) {
+    const output = role.output
+        ? {
+            schemaKey: role.output.schemaKey ?? role.output.schema?.split('@')?.[0],
+            schemaVersion: role.output.schemaVersion ?? role.output.schema?.split('@')?.[1],
+            transform: role.output.transform ?? '',
+        }
+        : undefined;
+    return {
+        key: role.key,
+        name: role.name,
+        roleCategory: role.roleCategory ?? 'signer',
+        output,
+    };
+}
+function transformField(field) {
+    // Handle both API format (widgets array) and CLI format (single widget object)
+    let widgets;
+    if (Array.isArray(field.widgets)) {
+        widgets = field.widgets;
+    }
+    else {
+        const widget = field.widget;
+        widgets = widget
+            ? [
+                {
+                    position: {
+                        pageNumber: widget.page ?? 1,
+                        x: widget.x ?? 0,
+                        y: widget.y ?? 0,
+                    },
+                    dimensions: {
+                        width: widget.width ?? 200,
+                        height: widget.height ?? 20,
+                    },
+                    rotationDegree: widget.rotation ?? 0,
+                    style: widget.style
+                        ? {
+                            fontSizePx: widget.style.fontSize ?? 12,
+                            fontColor: widget.style.fontColor ?? '#000000',
+                            fontFamily: widget.style.fontFamily,
+                            strokeWidth: widget.style.strokeWidth,
+                            strokeColor: widget.style.strokeColor,
+                        }
+                        : undefined,
+                },
+            ]
+            : [];
+    }
+    return {
+        key: field.key,
+        type: field.type,
+        value: normalizeExpression(field.value),
+        role: field.roleKey ?? field.role,
+        includeIf: extractExpressionString(field.includeIf ?? field.displayCondition),
+        widgets,
+    };
+}
+/**
+ * Transforms a map of named asset references (alias → "key@version") into
+ * an array of `{ key, version, alias }`. Used for image references, which
+ * are always plain string refs in YAML.
+ */
+function transformAssetObjectRefs(yamlRefs) {
+    if (!yamlRefs)
+        return undefined;
+    const results = [];
+    for (const [alias, ref] of Object.entries(yamlRefs)) {
+        const assetRef = typeof ref === 'string' ? ref : ref?.asset;
+        if (typeof assetRef === 'string') {
+            const [key, version] = assetRef.split('@');
+            results.push({ key, version, alias });
+        }
+    }
+    return results.length > 0 ? results : undefined;
+}
+/**
+ * Transforms a map of partial references into an array of
+ * `{ key, version, alias, roleMap? }`. Partials support an object form in
+ * YAML that carries an optional `roleMap` alongside the asset reference:
+ *
+ *     partials:
+ *       buyer_sig:
+ *         asset: signature_block@1.0.0
+ *         roleMap: { signer: buyer }
+ */
+function transformPartialObjectRefs(yamlRefs) {
+    if (!yamlRefs)
+        return undefined;
+    const results = [];
+    for (const [alias, ref] of Object.entries(yamlRefs)) {
+        const assetRef = typeof ref === 'string' ? ref : ref?.asset;
+        if (typeof assetRef === 'string') {
+            const [key, version] = assetRef.split('@');
+            const roleMap = typeof ref === 'object' && ref?.roleMap ? ref.roleMap : undefined;
+            results.push({ key, version, alias, ...(roleMap ? { roleMap } : {}) });
+        }
+    }
+    return results.length > 0 ? results : undefined;
+}
+function transformEnvelopes(yamlEnvelopes) {
+    return yamlEnvelopes.map((env) => ({
+        key: env.key,
+        subject: normalizeExpression(env.subject) ?? env.name ?? env.key,
+        name: env.name,
+        resolutionMode: env.resolutionMode,
+        includeIf: extractExpressionString(env.includeIf),
+        documents: (env.documents ?? []).map((d) => {
+            const templateKey = d.templateKey ?? ((d.template ?? '').split('@')[0] || undefined);
+            const templateVersion = d.templateVersion ?? ((d.template ?? '').split('@')[1] || undefined);
+            const inputMap = Array.isArray(d.inputMap)
+                ? d.inputMap
+                : d.inputMap && typeof d.inputMap === 'object'
+                    ? Object.entries(d.inputMap).map(([k, v]) => ({
+                        templateInputKey: k,
+                        blueprintInputKey: typeof v === 'string' ? extractBlueprintInputKey(v) : '',
+                    }))
+                    : undefined;
+            return {
+                key: d.key,
+                name: d.name ?? d.key,
+                templateKey,
+                templateVersion,
+                inputMap,
+                includeIf: d.includeIf,
+                iterator: d.iterator,
+                fileId: normalizeExpression(d.fileId),
+            };
+        }),
+    }));
+}
+function transformParticipants(yamlParticipants) {
+    return yamlParticipants.map((p) => {
+        return {
+            key: p.key,
+            name: typeof p.name === 'string' ? p.name : p.key,
+            roleCategory: p.roleCategory,
+            participantName: normalizeExpression(p.name),
+            participantEmail: normalizeExpression(p.email),
+        };
+    });
+}
+function transformCustomFields(yamlCustomFields) {
+    return yamlCustomFields.map((field) => ({
+        key: field.key,
+        name: field.name,
+        value: normalizeExpression(field.value) ?? field.value,
+    }));
+}
+function transformOrchestrationToTree(node) {
+    if (node.type === 'group') {
+        const step = {
+            key: node.key,
+            type: node.type,
+            execution: node.execution ?? node.executionMode ?? 'sequential',
+            completion: node.completion ??
+                node.completionRule ??
+                workflow_1.WorkflowStepCompletionRule.All,
+            children: (node.children ?? []).map((c) => transformOrchestrationToTree(c)),
+        };
+        if (node.name)
+            step.name = node.name;
+        if (node.includeIf)
+            step.includeIf = node.includeIf;
+        if (node.quorum ?? node.quorumCount)
+            step.quorum = node.quorum ?? node.quorumCount;
+        if (node.onComplete)
+            step.onComplete = transformOnComplete(node.onComplete);
+        return step;
+    }
+    else {
+        const step = {
+            key: node.key,
+            type: node.type,
+            participantKey: node.participantKey ?? node.participant,
+        };
+        if (node.name)
+            step.name = node.name;
+        if (node.includeIf)
+            step.includeIf = node.includeIf;
+        if (node.action)
+            step.action = transformAction(node.action);
+        if (node.onComplete)
+            step.onComplete = transformOnComplete(node.onComplete);
+        return step;
+    }
+}
+function transformOnComplete(onComplete) {
+    const result = {};
+    if (onComplete.validate ?? onComplete.validateExpression) {
+        result.validate = onComplete.validate ?? onComplete.validateExpression;
+    }
+    if (onComplete.updates) {
+        result.updates = onComplete.updates;
+    }
+    return result;
+}
+function transformAction(action) {
+    return {
+        type: action.type,
+        envelopeKey: action.envelopeKey ?? action.envelope,
+        assignments: action.assignments?.map((a) => ({
+            documentKey: a.documentKey ?? a.document,
+            roleKey: a.roleKey ?? a.role,
+        })),
+    };
+}
+function transformJsonataParams(yamlParams) {
+    return yamlParams.map((p) => {
+        const type = p.type;
+        const result = { name: p.name, type };
+        if (type === jsonata_function_1.JsonataFunctionParamType.Array && p.itemType) {
+            result.itemType = p.itemType;
+        }
+        const allowsSchema = type === jsonata_function_1.JsonataFunctionParamType.Object ||
+            (type === jsonata_function_1.JsonataFunctionParamType.Array &&
+                result.itemType === jsonata_function_1.JsonataFunctionItemType.Object);
+        if (allowsSchema) {
+            if (p.schemaKey) {
+                result.schemaKey = p.schemaKey;
+                result.schemaVersion = p.schemaVersion;
+            }
+            else if (p.schema) {
+                const [schemaKey, schemaVersion] = p.schema.split('@');
+                result.schemaKey = schemaKey;
+                result.schemaVersion = schemaVersion;
+            }
+        }
+        return result;
+    });
+}
+function transformJsonataReturnType(yamlReturnType) {
+    const type = (yamlReturnType?.type ??
+        jsonata_function_1.JsonataFunctionParamType.String);
+    const result = { type };
+    if (type === jsonata_function_1.JsonataFunctionParamType.Array && yamlReturnType?.itemType) {
+        result.itemType = yamlReturnType.itemType;
+    }
+    const allowsSchema = type === jsonata_function_1.JsonataFunctionParamType.Object ||
+        (type === jsonata_function_1.JsonataFunctionParamType.Array &&
+            result.itemType === jsonata_function_1.JsonataFunctionItemType.Object);
+    if (allowsSchema) {
+        if (yamlReturnType?.schemaKey) {
+            result.schemaKey = yamlReturnType.schemaKey;
+            result.schemaVersion = yamlReturnType.schemaVersion;
+        }
+        else if (yamlReturnType?.schema) {
+            const [schemaKey, schemaVersion] = yamlReturnType.schema.split('@');
+            result.schemaKey = schemaKey;
+            result.schemaVersion = schemaVersion;
+        }
+    }
+    return result;
+}
+function buildHtmlConfigRefs(spec) {
+    if (!spec)
+        return undefined;
+    const refs = {};
+    let hasRefs = false;
+    const partials = transformPartialObjectRefs(spec.partials);
+    if (partials) {
+        refs.partials = partials;
+        hasRefs = true;
+    }
+    if (spec.styles && Array.isArray(spec.styles)) {
+        const styles = spec.styles
+            .filter((s) => typeof s === 'string')
+            .map((s) => {
+            const [key, version] = s.split('@');
+            return { key, version };
+        });
+        if (styles.length > 0) {
+            refs.styles = styles;
+            hasRefs = true;
+        }
+    }
+    const images = transformAssetObjectRefs(spec.images);
+    if (images) {
+        refs.images = images;
+        hasRefs = true;
+    }
+    const viewModelSchemaRef = spec.data?.schema;
+    if (viewModelSchemaRef) {
+        const [key, version] = viewModelSchemaRef.split('@');
+        refs.data = { schemaKey: key, schemaVersion: version };
+        hasRefs = true;
+    }
+    if (spec.pdfSettings) {
+        refs.pdfSettings = spec.pdfSettings;
+        hasRefs = true;
+    }
+    return hasRefs ? refs : undefined;
+}
+// ─── Per-Kind Spec Converters ───────────────────────────────────────
+function convertAssetYamlSpec(spec) {
+    const converted = { ...spec };
+    // Build htmlConfig from top-level CLI fields
+    const htmlConfig = buildHtmlConfigRefs(spec);
+    if (htmlConfig) {
+        converted.htmlConfig = htmlConfig;
+    }
+    // Remove fields consumed by htmlConfig
+    delete converted.partials;
+    delete converted.styles;
+    delete converted.images;
+    delete converted.pdfSettings;
+    if (converted.data?.schema) {
+        delete converted.data;
+    }
+    // Remove file path (not applicable for API creation)
+    delete converted.file;
+    return converted;
+}
+function convertTemplateYamlSpec(spec) {
+    const contentKey = spec.contentKey ?? (spec.content ?? '').split('@')[0] ?? '';
+    const contentVersion = spec.contentVersion ?? (spec.content ?? '').split('@')[1] ?? '';
+    const inputs = transformExpressionInputs(spec.inputs ?? []);
+    const roles = (spec.roles ?? []).map(transformRole);
+    const fields = (spec.fields ?? []).map(transformField);
+    const data = spec.data?.transform
+        ? { transform: spec.data.transform }
+        : undefined;
+    const functions = normalizeYamlFunctionsBlock(spec.functions);
+    return {
+        type: spec.type ?? 'pdf',
+        contentKey,
+        contentVersion,
+        data,
+        fields,
+        inputs,
+        roles,
+        functions,
+    };
+}
+function convertBlueprintYamlSpec(spec) {
+    const inputs = transformInputs(spec.inputs ?? []);
+    const envelopes = transformEnvelopes(spec.envelopes ?? []);
+    const participants = transformParticipants(spec.participants ?? []);
+    const customFields = transformCustomFields(spec.customFields ?? []);
+    const orchestration = spec.orchestration
+        ? transformOrchestrationToTree(spec.orchestration)
+        : undefined;
+    const functions = normalizeYamlFunctionsBlock(spec.functions);
+    return {
+        envelopes,
+        participants,
+        inputs,
+        customFields,
+        orchestration,
+        functions,
+    };
+}
+/**
+ * Normalize a YAML `functions` block (object map or array form) into the API
+ * shape `{ alias, functionKey, functionVersion }[]`.
+ *
+ * Supported shapes:
+ * - Object map: `{ money: "format_currency@1.0.0" }` (key is alias)
+ * - Array of strings: `["format_currency@1.0.0"]` (alias = functionKey)
+ */
+function normalizeYamlFunctionsBlock(fns) {
+    if (!fns)
+        return undefined;
+    if (Array.isArray(fns)) {
+        return fns.flatMap((entry) => {
+            if (typeof entry !== 'string')
+                return [];
+            const [functionKey, functionVersion] = entry.split('@');
+            // No alias for array form — function is callable as $functionKey(...)
+            return [
+                { functionKey, functionVersion: functionVersion || base_1.DRAFT_VERSION },
+            ];
+        });
+    }
+    if (typeof fns === 'object') {
+        return Object.entries(fns).flatMap(([alias, ref]) => {
+            if (typeof ref !== 'string')
+                return [];
+            const [functionKey, functionVersion] = ref.split('@');
+            return [
+                {
+                    alias,
+                    functionKey,
+                    functionVersion: functionVersion || base_1.DRAFT_VERSION,
+                },
+            ];
+        });
+    }
+    return undefined;
+}
+function convertFunctionYamlSpec(spec) {
+    const params = transformJsonataParams(spec.params ?? []);
+    const returnType = transformJsonataReturnType(spec.returnType);
+    return {
+        params: params.length > 0 ? params : undefined,
+        returnType,
+        body: spec.body ?? '',
+        ...(spec.functions && { functions: spec.functions }),
+    };
+}
+// ─── API Format Detection ───────────────────────────────────────────
+/**
+ * Detect whether a spec is already in API format (vs CLI YAML format).
+ * API format uses split key/version fields (e.g. templateKey + templateVersion),
+ * while YAML format uses combined refs (e.g. template: "key@version").
+ */
+function isApiFormat(kind, spec) {
+    switch (kind) {
+        case resource_edge_1.ResourceKind.Blueprint:
+            // Always convert — AI generates mixed CLI/API formats
+            return false;
+        case resource_edge_1.ResourceKind.Template:
+            // Always convert — AI generates mixed CLI/API formats
+            return false;
+        case resource_edge_1.ResourceKind.Asset:
+            return spec.htmlConfig !== undefined;
+        case resource_edge_1.ResourceKind.JsonataFunction:
+            // Always convert — YAML uses combined 'schema' ref that needs splitting into schemaKey/schemaVersion
+            return false;
+        default:
+            return false;
+    }
+}
+// ─── Main Entry Points ──────────────────────────────────────────────
+/**
+ * Convert a YAML spec to API format based on resource kind.
+ * If the spec is already in API format, returns it as-is.
+ */
+function convertYamlSpec(kind, spec) {
+    if (isApiFormat(kind, spec)) {
+        return { ...spec };
+    }
+    switch (kind) {
+        case resource_edge_1.ResourceKind.Schema:
+            return { ...spec };
+        case resource_edge_1.ResourceKind.Asset:
+            return convertAssetYamlSpec(spec);
+        case resource_edge_1.ResourceKind.Template:
+            return convertTemplateYamlSpec(spec);
+        case resource_edge_1.ResourceKind.Blueprint:
+            return convertBlueprintYamlSpec(spec);
+        case resource_edge_1.ResourceKind.JsonataFunction:
+            return convertFunctionYamlSpec(spec);
+        default:
+            return { ...spec };
+    }
+}
+function displayNameToResourceKind(display) {
+    switch (display) {
+        case 'Schema':
+        case resource_edge_1.ResourceKind.Schema:
+            return resource_edge_1.ResourceKind.Schema;
+        case 'Asset':
+        case resource_edge_1.ResourceKind.Asset:
+            return resource_edge_1.ResourceKind.Asset;
+        case 'Template':
+        case resource_edge_1.ResourceKind.Template:
+            return resource_edge_1.ResourceKind.Template;
+        case 'JsonataFunction':
+        case resource_edge_1.ResourceKind.JsonataFunction:
+            return resource_edge_1.ResourceKind.JsonataFunction;
+        case 'Blueprint':
+        case resource_edge_1.ResourceKind.Blueprint:
+            return resource_edge_1.ResourceKind.Blueprint;
+        default:
+            return null;
+    }
+}
+function resourceKindToDisplayName(kind) {
+    switch (kind) {
+        case resource_edge_1.ResourceKind.Schema:
+            return 'Schema';
+        case resource_edge_1.ResourceKind.Asset:
+            return 'Asset';
+        case resource_edge_1.ResourceKind.Template:
+            return 'Template';
+        case resource_edge_1.ResourceKind.JsonataFunction:
+            return 'JsonataFunction';
+        case resource_edge_1.ResourceKind.Blueprint:
+            return 'Blueprint';
+    }
+}
+// ─── API → YAML Object Converters ──────────────────────────────────
+//
+// These convert API-format resources (as stored in MasterResourceStore)
+// into clean YAML-friendly plain objects. The caller stringifies with
+// `yaml.stringify(result, { lineWidth: 0 })`.
+function formatMetadataForYaml(metadata) {
+    return {
+        key: metadata?.key || '',
+        version: metadata?.version || '',
+        name: metadata?.name || '',
+        ...(metadata?.description && { description: metadata.description }),
+        ...(metadata?.labels &&
+            Object.keys(metadata.labels).length && {
+            labels: metadata.labels,
+        }),
+    };
+}
+function schemaToYamlObject(metadata, spec) {
+    const parsedDefinition = (() => {
+        if (!spec?.schemaDefinition)
+            return undefined;
+        if (typeof spec.schemaDefinition === 'object')
+            return spec.schemaDefinition;
+        try {
+            return JSON.parse(spec.schemaDefinition);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    return {
+        apiVersion: 'signstack/v1beta2',
+        kind: 'Schema',
+        metadata: formatMetadataForYaml(metadata),
+        spec: {
+            jsonSchemaDraft: spec?.jsonSchemaDraft ?? '2020-12',
+            ...(parsedDefinition && { schemaDefinition: parsedDefinition }),
+        },
+    };
+}
+function assetToYamlObject(metadata, spec) {
+    const assetType = spec?.type ?? base_1.AssetType.Html;
+    const content = spec?.content;
+    const yamlSpec = { type: assetType };
+    if (assetType !== base_1.AssetType.Image && assetType !== base_1.AssetType.Pdf && content) {
+        yamlSpec.content = content;
+    }
+    if (spec?.fileId)
+        yamlSpec.fileId = spec.fileId;
+    // htmlConfig → YAML partials/images/styles/data/pdfSettings
+    const config = spec?.htmlConfig;
+    if (config) {
+        if (config.partials?.length) {
+            yamlSpec.partials = {};
+            for (const p of config.partials) {
+                const assetRef = toRef(p.key, p.version);
+                if (p.roleMap && Object.keys(p.roleMap).length > 0) {
+                    yamlSpec.partials[p.alias] = {
+                        asset: assetRef,
+                        roleMap: p.roleMap,
+                    };
+                }
+                else {
+                    yamlSpec.partials[p.alias] = assetRef;
+                }
+            }
+        }
+        if (config.images?.length) {
+            yamlSpec.images = {};
+            for (const img of config.images) {
+                yamlSpec.images[img.alias] = toRef(img.key, img.version);
+            }
+        }
+        if (config.styles?.length) {
+            yamlSpec.styles = config.styles.map((s) => toRef(s.key, s.version));
+        }
+        if (config.data?.schemaKey) {
+            yamlSpec.data = {
+                schema: toRef(config.data.schemaKey, config.data.schemaVersion),
+            };
+        }
+        if (config.pdfSettings) {
+            yamlSpec.pdfSettings = config.pdfSettings;
+        }
+    }
+    return {
+        apiVersion: 'signstack/v1beta2',
+        kind: 'Asset',
+        metadata: formatMetadataForYaml(metadata),
+        spec: yamlSpec,
+    };
+}
+function functionToYamlObject(metadata, spec) {
+    const params = (spec?.params ?? [])
+        .filter((p) => p.name && p.name.trim())
+        .map((p) => {
+        const result = {
+            name: p.name,
+            type: p.type,
+        };
+        if (p.type === jsonata_function_1.JsonataFunctionParamType.Array && p.itemType) {
+            result.itemType = p.itemType;
+        }
+        const allowsSchema = p.type === jsonata_function_1.JsonataFunctionParamType.Object ||
+            (p.type === jsonata_function_1.JsonataFunctionParamType.Array &&
+                p.itemType === jsonata_function_1.JsonataFunctionItemType.Object);
+        if (allowsSchema) {
+            const schemaRef = toRef(p.schemaKey, p.schemaVersion);
+            if (schemaRef)
+                result.schema = schemaRef;
+        }
+        return result;
+    });
+    const returnType = spec?.returnType ?? { type: 'string' };
+    const yamlReturnType = { type: returnType.type };
+    if (returnType.type === jsonata_function_1.JsonataFunctionParamType.Array &&
+        returnType.itemType) {
+        yamlReturnType.itemType = returnType.itemType;
+    }
+    const rtAllowsSchema = returnType.type === jsonata_function_1.JsonataFunctionParamType.Object ||
+        (returnType.type === jsonata_function_1.JsonataFunctionParamType.Array &&
+            returnType.itemType === jsonata_function_1.JsonataFunctionItemType.Object);
+    if (rtAllowsSchema) {
+        const rtSchema = toRef(returnType.schemaKey, returnType.schemaVersion);
+        if (rtSchema)
+            yamlReturnType.schema = rtSchema;
+    }
+    return {
+        apiVersion: 'signstack/v1beta2',
+        kind: 'JsonataFunction',
+        metadata: formatMetadataForYaml(metadata),
+        spec: {
+            ...(params.length > 0 && { params }),
+            returnType: yamlReturnType,
+            ...(spec?.body && { body: spec.body }),
+        },
+    };
+}
+/**
+ * Convert an API-format resource into a YAML-friendly plain object.
+ * For resource kinds without special formatting (Template, Blueprint),
+ * returns a generic `{ kind, metadata, spec }` structure.
+ */
+function convertResourceToYamlObject(kind, metadata, spec) {
+    switch (kind) {
+        case resource_edge_1.ResourceKind.Schema:
+            return schemaToYamlObject(metadata, spec);
+        case resource_edge_1.ResourceKind.Asset:
+            return assetToYamlObject(metadata, spec);
+        case resource_edge_1.ResourceKind.JsonataFunction:
+            return functionToYamlObject(metadata, spec);
+        case resource_edge_1.ResourceKind.Blueprint:
+            return blueprintToYamlObject(metadata, spec);
+        case resource_edge_1.ResourceKind.Template:
+            return templateToYamlObject(metadata, spec);
+        default:
+            return {
+                kind: resourceKindToDisplayName(kind),
+                metadata: formatMetadataForYaml(metadata),
+                spec,
+            };
+    }
+}
+/**
+ * Convert an API-format resource into a YAML string.
+ * Convenience wrapper around convertResourceToYamlObject + yamlStringify.
+ */
+function resourceToYaml(kind, metadata, spec) {
+    try {
+        return (0, yaml_1.stringify)(convertResourceToYamlObject(kind, metadata, spec), {
+            lineWidth: 0,
+        });
+    }
+    catch (e) {
+        console.error('Failed to stringify resource to YAML:', e);
+        return '';
+    }
+}
+// ── Helper: combine key@version ──
+function toRef(key, version) {
+    if (!key)
+        return undefined;
+    return version ? `${key}@${version}` : key;
+}
+function passthroughExpression(value) {
+    if (value == null)
+        return undefined;
+    return value;
+}
+// ── Blueprint API → YAML ──
+function blueprintToYamlObject(metadata, spec) {
+    const yamlSpec = {};
+    // inputs: schemaKey/schemaVersion → schema: key@version
+    if (spec?.inputs?.length) {
+        yamlSpec.inputs = spec.inputs.map((input) => {
+            const result = { key: input.key };
+            if (input.name)
+                result.name = input.name;
+            result.schema = toRef(input.schemaKey, input.schemaVersion);
+            if (input.required !== undefined)
+                result.required = passthroughExpression(input.required);
+            return result;
+        });
+    }
+    // functions: emit object-map only when at least one entry has a distinct alias
+    if (spec?.functions?.length) {
+        const hasDistinctAlias = spec.functions.some((fn) => fn.alias);
+        if (hasDistinctAlias) {
+            yamlSpec.functions = {};
+            for (const fn of spec.functions) {
+                yamlSpec.functions[fn.alias ?? fn.functionKey] = toRef(fn.functionKey, fn.functionVersion);
+            }
+        }
+        else {
+            yamlSpec.functions = spec.functions.map((fn) => toRef(fn.functionKey, fn.functionVersion));
+        }
+    }
+    // participants: participantName/participantEmail → name/email exprs
+    if (spec?.participants?.length) {
+        yamlSpec.participants = spec.participants.map((p) => {
+            const result = { key: p.key };
+            if (p.participantName) {
+                result.name = passthroughExpression(p.participantName);
+            }
+            else if (p.name) {
+                result.name = p.name;
+            }
+            if (p.participantEmail) {
+                result.email = passthroughExpression(p.participantEmail);
+            }
+            if (p.roleCategory)
+                result.roleCategory = p.roleCategory;
+            return result;
+        });
+    }
+    // envelopes: templateKey/templateVersion → template: key@version
+    if (spec?.envelopes?.length) {
+        yamlSpec.envelopes = spec.envelopes.map((env) => {
+            const yamlEnv = { key: env.key };
+            if (env.name)
+                yamlEnv.name = env.name;
+            if (env.subject)
+                yamlEnv.subject = passthroughExpression(env.subject);
+            if (env.includeIf)
+                yamlEnv.includeIf = env.includeIf;
+            if (env.documents?.length) {
+                yamlEnv.documents = env.documents.map((doc) => {
+                    const yamlDoc = { key: doc.key };
+                    if (doc.name)
+                        yamlDoc.name = doc.name;
+                    yamlDoc.template = toRef(doc.templateKey, doc.templateVersion);
+                    if (doc.inputMap?.length) {
+                        yamlDoc.inputMap = {};
+                        for (const m of doc.inputMap) {
+                            yamlDoc.inputMap[m.templateInputKey] = m.blueprintInputKey
+                                ? `$.${m.blueprintInputKey}`
+                                : m.blueprintInputKey;
+                        }
+                    }
+                    if (doc.includeIf)
+                        yamlDoc.includeIf = doc.includeIf;
+                    if (doc.iterator)
+                        yamlDoc.iterator = doc.iterator;
+                    if (doc.fileId)
+                        yamlDoc.fileId = passthroughExpression(doc.fileId);
+                    return yamlDoc;
+                });
+            }
+            return yamlEnv;
+        });
+    }
+    // customFields: pass through expression value
+    if (spec?.customFields?.length) {
+        yamlSpec.customFields = spec.customFields.map((cf) => ({
+            ...cf,
+            value: passthroughExpression(cf.value),
+        }));
+    }
+    // orchestration: convert step tree
+    if (spec?.orchestration) {
+        yamlSpec.orchestration = stepToYaml(spec.orchestration);
+    }
+    return {
+        apiVersion: 'signstack/v1beta2',
+        kind: 'Blueprint',
+        metadata: formatMetadataForYaml(metadata),
+        spec: yamlSpec,
+    };
+}
+function stepToYaml(step) {
+    const result = { key: step.key, type: step.type };
+    if (step.name)
+        result.name = step.name;
+    if (step.includeIf)
+        result.includeIf = step.includeIf;
+    if (step.type === 'group') {
+        result.execution = step.execution ?? 'sequential';
+        if (step.completion && step.completion !== 'all') {
+            result.completion = step.completion;
+        }
+        if (step.quorum)
+            result.quorum = step.quorum;
+        if (step.children?.length) {
+            result.children = step.children.map(stepToYaml);
+        }
+    }
+    else {
+        result.participant = step.participantKey;
+        if (step.action) {
+            result.action = {
+                type: step.action.type,
+                envelope: step.action.envelopeKey,
+                ...(step.action.assignments?.length && {
+                    assignments: step.action.assignments.map((a) => ({
+                        document: a.documentKey,
+                        role: a.roleKey,
+                    })),
+                }),
+            };
+        }
+    }
+    if (step.onComplete)
+        result.onComplete = step.onComplete;
+    return result;
+}
+// ── Template API → YAML ──
+function templateToYamlObject(metadata, spec) {
+    const yamlSpec = {};
+    if (spec?.type)
+        yamlSpec.type = spec.type;
+    // content: contentKey/contentVersion → content: key@version
+    const contentRef = toRef(spec?.contentKey, spec?.contentVersion);
+    if (contentRef)
+        yamlSpec.content = contentRef;
+    // inputs: schemaKey/schemaVersion → schema: key@version
+    if (spec?.inputs?.length) {
+        yamlSpec.inputs = spec.inputs.map((input) => {
+            const result = { key: input.key };
+            if (input.name)
+                result.name = input.name;
+            result.schema = toRef(input.schemaKey, input.schemaVersion);
+            if (input.required !== undefined)
+                result.required = passthroughExpression(input.required);
+            return result;
+        });
+    }
+    // functions: emit object-map only when at least one entry has a distinct alias
+    if (spec?.functions?.length) {
+        const hasDistinctAlias = spec.functions.some((fn) => fn.alias);
+        if (hasDistinctAlias) {
+            yamlSpec.functions = {};
+            for (const fn of spec.functions) {
+                yamlSpec.functions[fn.alias ?? fn.functionKey] = toRef(fn.functionKey, fn.functionVersion);
+            }
+        }
+        else {
+            yamlSpec.functions = spec.functions.map((fn) => toRef(fn.functionKey, fn.functionVersion));
+        }
+    }
+    // roles
+    if (spec?.roles?.length) {
+        yamlSpec.roles = spec.roles.map((role) => {
+            const result = { key: role.key };
+            if (role.name)
+                result.name = role.name;
+            if (role.output) {
+                result.output = { ...role.output };
+                result.output.schema = toRef(role.output.schemaKey, role.output.schemaVersion);
+                delete result.output.schemaKey;
+                delete result.output.schemaVersion;
+            }
+            return result;
+        });
+    }
+    // fields: convert API widgets array back to singular widget object
+    if (spec?.fields?.length) {
+        yamlSpec.fields = spec.fields.map((field) => {
+            const result = { key: field.key, type: field.type };
+            if (field.role)
+                result.role = field.role;
+            else if (field.roleKey)
+                result.role = field.roleKey;
+            if (field.value !== undefined)
+                result.value = passthroughExpression(field.value);
+            if (field.includeIf)
+                result.includeIf = field.includeIf;
+            // Convert widgets array → singular widget object for YAML schema
+            const widgets = field.widgets;
+            if (Array.isArray(widgets) && widgets.length > 0) {
+                const w = widgets[0];
+                result.widget = {
+                    page: w.position?.pageNumber ?? w.page ?? 1,
+                    x: w.position?.x ?? w.x ?? 0,
+                    y: w.position?.y ?? w.y ?? 0,
+                    width: w.dimensions?.width ?? w.width ?? 200,
+                    height: w.dimensions?.height ?? w.height ?? 20,
+                    ...(w.rotationDegree !== undefined &&
+                        w.rotationDegree !== 0 && { rotation: w.rotationDegree }),
+                    ...(w.style || w.dimensions?.style
+                        ? {
+                            style: {
+                                ...(w.style?.fontSizePx && { fontSize: w.style.fontSizePx }),
+                                ...(w.style?.fontColor && { fontColor: w.style.fontColor }),
+                                ...(w.style?.fontFamily && {
+                                    fontFamily: w.style.fontFamily,
+                                }),
+                            },
+                        }
+                        : {}),
+                };
+            }
+            else if (field.widget) {
+                result.widget = field.widget;
+            }
+            return result;
+        });
+    }
+    // data (HTML data config)
+    if (spec?.data)
+        yamlSpec.data = spec.data;
+    return {
+        apiVersion: 'signstack/v1beta2',
+        kind: 'Template',
+        metadata: formatMetadataForYaml(metadata),
+        spec: yamlSpec,
+    };
+}
+//# sourceMappingURL=yaml-spec-converter.js.map