@siloy/hubspot-provisioning 0.0.0-stage → 0.1.0

package/dist/engine/src/blueprint/serialize.d.ts

@@ -0,0 +1,22 @@
+import { type Blueprint, type DraftBlueprint } from './schema.ts';
+import { type BlueprintIssue } from './validate.ts';
+/** Parse a blueprint from YAML or JSON text (JSON is valid YAML). */
+export declare function parseBlueprint(text: string): Blueprint;
+export type DraftYaml = {
+    ok: true;
+    content: DraftBlueprint;
+    issues: BlueprintIssue[];
+} | {
+    ok: false;
+    error: string;
+    line: number | null;
+    issues: BlueprintIssue[];
+};
+/**
+ * The editor's YAML tab (spec #27 §7.6): parse the text and fit it to the draft schema. `ok` means the
+ * forms can render it; issues are listed either way. Never throws.
+ */
+export declare function readDraftYaml(text: string): DraftYaml;
+/** YAML for humans. Values equal to their schema default are omitted; parsing restores them. */
+export declare function serializeBlueprint(bp: Blueprint): string;
+export declare function blueprintJsonSchema(): Record<string, unknown>;

package/dist/engine/src/blueprint/serialize.js

@@ -0,0 +1,70 @@
+import { parse, stringify, YAMLParseError } from 'yaml';
+import { z } from 'zod';
+import { BlueprintError } from '../errors.js';
+import { BlueprintSchema, DraftBlueprintSchema } from './schema.js';
+import { blueprintIssues, validateBlueprint } from './validate.js';
+/** Parse a blueprint from YAML or JSON text (JSON is valid YAML). */
+export function parseBlueprint(text) {
+    let raw;
+    try {
+        raw = parse(text.replace(/^/, ''));
+    }
+    catch (error) {
+        throw new BlueprintError([`not valid YAML or JSON: ${error.message}`]);
+    }
+    return validateBlueprint(raw);
+}
+/**
+ * The editor's YAML tab (spec #27 §7.6): parse the text and fit it to the draft schema. `ok` means the
+ * forms can render it; issues are listed either way. Never throws.
+ */
+export function readDraftYaml(text) {
+    let raw;
+    try {
+        raw = parse(text.replace(/^\uFEFF/, ''));
+    }
+    catch (error) {
+        const line = error instanceof YAMLParseError ? (error.linePos?.[0]?.line ?? null) : null;
+        return { ok: false, error: error.message, line, issues: [] };
+    }
+    const issues = blueprintIssues(raw);
+    const draft = DraftBlueprintSchema.safeParse(raw);
+    if (draft.success)
+        return { ok: true, content: draft.data, issues };
+    return { ok: false, error: 'This YAML does not fit the blueprint structure yet; the issues below say where.', line: null, issues };
+}
+/** YAML for humans. Values equal to their schema default are omitted; parsing restores them. */
+export function serializeBlueprint(bp) {
+    return stringify(compact(bp), { lineWidth: 0 });
+}
+export function blueprintJsonSchema() {
+    return z.toJSONSchema(BlueprintSchema, { io: 'input' });
+}
+function compact(bp) {
+    return {
+        format: bp.format,
+        ...(bp.source ? { source: bp.source } : {}),
+        objects: bp.objects.map((object) => ({
+            objectType: object.objectType,
+            ...(object.schema ? { schema: object.schema } : {}),
+            ...(object.labels ? { labels: object.labels } : {}),
+            propertyGroups: object.propertyGroups,
+            properties: object.properties.map(compactProperty),
+            ...(object.pipelines.length > 0
+                ? { pipelines: object.pipelines.map(({ origin, ...pipeline }) => (origin === 'custom' ? pipeline : { origin, ...pipeline })) }
+                : {}),
+        })),
+        associations: bp.associations.map(({ labels, ...pair }) => (labels.length > 0 ? { ...pair, labels } : pair)),
+    };
+}
+function compactProperty(property) {
+    const { origin, hasUniqueValue, options, ...rest } = property;
+    return {
+        ...rest,
+        ...(origin === 'custom' ? {} : { origin }),
+        ...(hasUniqueValue ? { hasUniqueValue } : {}),
+        ...(options.length > 0
+            ? { options: options.map(({ hidden, ...option }) => (hidden ? { ...option, hidden } : option)) }
+            : {}),
+    };
+}

