@siloy/hubspot-provisioning 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,99 @@
+import { isStandardObject } from './schema.js';
+/** Pipelines exist on deals, tickets and custom objects only (P1). */
+export function canHavePipelines(objectType) {
+    return objectType === 'deals' || objectType === 'tickets' || !isStandardObject(objectType);
+}
+/** Each object kind keeps its stage semantics under a different metadata key (P2). */
+export function metadataKeyFor(objectType) {
+    if (objectType === 'deals')
+        return 'probability';
+    if (objectType === 'tickets')
+        return 'ticketState';
+    return 'state';
+}
+/** The pipeline HubSpot ships with a portal; adopted with origin: hubspot, never created. */
+export const DEFAULT_PIPELINE_IDS = { deals: 'default', tickets: '0' };
+/** The pipeline every new portal has on deals and tickets, measured on portals A and B (docs/hubspot-quirks.md, Pipelines). */
+export const STOCK_PIPELINES = {
+    deals: {
+        id: 'default',
+        label: 'Sales Pipeline',
+        stages: [
+            { id: 'appointmentscheduled', label: 'Appointment Scheduled', metadata: { probability: '0.2' } },
+            { id: 'qualifiedtobuy', label: 'Qualified To Buy', metadata: { probability: '0.4' } },
+            { id: 'presentationscheduled', label: 'Presentation Scheduled', metadata: { probability: '0.6' } },
+            { id: 'decisionmakerboughtin', label: 'Decision Maker Bought-In', metadata: { probability: '0.8' } },
+            { id: 'contractsent', label: 'Contract Sent', metadata: { probability: '0.9' } },
+            { id: 'closedwon', label: 'Closed Won', metadata: { probability: '1.0' } },
+            { id: 'closedlost', label: 'Closed Lost', metadata: { probability: '0.0' } },
+        ],
+    },
+    tickets: {
+        id: '0',
+        label: 'Support Pipeline',
+        stages: [
+            { id: '1', label: 'New', metadata: { ticketState: 'OPEN' } },
+            { id: '2', label: 'Waiting on contact', metadata: { ticketState: 'OPEN' } },
+            { id: '3', label: 'Waiting on us', metadata: { ticketState: 'OPEN' } },
+            { id: '4', label: 'Closed', metadata: { ticketState: 'CLOSED' } },
+        ],
+    },
+};
+/**
+ * The stock pipeline as a blueprint pipeline with origin: hubspot, for the editor's "Adopt HubSpot's default
+ * pipeline". Keys are slugged from the labels, as ingest does without state; the planner matches the portal's
+ * stages by label.
+ */
+export function adoptablePipeline(objectType) {
+    const stock = STOCK_PIPELINES[objectType];
+    return {
+        key: pipelineKeySlug(stock.label, 'p'),
+        origin: 'hubspot',
+        label: stock.label,
+        stages: stock.stages.map((stage) => ({ key: pipelineKeySlug(stage.label, 's'), label: stage.label, metadata: { ...stage.metadata } })),
+    };
+}
+/** The record property holding the stage id. */
+export function stagePropertyFor(objectType) {
+    return objectType === 'deals' ? 'dealstage' : 'hs_pipeline_stage';
+}
+/** HubSpot generates one set of these per stage; they are not ours to manage. */
+export const STAGE_PROPERTY_PATTERN = /^hs_v2_(date_entered|date_exited|cumulative_time_in|latest_time_in)_(.+)$/;
+export function isStageGeneratedProperty(name) {
+    const match = STAGE_PROPERTY_PATTERN.exec(name);
+    return match !== null && match[2] !== 'current_stage';
+}
+/** Properties that pipelines and stages own, so the property engine must leave them alone. */
+export function isPipelineOwnedProperty(objectType, name) {
+    return isOptionsOwnedByPipelines(objectType, name) || isStageGeneratedProperty(name);
+}
+/** The four properties whose options are the pipelines and stages themselves. */
+export function isOptionsOwnedByPipelines(objectType, name) {
+    return name === 'hs_pipeline' || name === 'hs_pipeline_stage' || (objectType === 'deals' && (name === 'dealstage' || name === 'pipeline'));
+}
+/** A readable identifier from a label: lower case letters, digits and underscores, starting with a letter. */
+export function identifierSlug(label, prefix, fallback) {
+    const slug = label
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    if (slug === '')
+        return fallback;
+    return /^[a-z]/.test(slug) ? slug : `${prefix}_${slug}`;
+}
+/** A readable, identifier-safe key from a label. */
+export function pipelineKeySlug(label, prefix) {
+    return identifierSlug(label, prefix, prefix === 'p' ? 'p_pipeline' : 's_stage');
+}
+/** isClosed is derived by HubSpot, so we infer it from the metadata that drives it (P2). */
+export function isClosedStage(objectType, metadata) {
+    if (objectType === 'tickets')
+        return metadata.ticketState === 'CLOSED';
+    if (objectType === 'deals') {
+        const probability = Number(metadata.probability);
+        return metadata.probability !== undefined && (probability === 0 || probability === 1);
+    }
+    return metadata.state === 'CLOSED';
+}

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