package/dist/engine/src/blueprint/validate.d.ts

@@ -0,0 +1,35 @@
+import { type Blueprint, type BlueprintObject, type Property } from './schema.ts';
+export type IssuePath = Array<string | number>;
+/**
+ * One problem in a blueprint. `at: message` is the text BlueprintError has always shown; `path` finds the
+ * field by index, so an editor can place it even when two items share a key.
+ */
+export interface BlueprintIssue {
+    path: IssuePath;
+    at: string;
+    message: string;
+}
+export declare function issueText(issue: BlueprintIssue): string;
+export interface ValidateOptions {
+    /**
+     * Content saved before #107 is read back: allow what the old rules allowed and HubSpot does not, an uppercase
+     * group name, so such a version still opens. New content and plans are checked without it.
+     */
+    stored?: boolean;
+}
+/** Structural (Zod) and semantic validation. Throws BlueprintError listing every issue found. */
+export declare function validateBlueprint(input: unknown, options?: ValidateOptions): Blueprint;
+/**
+ * Every issue, without throwing. Unlike validateBlueprint it also runs the semantic checks when only
+ * string rules fail (an empty label, an odd key), so an editor shows them all at once (spec #27 §4.2).
+ */
+export declare function blueprintIssues(input: unknown): BlueprintIssue[];
+/**
+ * Calculated-property rules for one property (spec addendum §2). Also used by ingest to drop what a
+ * blueprint cannot hold. Formula references are checked at plan time, against the target too.
+ */
+export declare function calculationIssues(at: string, property: Property): string[];
+/** Semantic option rules for one property. Also used by ingest to drop what a blueprint cannot hold. */
+export declare function optionIssues(at: string, property: Property): string[];
+/** Pipeline and stage rules for one object (spec §2, quirks P1-P2). */
+export declare function pipelineIssues(at: string, object: BlueprintObject): string[];

package/dist/engine/src/blueprint/validate.js