@@ -0,0 +1,422 @@
+import { z } from 'zod';
+export declare const BLUEPRINT_FORMAT = "hubspot-blueprint/v1";
+/** Standard objects the engine manages, with HubSpot's fixed object type ids. */
+export declare const STANDARD_OBJECTS: {
+    readonly contacts: '0-1';
+    readonly companies: '0-2';
+    readonly deals: '0-3';
+    readonly tickets: '0-5';
+    readonly products: '0-7';
+    readonly line_items: '0-8';
+};
+export type StandardObject = keyof typeof STANDARD_OBJECTS;
+export declare function isStandardObject(name: string): name is StandardObject;
+export declare const PROPERTY_TYPES: readonly ['string', 'number', 'date', 'datetime', 'enumeration', 'bool', 'phone_number'];
+/** The only calculated kind HubSpot can read and create through the API (docs/hubspot-quirks.md, Q16). */
+export declare const EQUATION_FIELD_TYPE = "calculation_equation";
+/** Result types HubSpot accepts for an equation; text and dropdown equations are rejected (400). */
+export declare const EQUATION_TYPES: ReadonlyArray<string>;
+/** HubSpot's highest per-record association limit. */
+export declare const ASSOCIATION_LIMIT_MAX = 10000;
+export declare function isEquation(property: {
+    fieldType: string;
+}): boolean;
+/**
+ * A property group's internal name: HubSpot keeps the label's characters ('identity_&_sync_keys'), and a group with
+ * '/' cannot be read or patched after creation (docs/hubspot-quirks.md, Q18). HubSpot also rejects uppercase; that
+ * is a semantic check in validate.ts, which stored content may skip because the old identifier rule allowed it.
+ */
+export declare const GROUP_NAME_MAX = 100;
+export declare const GROUP_NAME_RULE = "must be 1 to 100 characters, without '/' or control characters";
+export declare function isGroupName(name: string): boolean;
+export declare const GROUP_NAME_LOWERCASE = "HubSpot only accepts lowercase group names";
+/** False for a name HubSpot rejects for its uppercase; such a group can only come from an old stored version. */
+export declare function isLowercaseGroupName(name: string): boolean;
+export declare const OptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    displayOrder: z.ZodOptional<z.ZodNumber>;
+    hidden: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, PropertySchema: z.ZodObject<{
+    name: z.ZodString;
+    origin: z.ZodDefault<z.ZodEnum<{
+        custom: "custom";
+        hubspot: "hubspot";
+    }>>;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        bool: "bool";
+        date: "date";
+        datetime: "datetime";
+        enumeration: "enumeration";
+        number: "number";
+        phone_number: "phone_number";
+        string: "string";
+    }>;
+    fieldType: z.ZodString;
+    groupName: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    displayOrder: z.ZodOptional<z.ZodNumber>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    formField: z.ZodOptional<z.ZodBoolean>;
+    hasUniqueValue: z.ZodDefault<z.ZodBoolean>;
+    referencedObjectType: z.ZodOptional<z.ZodString>;
+    externalOptions: z.ZodOptional<z.ZodBoolean>;
+    calculationFormula: z.ZodOptional<z.ZodString>;
+    numberDisplayHint: z.ZodOptional<z.ZodString>;
+    showCurrencySymbol: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        displayOrder: z.ZodOptional<z.ZodNumber>;
+        hidden: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, PropertyGroupSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    displayOrder: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, CustomObjectSchema: z.ZodObject<{
+    labels: z.ZodObject<{
+        singular: z.ZodString;
+        plural: z.ZodString;
+    }, z.core.$strict>;
+    description: z.ZodOptional<z.ZodString>;
+    primaryDisplayProperty: z.ZodString;
+    secondaryDisplayProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requiredProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    searchableProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, StageMetadataSchema: z.ZodObject<{
+    probability: z.ZodOptional<z.ZodString>;
+    ticketState: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, StageSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    metadata: z.ZodObject<{
+        probability: z.ZodOptional<z.ZodString>;
+        ticketState: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, PipelineSchema: z.ZodObject<{
+    key: z.ZodString;
+    origin: z.ZodDefault<z.ZodEnum<{
+        custom: "custom";
+        hubspot: "hubspot";
+    }>>;
+    label: z.ZodString;
+    displayOrder: z.ZodOptional<z.ZodNumber>;
+    stages: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        metadata: z.ZodObject<{
+            probability: z.ZodOptional<z.ZodString>;
+            ticketState: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, ObjectSchema: z.ZodObject<{
+    objectType: z.ZodString;
+    schema: z.ZodOptional<z.ZodObject<{
+        labels: z.ZodObject<{
+            singular: z.ZodString;
+            plural: z.ZodString;
+        }, z.core.$strict>;
+        description: z.ZodOptional<z.ZodString>;
+        primaryDisplayProperty: z.ZodString;
+        secondaryDisplayProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        requiredProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        searchableProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    labels: z.ZodOptional<z.ZodObject<{
+        singular: z.ZodString;
+        plural: z.ZodString;
+    }, z.core.$strict>>;
+    propertyGroups: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        displayOrder: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        origin: z.ZodDefault<z.ZodEnum<{
+            custom: "custom";
+            hubspot: "hubspot";
+        }>>;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            bool: "bool";
+            date: "date";
+            datetime: "datetime";
+            enumeration: "enumeration";
+            number: "number";
+            phone_number: "phone_number";
+            string: "string";
+        }>;
+        fieldType: z.ZodString;
+        groupName: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        displayOrder: z.ZodOptional<z.ZodNumber>;
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        formField: z.ZodOptional<z.ZodBoolean>;
+        hasUniqueValue: z.ZodDefault<z.ZodBoolean>;
+        referencedObjectType: z.ZodOptional<z.ZodString>;
+        externalOptions: z.ZodOptional<z.ZodBoolean>;
+        calculationFormula: z.ZodOptional<z.ZodString>;
+        numberDisplayHint: z.ZodOptional<z.ZodString>;
+        showCurrencySymbol: z.ZodOptional<z.ZodBoolean>;
+        options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+            hidden: z.ZodDefault<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+    pipelines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        origin: z.ZodDefault<z.ZodEnum<{
+            custom: "custom";
+            hubspot: "hubspot";
+        }>>;
+        label: z.ZodString;
+        displayOrder: z.ZodOptional<z.ZodNumber>;
+        stages: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            metadata: z.ZodObject<{
+                probability: z.ZodOptional<z.ZodString>;
+                ticketState: z.ZodOptional<z.ZodString>;
+                state: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, AssociationLabelSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    inverseLabel: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    inverseLimit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, AssociationSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    inverseLimit: z.ZodOptional<z.ZodNumber>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        inverseLabel: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        inverseLimit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, BlueprintSchema: z.ZodObject<{
+    format: z.ZodLiteral<"hubspot-blueprint/v1">;
+    source: z.ZodOptional<z.ZodObject<{
+        portalId: z.ZodNumber;
+        ingestedAt: z.ZodString;
+    }, z.core.$strict>>;
+    objects: z.ZodArray<z.ZodObject<{
+        objectType: z.ZodString;
+        schema: z.ZodOptional<z.ZodObject<{
+            labels: z.ZodObject<{
+                singular: z.ZodString;
+                plural: z.ZodString;
+            }, z.core.$strict>;
+            description: z.ZodOptional<z.ZodString>;
+            primaryDisplayProperty: z.ZodString;
+            secondaryDisplayProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            requiredProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            searchableProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        labels: z.ZodOptional<z.ZodObject<{
+            singular: z.ZodString;
+            plural: z.ZodString;
+        }, z.core.$strict>>;
+        propertyGroups: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            origin: z.ZodDefault<z.ZodEnum<{
+                custom: "custom";
+                hubspot: "hubspot";
+            }>>;
+            label: z.ZodString;
+            type: z.ZodEnum<{
+                bool: "bool";
+                date: "date";
+                datetime: "datetime";
+                enumeration: "enumeration";
+                number: "number";
+                phone_number: "phone_number";
+                string: "string";
+            }>;
+            fieldType: z.ZodString;
+            groupName: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            formField: z.ZodOptional<z.ZodBoolean>;
+            hasUniqueValue: z.ZodDefault<z.ZodBoolean>;
+            referencedObjectType: z.ZodOptional<z.ZodString>;
+            externalOptions: z.ZodOptional<z.ZodBoolean>;
+            calculationFormula: z.ZodOptional<z.ZodString>;
+            numberDisplayHint: z.ZodOptional<z.ZodString>;
+            showCurrencySymbol: z.ZodOptional<z.ZodBoolean>;
+            options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+                displayOrder: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodDefault<z.ZodBoolean>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>>;
+        pipelines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            origin: z.ZodDefault<z.ZodEnum<{
+                custom: "custom";
+                hubspot: "hubspot";
+            }>>;
+            label: z.ZodString;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+            stages: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodString;
+                metadata: z.ZodObject<{
+                    probability: z.ZodOptional<z.ZodString>;
+                    ticketState: z.ZodOptional<z.ZodString>;
+                    state: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    associations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        inverseLimit: z.ZodOptional<z.ZodNumber>;
+        labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            inverseLabel: z.ZodOptional<z.ZodString>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            inverseLimit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** What the editor's forms can render (spec #27 §4.3). Never used to accept a version. */
+export declare const DraftBlueprintSchema: z.ZodObject<{
+    format: z.ZodLiteral<"hubspot-blueprint/v1">;
+    source: z.ZodOptional<z.ZodObject<{
+        portalId: z.ZodNumber;
+        ingestedAt: z.ZodString;
+    }, z.core.$strict>>;
+    objects: z.ZodArray<z.ZodObject<{
+        objectType: z.ZodString;
+        schema: z.ZodOptional<z.ZodObject<{
+            labels: z.ZodObject<{
+                singular: z.ZodString;
+                plural: z.ZodString;
+            }, z.core.$strict>;
+            description: z.ZodOptional<z.ZodString>;
+            primaryDisplayProperty: z.ZodString;
+            secondaryDisplayProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            requiredProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            searchableProperties: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        labels: z.ZodOptional<z.ZodObject<{
+            singular: z.ZodString;
+            plural: z.ZodString;
+        }, z.core.$strict>>;
+        propertyGroups: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            origin: z.ZodDefault<z.ZodEnum<{
+                custom: "custom";
+                hubspot: "hubspot";
+            }>>;
+            label: z.ZodString;
+            type: z.ZodEnum<{
+                bool: "bool";
+                date: "date";
+                datetime: "datetime";
+                enumeration: "enumeration";
+                number: "number";
+                phone_number: "phone_number";
+                string: "string";
+            }>;
+            fieldType: z.ZodString;
+            groupName: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            formField: z.ZodOptional<z.ZodBoolean>;
+            hasUniqueValue: z.ZodDefault<z.ZodBoolean>;
+            referencedObjectType: z.ZodOptional<z.ZodString>;
+            externalOptions: z.ZodOptional<z.ZodBoolean>;
+            calculationFormula: z.ZodOptional<z.ZodString>;
+            numberDisplayHint: z.ZodOptional<z.ZodString>;
+            showCurrencySymbol: z.ZodOptional<z.ZodBoolean>;
+            options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+                displayOrder: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodDefault<z.ZodBoolean>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>>;
+        pipelines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            origin: z.ZodDefault<z.ZodEnum<{
+                custom: "custom";
+                hubspot: "hubspot";
+            }>>;
+            label: z.ZodString;
+            displayOrder: z.ZodOptional<z.ZodNumber>;
+            stages: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodString;
+                metadata: z.ZodObject<{
+                    probability: z.ZodOptional<z.ZodString>;
+                    ticketState: z.ZodOptional<z.ZodString>;
+                    state: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    associations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        inverseLimit: z.ZodOptional<z.ZodNumber>;
+        labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            inverseLabel: z.ZodOptional<z.ZodString>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            inverseLimit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type Blueprint = z.output<typeof BlueprintSchema>;
+/** An editor draft: the shape of a Blueprint, not yet valid. */
+export type DraftBlueprint = z.output<typeof DraftBlueprintSchema>;
+export type BlueprintObject = Blueprint['objects'][number];
+export type CustomObjectDefinition = NonNullable<BlueprintObject['schema']>;
+export type PropertyGroup = BlueprintObject['propertyGroups'][number];
+export type Property = BlueprintObject['properties'][number];
+export type BlueprintOption = Property['options'][number];
+/** An object pair, with its labels nested. */
+export type Association = Blueprint['associations'][number];
+export type AssociationLabel = Association['labels'][number];
+export type PropertyType = (typeof PROPERTY_TYPES)[number];
+export type Pipeline = BlueprintObject['pipelines'][number];
+export type Stage = Pipeline['stages'][number];
+export type StageMetadata = Stage['metadata'];

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

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+export const BLUEPRINT_FORMAT = 'hubspot-blueprint/v1';
+/** Standard objects the engine manages, with HubSpot's fixed object type ids. */
+export const STANDARD_OBJECTS = {
+    contacts: '0-1',
+    companies: '0-2',
+    deals: '0-3',
+    tickets: '0-5',
+    products: '0-7',
+    line_items: '0-8',
+};
+export function isStandardObject(name) {
+    return Object.hasOwn(STANDARD_OBJECTS, name);
+}
+export const PROPERTY_TYPES = ['string', 'number', 'date', 'datetime', 'enumeration', 'bool', 'phone_number'];
+/** The only calculated kind HubSpot can read and create through the API (docs/hubspot-quirks.md, Q16). */
+export const EQUATION_FIELD_TYPE = 'calculation_equation';
+/** Result types HubSpot accepts for an equation; text and dropdown equations are rejected (400). */
+export const EQUATION_TYPES = ['number', 'bool', 'date', 'datetime'];
+/** HubSpot's highest per-record association limit. */
+export const ASSOCIATION_LIMIT_MAX = 10000;
+export function isEquation(property) {
+    return property.fieldType === EQUATION_FIELD_TYPE;
+}
+const strictIdentifier = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'must start with a letter and contain only letters, digits and underscores');
+/**
+ * A property group's internal name: HubSpot keeps the label's characters ('identity_&_sync_keys'), and a group with
+ * '/' cannot be read or patched after creation (docs/hubspot-quirks.md, Q18). HubSpot also rejects uppercase; that
+ * is a semantic check in validate.ts, which stored content may skip because the old identifier rule allowed it.
+ */
+export const GROUP_NAME_MAX = 100;
+const GROUP_NAME = new RegExp(`^[^/\\u0000-\\u001f\\u007f-\\u009f]{1,${GROUP_NAME_MAX}}$`);
+export const GROUP_NAME_RULE = `must be 1 to ${GROUP_NAME_MAX} characters, without '/' or control characters`;
+export function isGroupName(name) {
+    return GROUP_NAME.test(name);
+}
+export const GROUP_NAME_LOWERCASE = 'HubSpot only accepts lowercase group names';
+/** False for a name HubSpot rejects for its uppercase; such a group can only come from an old stored version. */
+export function isLowercaseGroupName(name) {
+    return name === name.toLowerCase();
+}
+const strictGroupName = z.string().regex(GROUP_NAME, GROUP_NAME_RULE);
+const strictText = z.string().min(1);
+const LIMIT_MESSAGE = `a limit is a whole number from 1 to ${ASSOCIATION_LIMIT_MAX}`;
+const strictLimit = z.number().int(LIMIT_MESSAGE).min(1, LIMIT_MESSAGE).max(ASSOCIATION_LIMIT_MAX, LIMIT_MESSAGE);
+/**
+ * Builds the blueprint schemas. `draft`: the same structure with plain strings and no minimum stage count,
+ * so an editor draft with an empty label or a pipeline without stages still parses (spec #27 §4.3).
+ */
+function buildSchemas(draft) {
+    const identifier = draft ? z.string() : strictIdentifier;
+    const groupName = draft ? z.string() : strictGroupName;
+    const text = draft ? z.string() : strictText;
+    const limit = draft ? z.number() : strictLimit;
+    const OptionSchema = z.strictObject({
+        value: text,
+        label: text,
+        displayOrder: z.number().int().optional(),
+        hidden: z.boolean().default(false),
+        description: z.string().optional(),
+    });
+    const PropertySchema = z.strictObject({
+        name: identifier,
+        /** custom: created by us. hubspot: a HubSpot-defined property we take over (patch only, never create). */
+        origin: z.enum(['custom', 'hubspot']).default('custom'),
+        label: text,
+        type: z.enum(PROPERTY_TYPES),
+        fieldType: text,
+        groupName,
+        description: z.string().optional(),
+        displayOrder: z.number().int().optional(),
+        hidden: z.boolean().optional(),
+        formField: z.boolean().optional(),
+        hasUniqueValue: z.boolean().default(false),
+        referencedObjectType: z.string().optional(),
+        externalOptions: z.boolean().optional(),
+        /** calculation_equation only (and then required). Refers to properties of the same object by name. */
+        calculationFormula: text.optional(),
+        /** number only. Omitted = unmanaged. */
+        numberDisplayHint: text.optional(),
+        /** number only. Omitted = unmanaged. */
+        showCurrencySymbol: z.boolean().optional(),
+        options: z.array(OptionSchema).default([]),
+    });
+    const PropertyGroupSchema = z.strictObject({
+        name: groupName,
+        label: text,
+        displayOrder: z.number().int().optional(),
+    });
+    const CustomObjectSchema = z.strictObject({
+        labels: z.strictObject({ singular: text, plural: text }),
+        description: z.string().optional(),
+        primaryDisplayProperty: identifier,
+        /** Ordered: renders left-to-right on a record. */
+        secondaryDisplayProperties: z.array(identifier).default([]),
+        /** Sets: order is meaningless. */
+        requiredProperties: z.array(identifier).default([]),
+        searchableProperties: z.array(identifier).default([]),
+    });
+    /** Which key is meaningful depends on the object kind (see pipelines.ts); validate.ts enforces that. */
+    const StageMetadataSchema = z.strictObject({
+        probability: text.optional(),
+        ticketState: text.optional(),
+        state: text.optional(),
+    });
+    /** Stage order is the array order; there is deliberately no displayOrder. */
+    const StageSchema = z.strictObject({
+        key: identifier,
+        label: text,
+        metadata: StageMetadataSchema,
+    });
+    const PipelineSchema = z.strictObject({
+        key: identifier,
+        /** custom: created by us. hubspot: the portal's default pipeline, adopted (deals and tickets only). */
+        origin: z.enum(['custom', 'hubspot']).default('custom'),
+        label: text,
+        displayOrder: z.number().int().optional(),
+        stages: draft ? z.array(StageSchema) : z.array(StageSchema).min(1, 'a pipeline needs at least one stage'),
+    });
+    const ObjectSchema = z.strictObject({
+        objectType: identifier,
+        schema: CustomObjectSchema.optional(),
+        /** Standard objects only: the names HubSpot's were changed to in the portal. */
+        labels: z.strictObject({ singular: text, plural: text }).optional(),
+        propertyGroups: z.array(PropertyGroupSchema).default([]),
+        properties: z.array(PropertySchema).default([]),
+        pipelines: z.array(PipelineSchema).default([]),
+    });
+    /** A label of a pair. `label` reads from the pair's `from` side, `inverseLabel` from its `to` side. */
+    const AssociationLabelSchema = z.strictObject({
+        /** Stable, portal-agnostic identity; also the write-only internal `name` sent on create. */
+        key: identifier,
+        label: text,
+        inverseLabel: text.optional(),
+        /** Most `to` records one `from` record can have through this label. Absent: no limit. */
+        limit: limit.optional(),
+        inverseLimit: limit.optional(),
+    });
+    /** One entry per unordered object pair; a self-pair (from = to) is allowed. */
+    const AssociationSchema = z.strictObject({
+        from: identifier,
+        to: identifier,
+        /** Limits of the unlabelled association, per direction. Absent: no limit (not unmanaged). */
+        limit: limit.optional(),
+        inverseLimit: limit.optional(),
+        labels: z.array(AssociationLabelSchema).default([]),
+    });
+    const BlueprintSchema = z.strictObject({
+        format: z.literal(BLUEPRINT_FORMAT),
+        source: z.strictObject({ portalId: z.number().int(), ingestedAt: z.string() }).optional(),
+        objects: z.array(ObjectSchema),
+        associations: z.array(AssociationSchema).default([]),
+    });
+    return {
+        OptionSchema, PropertySchema, PropertyGroupSchema, CustomObjectSchema, StageMetadataSchema, StageSchema,
+        PipelineSchema, ObjectSchema, AssociationLabelSchema, AssociationSchema, BlueprintSchema,
+    };
+}
+export const { OptionSchema, PropertySchema, PropertyGroupSchema, CustomObjectSchema, StageMetadataSchema, StageSchema, PipelineSchema, ObjectSchema, AssociationLabelSchema, AssociationSchema, BlueprintSchema, } = buildSchemas(false);
+/** What the editor's forms can render (spec #27 §4.3). Never used to accept a version. */
+export const DraftBlueprintSchema = buildSchemas(true).BlueprintSchema;