@@ -0,0 +1,385 @@
+import { BlueprintError } from '../errors.js';
+import { pairId } from './associations.js';
+import { formulaCycles } from './formula.js';
+import { CUSTOM_OBJECT_NAME_MAX } from './groups.js';
+import { canHavePipelines, isClosedStage, metadataKeyFor } from './pipelines.js';
+import { BlueprintSchema, DraftBlueprintSchema, EQUATION_FIELD_TYPE, EQUATION_TYPES, GROUP_NAME_LOWERCASE, isEquation, isLowercaseGroupName, isStandardObject } from './schema.js';
+const MAX_LABELS_PER_PAIR = 10;
+export function issueText(issue) {
+    return `${issue.at}: ${issue.message}`;
+}
+/** Structural (Zod) and semantic validation. Throws BlueprintError listing every issue found. */
+export function validateBlueprint(input, options = {}) {
+    const { issues, data } = collect(input, false, options);
+    if (issues.length > 0 || data === undefined)
+        throw new BlueprintError(issues.map(issueText));
+    return data;
+}
+/**
+ * Every issue, without throwing. Unlike validateBlueprint it also runs the semantic checks when only
+ * string rules fail (an empty label, an odd key), so an editor shows them all at once (spec #27 §4.2).
+ */
+export function blueprintIssues(input) {
+    return collect(input, true, {}).issues;
+}
+function collect(input, draftSemantics, options) {
+    const issues = preParseIssues(input);
+    const result = BlueprintSchema.safeParse(input);
+    if (!result.success) {
+        for (const zodIssue of result.error.issues) {
+            // A lone dataSensitivity key is already explained by preParseIssues; skip Zod's duplicate.
+            if (zodIssue.code === 'unrecognized_keys' && sameKeys(zodIssue.keys, ['dataSensitivity']))
+                continue;
+            // An old flat association too; its unknown keys are the label preParseIssues points at.
+            if (zodIssue.code === 'unrecognized_keys' && zodIssue.path.length === 2 && zodIssue.path[0] === 'associations'
+                && isFlatAssociation(input.associations[zodIssue.path[1]]))
+                continue;
+            const path = zodIssue.path.filter((p) => typeof p !== 'symbol');
+            issues.push({ path, at: path.map(String).join('.') || '(root)', message: zodIssue.message });
+        }
+        if (draftSemantics) {
+            const draft = DraftBlueprintSchema.safeParse(input);
+            if (draft.success)
+                issues.push(...semanticIssues(draft.data, options));
+        }
+        return { issues };
+    }
+    issues.push(...semanticIssues(result.data, options));
+    return { issues, data: result.data };
+}
+function sameKeys(actual, expected) {
+    return actual.length === expected.length && expected.every((key, i) => actual[i] === key);
+}
+function collector() {
+    const issues = [];
+    return { issues, add: (path, at, message) => { issues.push({ path, at, message }); } };
+}
+/** The format before #30: a label with `key` or `label` directly on the association entry. */
+function isFlatAssociation(association) {
+    return association !== null && typeof association === 'object' && ('key' in association || 'label' in association);
+}
+/**
+ * dataSensitivity gets its own message (instead of Zod's "unrecognized key") because the reason
+ * matters: the engine reads properties as non_sensitive, so a sensitive one would be invisible to
+ * the next run and re-created forever. isClosed too: users expect to set it, but HubSpot derives it.
+ * An association in the old flat shape gets a hint where its label now goes.
+ * A pure scan: the input is never modified.
+ */
+function preParseIssues(input) {
+    const { issues, add } = collector();
+    const associations = input?.associations;
+    if (Array.isArray(associations)) {
+        associations.forEach((association, a) => {
+            if (isFlatAssociation(association)) {
+                add(['associations', a], `associations.${a}`, 'associations are now grouped per object pair: move this label under `labels` of its pair');
+            }
+        });
+    }
+    const objects = input?.objects;
+    if (!Array.isArray(objects))
+        return issues;
+    objects.forEach((object, i) => {
+        const pipelines = object?.pipelines;
+        if (Array.isArray(pipelines)) {
+            pipelines.forEach((pipeline, j) => {
+                const stages = pipeline?.stages;
+                if (!Array.isArray(stages))
+                    return;
+                stages.forEach((stage, k) => {
+                    const metadata = stage?.metadata;
+                    if (metadata !== null && typeof metadata === 'object' && 'isClosed' in metadata) {
+                        add(['objects', i, 'pipelines', j, 'stages', k, 'metadata', 'isClosed'], `objects.${i}.pipelines.${j}.stages.${k}.metadata.isClosed`, 'isClosed is derived by HubSpot from probability, ticketState or state; remove it');
+                    }
+                });
+            });
+        }
+        const properties = object?.properties;
+        if (!Array.isArray(properties))
+            return;
+        properties.forEach((property, j) => {
+            if (property !== null && typeof property === 'object' && 'dataSensitivity' in property) {
+                add(['objects', i, 'properties', j, 'dataSensitivity'], `objects.${i}.properties.${j}.dataSensitivity`, 'not supported — properties are read as non_sensitive, so a sensitive property would be invisible to the next run and re-created forever');
+            }
+        });
+    });
+    return issues;
+}
+function semanticIssues(bp, options) {
+    const { issues, add } = collector();
+    const objectNames = new Set();
+    bp.objects.forEach((object, i) => {
+        const at = `objects.${object.objectType}`;
+        const path = ['objects', i];
+        if (objectNames.has(object.objectType))
+            add(path, at, 'declared more than once');
+        objectNames.add(object.objectType);
+        const standard = isStandardObject(object.objectType);
+        if (standard && object.schema)
+            add([...path, 'schema'], `${at}.schema`, 'standard objects have no schema block');
+        if (!standard && !object.schema) {
+            add(path, at, `'${object.objectType}' is not a standard object, so it needs a schema block to be created as a custom object`);
+        }
+        if (!standard && object.objectType.length > CUSTOM_OBJECT_NAME_MAX) {
+            add([...path, 'objectType'], `${at}.objectType`, `at most ${CUSTOM_OBJECT_NAME_MAX} characters; HubSpot's limit for a custom object's name`);
+        }
+        if (!standard && object.labels)
+            add([...path, 'labels'], `${at}.labels`, 'names of a custom object belong in schema.labels');
+        if (standard && object.labels) {
+            for (const which of ['singular', 'plural']) {
+                if (object.labels[which].length > CUSTOM_OBJECT_NAME_MAX) {
+                    add([...path, 'labels', which], `${at}.labels.${which}`, `at most ${CUSTOM_OBJECT_NAME_MAX} characters; HubSpot's limit for an object's names`);
+                }
+            }
+        }
+        if (object.schema) {
+            for (const which of ['singular', 'plural']) {
+                if (object.schema.labels[which].length > CUSTOM_OBJECT_NAME_MAX) {
+                    add([...path, 'schema', 'labels', which], `${at}.schema.labels.${which}`, `at most ${CUSTOM_OBJECT_NAME_MAX} characters; HubSpot's limit for a custom object's labels`);
+                }
+            }
+        }
+        const groups = new Set();
+        object.propertyGroups.forEach((group, g) => {
+            if (groups.has(group.name))
+                add([...path, 'propertyGroups', g], `${at}.propertyGroups.${group.name}`, 'declared more than once');
+            groups.add(group.name);
+            if (!options.stored && !isLowercaseGroupName(group.name)) {
+                add([...path, 'propertyGroups', g, 'name'], `${at}.propertyGroups.${group.name}`, GROUP_NAME_LOWERCASE);
+            }
+        });
+        const properties = new Set();
+        const equations = new Set();
+        object.properties.forEach((property, j) => {
+            const pat = `${at}.properties.${property.name}`;
+            const ppath = [...path, 'properties', j];
+            if (properties.has(property.name))
+                add(ppath, pat, 'declared more than once');
+            properties.add(property.name);
+            if (!groups.has(property.groupName)) {
+                add([...ppath, 'groupName'], `${pat}.groupName`, `group '${property.groupName}' is not declared in ${at}.propertyGroups`);
+            }
+            if (property.origin === 'hubspot' && !standard)
+                add([...ppath, 'origin'], `${pat}.origin`, `'hubspot' is only valid on standard objects`);
+            issues.push(...optionIssueList(pat, ppath, property));
+            issues.push(...calculationIssueList(pat, ppath, property));
+            if (isEquation(property))
+                equations.add(property.name);
+        });
+        const cycles = formulaCycles(object.properties);
+        object.properties.forEach((property, j) => {
+            const cycle = cycles.get(property.name);
+            if (!cycle)
+                return;
+            add(['objects', i, 'properties', j, 'calculationFormula'], `${at}.properties.${property.name}.calculationFormula`, cycle.length === 1
+                ? 'the formula refers to itself'
+                : `the formulas of ${cycle.join(', ')} refer to each other in a cycle, so none of them can be created first; change one of them`);
+        });
+        issues.push(...pipelineIssueList(at, path, object));
+        if (object.schema) {
+            const s = object.schema;
+            const references = [
+                ['primaryDisplayProperty', [s.primaryDisplayProperty], false],
+                ['secondaryDisplayProperties', s.secondaryDisplayProperties, true],
+                ['requiredProperties', s.requiredProperties, true],
+                ['searchableProperties', s.searchableProperties, true],
+            ];
+            for (const [field, names, indexed] of references) {
+                names.forEach((name, n) => {
+                    const fpath = indexed ? [...path, 'schema', field, n] : [...path, 'schema', field];
+                    if (!properties.has(name))
+                        add(fpath, `${at}.schema.${field}`, `'${name}' is not a property of ${object.objectType}`);
+                    else if (equations.has(name)) {
+                        add(fpath, `${at}.schema.${field}`, `'${name}' is an equation; equations are created after the object, so they cannot be part of its schema definition`);
+                    }
+                });
+            }
+        }
+    });
+    const pairs = new Set();
+    const keys = new Set();
+    bp.associations.forEach((association, a) => {
+        const { from, to, labels } = association;
+        const pair = pairId(from, to);
+        const at = `associations.${pair}`;
+        const path = ['associations', a];
+        if (pairs.has(pair))
+            add(path, at, `pair ${pair} declared more than once`);
+        pairs.add(pair);
+        for (const end of ['from', 'to']) {
+            const name = association[end];
+            if (!objectNames.has(name) && !isStandardObject(name))
+                add([...path, end], `${at}.${end}`, `'${name}' is neither a standard object nor declared in objects`);
+        }
+        if (labels.length > MAX_LABELS_PER_PAIR) {
+            add(path, at, `more than ${MAX_LABELS_PER_PAIR} labels on ${pair}; HubSpot allows at most ${MAX_LABELS_PER_PAIR} per object pair`);
+        }
+        const self = from === to;
+        // HubSpot has one unlabelled typeId on a self-pair, so one direction to limit.
+        if (self && association.inverseLimit !== undefined)
+            add([...path, 'inverseLimit'], `${at}.inverseLimit`, 'a pair of an object with itself has one limit; use limit');
+        if (self && !isStandardObject(from) && labels.length === 0)
+            add(path, at, 'a custom object can only be associated with itself through a label; add one');
+        labels.forEach((label, l) => {
+            const lat = `${at}.labels.${label.key}`;
+            const lpath = [...path, 'labels', l];
+            if (keys.has(label.key))
+                add([...lpath, 'key'], lat, 'key declared more than once');
+            keys.add(label.key);
+            // A label with one name on a self-pair has a single typeId (L4).
+            const oneTypeId = self && label.inverseLabel === undefined;
+            if (oneTypeId && label.inverseLimit !== undefined) {
+                add([...lpath, 'inverseLimit'], `${lat}.inverseLimit`, 'a label with one name on a pair of an object with itself has one limit; use limit');
+            }
+            // L4: a label may not exceed the unlabelled limit in its direction; a self-pair's one limit caps both.
+            const caps = { limit: association.limit, inverseLimit: self ? association.limit : association.inverseLimit };
+            for (const field of oneTypeId ? ['limit'] : ['limit', 'inverseLimit']) {
+                const value = label[field];
+                const cap = caps[field];
+                if (value !== undefined && cap !== undefined && value > cap) {
+                    add([...lpath, field], `${lat}.${field}`, `higher than the pair's limit (${cap}); HubSpot caps a label at the unlabelled limit in the same direction`);
+                }
+            }
+        });
+    });
+    return issues;
+}
+/**
+ * Calculated-property rules for one property (spec addendum §2). Also used by ingest to drop what a
+ * blueprint cannot hold. Formula references are checked at plan time, against the target too.
+ */
+export function calculationIssues(at, property) {
+    return calculationIssueList(at, [], property).map(issueText);
+}
+function calculationIssueList(at, path, property) {
+    const { issues, add } = collector();
+    const calculated = property.fieldType.startsWith('calculation_');
+    if (calculated && !isEquation(property)) {
+        add([...path, 'fieldType'], `${at}.fieldType`, `'${property.fieldType}' properties cannot be created through the HubSpot API; only ${EQUATION_FIELD_TYPE} is supported`);
+    }
+    if (calculated && property.origin === 'hubspot') {
+        add([...path, 'origin'], `${at}.origin`, 'HubSpot-defined calculated properties are managed by HubSpot; only custom equations can be copied');
+    }
+    if (isEquation(property)) {
+        if (property.calculationFormula === undefined)
+            add([...path, 'calculationFormula'], `${at}.calculationFormula`, `required for fieldType ${EQUATION_FIELD_TYPE}`);
+        if (!EQUATION_TYPES.includes(property.type)) {
+            add([...path, 'type'], `${at}.type`, 'equations must be number, bool, date or datetime; HubSpot cannot create text or dropdown equations through the API');
+        }
+    }
+    else if (property.calculationFormula !== undefined) {
+        add([...path, 'calculationFormula'], `${at}.calculationFormula`, `only ${EQUATION_FIELD_TYPE} properties have a formula`);
+    }
+    if (property.type !== 'number') {
+        if (property.numberDisplayHint !== undefined)
+            add([...path, 'numberDisplayHint'], `${at}.numberDisplayHint`, 'only number properties have a display hint');
+        if (property.showCurrencySymbol !== undefined)
+            add([...path, 'showCurrencySymbol'], `${at}.showCurrencySymbol`, 'only number properties show a currency symbol');
+    }
+    return issues;
+}
+/** Semantic option rules for one property. Also used by ingest to drop what a blueprint cannot hold. */
+export function optionIssues(at, property) {
+    return optionIssueList(at, [], property).map(issueText);
+}
+function optionIssueList(at, path, property) {
+    const { issues, add } = collector();
+    if (property.type !== 'enumeration' && property.options.length > 0) {
+        add([...path, 'options'], `${at}.options`, property.type === 'bool'
+            ? 'boolean properties get their fixed true/false options automatically; remove options'
+            : 'only enumeration properties have options');
+    }
+    if (property.externalOptions && property.options.length > 0) {
+        add([...path, 'options'], `${at}.options`, `externalOptions properties take their options from ${property.referencedObjectType ?? 'another object'}; remove options`);
+    }
+    const values = new Set();
+    const orders = new Set();
+    const labels = new Set();
+    property.options.forEach((option, k) => {
+        const opath = [...path, 'options', k];
+        if (labels.has(option.label))
+            add([...opath, 'label'], `${at}.options.${option.value}.label`, `label "${option.label}" is already used by another option`);
+        labels.add(option.label);
+        if (values.has(option.value))
+            add([...opath, 'value'], `${at}.options.${option.value}`, 'value declared more than once');
+        values.add(option.value);
+        if (option.displayOrder !== undefined) {
+            if (orders.has(option.displayOrder)) {
+                add([...opath, 'displayOrder'], `${at}.options.${option.value}.displayOrder`, `${option.displayOrder} is already used by another option`);
+            }
+            orders.add(option.displayOrder);
+        }
+    });
+    return issues;
+}
+const PROBABILITY = /^\d+(\.\d+)?$/;
+/** Pipeline and stage rules for one object (spec §2, quirks P1-P2). */
+export function pipelineIssues(at, object) {
+    return pipelineIssueList(at, [], object).map(issueText);
+}
+function pipelineIssueList(at, path, object) {
+    const { issues, add } = collector();
+    if (object.pipelines.length === 0)
+        return issues;
+    if (!canHavePipelines(object.objectType)) {
+        add([...path, 'pipelines'], `${at}.pipelines`, 'pipelines are only supported on deals, tickets or custom objects');
+        return issues;
+    }
+    const metadataKey = metadataKeyFor(object.objectType);
+    const keys = new Set();
+    const labels = new Set();
+    let hubspotOrigin = 0;
+    object.pipelines.forEach((pipeline, p) => {
+        const pat = `${at}.pipelines.${pipeline.key}`;
+        const ppath = [...path, 'pipelines', p];
+        if (keys.has(pipeline.key))
+            add([...ppath, 'key'], pat, `duplicate pipeline key '${pipeline.key}'`);
+        keys.add(pipeline.key);
+        if (labels.has(pipeline.label))
+            add([...ppath, 'label'], `${pat}.label`, `label "${pipeline.label}" is already used by another pipeline`);
+        labels.add(pipeline.label);
+        if (pipeline.origin === 'hubspot') {
+            if (object.objectType !== 'deals' && object.objectType !== 'tickets') {
+                add([...ppath, 'origin'], `${pat}.origin`, "'hubspot' is only valid for the default pipeline of deals and tickets (only deals and tickets ship one)");
+            }
+            else if (++hubspotOrigin === 2) {
+                add([...ppath, 'origin'], `${pat}.origin`, "at most one pipeline per object may have origin 'hubspot' (the default pipeline)");
+            }
+        }
+        const stageKeys = new Set();
+        const stageLabels = new Set();
+        pipeline.stages.forEach((stage, s) => {
+            const sat = `${pat}.stages.${stage.key}`;
+            const spath = [...ppath, 'stages', s];
+            if (stageKeys.has(stage.key))
+                add([...spath, 'key'], sat, `duplicate stage key '${stage.key}'`);
+            stageKeys.add(stage.key);
+            if (stageLabels.has(stage.label))
+                add([...spath, 'label'], `${sat}.label`, `label "${stage.label}" is already used by another stage`);
+            stageLabels.add(stage.label);
+            issues.push(...stageMetadataIssues(`${sat}.metadata`, [...spath, 'metadata'], metadataKey, stage.metadata));
+        });
+        if (object.objectType === 'tickets' && !pipeline.stages.some((stage) => isClosedStage('tickets', stage.metadata))) {
+            add([...ppath, 'stages'], `${pat}.stages`, 'a ticket pipeline needs at least one CLOSED stage');
+        }
+    });
+    return issues;
+}
+function stageMetadataIssues(at, path, expected, metadata) {
+    const { issues, add } = collector();
+    const value = metadata[expected];
+    if (value === undefined)
+        add([...path, expected], `${at}.${expected}`, 'required for stages of this object type');
+    for (const key of ['probability', 'ticketState', 'state']) {
+        if (key !== expected && metadata[key] !== undefined)
+            add([...path, key], `${at}.${key}`, `not valid here; stages of this object type use ${expected}`);
+    }
+    if (value === undefined)
+        return issues;
+    if (expected === 'probability' && !PROBABILITY.test(value)) {
+        add([...path, 'probability'], `${at}.probability`, `'${value}' must be a non-negative decimal string such as '0.5'`);
+    }
+    if (expected !== 'probability' && value !== 'OPEN' && value !== 'CLOSED') {
+        add([...path, expected], `${at}.${expected}`, `'${value}' must be OPEN or CLOSED`);
+    }
+    return issues;
+}

package/dist/engine/src/errors.d.ts

@@ -0,0 +1,40 @@
+export declare class EngineError extends Error {
+    readonly exitCode: 1 | 2;
+    constructor(message: string, exitCode: 1 | 2);
+}
+/** The blueprint (a file, an upload, or ingest output) is invalid. Nothing was read or written. */
+export declare class BlueprintError extends EngineError {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/** Token, portal or state problem, always detected before the first write. */
+export declare class EnvironmentError extends EngineError {
+    constructor(message: string);
+}
+/** The target portal changed between reviewing a plan and applying it. Nothing was written. */
+export declare class PlanChangedError extends EngineError {
+    constructor(expected: string, actual: string);
+}
+export interface HubSpotApiErrorInit {
+    method: string;
+    path: string;
+    /** 0 means the request never got a response (network failure). */
+    status: number;
+    /** Already redacted by the HTTP client. */
+    body: string;
+}
+export declare class HubSpotApiError extends EngineError {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    readonly body: string;
+    /** The summarised body: HubSpot's JSON message, otherwise the body cut to 300 characters. */
+    readonly detail: string;
+    constructor(init: HubSpotApiErrorInit);
+    /** HubSpot's machine-readable error code, when the body carries one. */
+    get errorCode(): string | undefined;
+}
+/** A command or selection names something that does not exist or is malformed. Nothing was written. */
+export declare class InputError extends EngineError {
+    constructor(message: string);
+}

package/dist/engine/src/errors.js

@@ -0,0 +1,73 @@
+export class EngineError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.name = new.target.name;
+        this.exitCode = exitCode;
+    }
+}
+/** The blueprint (a file, an upload, or ingest output) is invalid. Nothing was read or written. */
+export class BlueprintError extends EngineError {
+    issues;
+    constructor(issues) {
+        super(`invalid blueprint:\n  - ${issues.join('\n  - ')}`, 2);
+        this.issues = issues;
+    }
+}
+/** Token, portal or state problem, always detected before the first write. */
+export class EnvironmentError extends EngineError {
+    constructor(message) {
+        super(message, 2);
+    }
+}
+/** The target portal changed between reviewing a plan and applying it. Nothing was written. */
+export class PlanChangedError extends EngineError {
+    constructor(expected, actual) {
+        super(`the portal changed since this plan was reviewed (fingerprint ${expected.slice(0, 12)} → ${actual.slice(0, 12)}); review the new plan`, 1);
+    }
+}
+export class HubSpotApiError extends EngineError {
+    method;
+    path;
+    status;
+    body;
+    /** The summarised body: HubSpot's JSON message, otherwise the body cut to 300 characters. */
+    detail;
+    constructor(init) {
+        const what = init.status === 0 ? 'network error' : `HTTP ${init.status}`;
+        const detail = summarise(init.body);
+        super(`${init.method} ${init.path} → ${what}: ${detail}`, 1);
+        this.detail = detail;
+        this.method = init.method;
+        this.path = init.path;
+        this.status = init.status;
+        this.body = init.body;
+    }
+    /** HubSpot's machine-readable error code, when the body carries one. */
+    get errorCode() {
+        const json = parseJsonObject(this.body);
+        const code = json?.groupsErrorCode ?? json?.subCategory ?? json?.category;
+        return typeof code === 'string' ? code : undefined;
+    }
+}
+function parseJsonObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return value !== null && typeof value === 'object' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarise(body) {
+    const message = parseJsonObject(body)?.message;
+    if (typeof message === 'string')
+        return message;
+    return body.length > 300 ? `${body.slice(0, 300)}…` : body;
+}
+/** A command or selection names something that does not exist or is malformed. Nothing was written. */
+export class InputError extends EngineError {
+    constructor(message) {
+        super(message, 2);
+    }
+}

package/dist/provisioning/src/api/client.d.ts

@@ -0,0 +1,36 @@
+import type { CiRunView, CreateApplyResponse, CreatePlanRequest, CreatePlanResponse, KnownErrorCode } from './types.ts';
+/** The server refused, or answered something unreadable. `status` 0 is a network failure. `message` is the server's text. */
+export declare class CiApiError extends Error {
+    readonly status: number;
+    readonly code: KnownErrorCode;
+    readonly details?: unknown;
+    constructor(status: number, code: KnownErrorCode, message: string, details?: unknown);
+}
+export declare class CiTimeoutError extends Error {
+    constructor(message: string);
+}
+export interface ClientOptions {
+    baseUrl: string;
+    key: string;
+    /** @internal Test hook. */
+    fetch?: typeof fetch;
+    /** @internal Test hook. */
+    sleep?: (ms: number) => Promise<void>;
+    /** @internal Test hook. */
+    now?: () => Date;
+    /**
+     * The command's deadline: a 429 wait that would pass it, or a request still unanswered at it, throws CiTimeoutError.
+     * Without one, each request is aborted after 60 s.
+     */
+    deadline?: Date;
+}
+/** Client for the three CI endpoints (#105). The key lives in a private field and is scrubbed from everything thrown. */
+export declare class CiClient {
+    #private;
+    constructor(options: ClientOptions);
+    createPlan(body: CreatePlanRequest): Promise<CreatePlanResponse>;
+    getRun(runId: string): Promise<CiRunView>;
+    createApply(planRunId: string): Promise<CreateApplyResponse>;
+    /** Polls getRun every 5 s until status is succeeded/failed; throws CiTimeoutError after `timeoutMs`. */
+    waitForRun(runId: string, timeoutMs: number): Promise<CiRunView>;
+}