@siloy/hubspot-provisioning 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siloy Benelux B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# @siloy/hubspot-provisioning
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Validate a HubSpot provisioning blueprint offline, preview it on pull requests, and deploy it from CI. The blueprint lives in your integration repo as `blueprint.yaml`; the provisioning app plans and applies it on the HubSpot portal your deploy key is bound to.
+
+Requires Node 20 or newer.
+
+## Install
+
+```sh
+npx -y @siloy/hubspot-provisioning@0.1.1 validate
+```
+
+In CI, run this pinned `npx` form (see "GitHub Actions"); don't install the CLI as a repo dependency in a job that has the deploy key. For editor support of the schema, a local install is fine: `npm install --save-dev @siloy/hubspot-provisioning`.
+
+## Commands
+
+```
+hubspot-provisioning validate [file] [--targets <json>]
+hubspot-provisioning plan [file] --mode preview|deploy [--targets <json>] [--comment-file <path>]
+                          [--sha <sha>] [--ref <ref>] [--ci-run-url <url>] [--timeout <minutes>]
+hubspot-provisioning apply --plan-run <runId> [--timeout <minutes>]
+hubspot-provisioning deploy [file] [plan options except --mode]
+```
+
+`file` defaults to `blueprint.yaml`.
+
+| Command | What it does |
+| --- | --- |
+| `validate` | Checks the blueprint offline, with the same rules as the server. Needs no URL or key. |
+| `plan` | Sends the blueprint to the provisioning app, waits for the plan and prints it. `--mode preview` changes nothing and can never be applied; `--mode deploy` makes a plan that `apply` can apply. |
+| `apply` | Applies a deploy plan made by the same key (`--plan-run` is the plan's run id, printed by `plan`). |
+| `deploy` | `plan --mode deploy`, then `apply` when the plan can be applied. Exits 0 without applying when the portal already matches ("nothing to apply"). |
+
+| Flag | Meaning |
+| --- | --- |
+| `--targets <json>` | A JSON file of mapping targets that must exist in the blueprint or in HubSpot: `[{ "objectType": "contacts", "properties": ["cc_sync_number"] }]`. A target found nowhere blocks the plan. With `validate`, targets assumed to exist in HubSpot are listed. |
+| `--comment-file <path>` | Writes the plan as a Markdown comment for a pull request. Also written when the command fails: an invalid blueprint (with its issues), a missing setting, a server refusal or a timeout. The comment starts with `<!-- hubspot-provisioning -->`. A comment that cannot be written is reported on stderr and does not change the exit code. |
+| `--sha`, `--ref`, `--ci-run-url` | The commit the plan belongs to. Default to `GITHUB_SHA`, `GITHUB_REF` and the URL of the Actions run. |
+| `--timeout <minutes>` | Give up waiting after this long. Default 15, at most 360. Each request counts against it, so a server that stops answering cannot hold the job longer. |
+| `--help`, `--version` | |
+
+### Commit info on pull requests
+
+On a `pull_request` event, `GITHUB_SHA` and `GITHUB_REF` are the merge commit and `refs/pull/N/merge`, not your branch. That is what the plan is recorded under unless you pass the head yourself:
+
+```yaml
+- run: npx -y @siloy/hubspot-provisioning@0.1.1 plan --mode preview --sha "$HEAD_SHA" --ref "$HEAD_REF"
+  env:
+    npm_config_registry: https://registry.npmjs.org
+    HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+    HEAD_REF: ${{ github.head_ref }}
+```
+
+Pass them through `env:`, never inline in the `run:` text: a branch name is attacker-controlled and would be run as shell.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success: the blueprint is valid, the plan is deployable (or there is nothing to change), the apply succeeded. |
+| 1 | The blueprint is invalid or over 5 MiB, the server refused the request, the wait timed out, or the plan cannot be deployed (conflicts, updates that would overwrite hand edits in HubSpot, missing mapping targets, a failed run). |
+| 2 | Usage or configuration error: unknown command or flag, a missing or non-https `PROVISIONING_URL`, a missing `PROVISIONING_KEY`, an unreadable file, no commit sha or ref. |
+
+## Configuration
+
+| Variable | Value |
+| --- | --- |
+| `PROVISIONING_URL` | The provisioning app's URL, for example `https://provisioning.example.com`. Must be `https://`; plain `http://` is accepted only for `localhost`, `127.0.0.1` and `[::1]`. |
+| `PROVISIONING_KEY` | The deploy key's secret (`hspk_...`). Store it as a CI secret, never in the repo. |
+
+`validate` needs neither. The key is scrubbed from everything the CLI prints.
+
+## Getting a deploy key
+
+A deploy key belongs to a workspace and is bound to one portal and blueprint. A workspace owner creates it on the blueprint page in the provisioning app and either:
+
+- copies the secret and puts it in the repo's CI secrets, or
+- chooses "Create a link for a developer" and sends you the link. The link works once and expires. Open it, click "Reveal secret" and copy the `hspk_` secret into the repo's CI secrets. If the link expired unused, ask the owner for a new one. If it was already opened (by you or someone else), the owner revokes the key and creates a new one.
+
+### Expiry
+
+A key expires after 90 days without use, counted from its last use, creation or reactivation. An expired key gets `deploy_key_expired`. A workspace owner reactivates it on the blueprint page; the secret stays the same, so nothing changes in your CI secrets. A revoked key never comes back.
+
+## GitHub Actions
+
+Preview on pull requests (with a comment that is updated, not repeated) and deploy on pushes to `main`. Pin the actions by commit SHA as your own policy requires; versions are shown here for readability. The samples pin 0.1.1; pin the version you use and bump it on purpose.
+
+```yaml
+# .github/workflows/blueprint.yml
+name: blueprint
+on:
+  pull_request:
+    paths: [blueprint.yaml]
+  push:
+    branches: [main]
+    paths: [blueprint.yaml]
+
+jobs:
+  preview:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      # No npm ci: the job holds the deploy key, so it runs only the pinned CLI, never the branch's dependencies.
+      # npm_config_registry outranks a project .npmrc, so a branch cannot point npx at another registry.
+      - run: npx -y @siloy/hubspot-provisioning@0.1.1 validate
+        env:
+          npm_config_registry: https://registry.npmjs.org
+      - run: >-
+          npx -y @siloy/hubspot-provisioning@0.1.1 plan --mode preview
+          --comment-file plan-comment.md
+          --sha "$HEAD_SHA" --ref "$HEAD_REF"
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          HEAD_REF: ${{ github.head_ref }}
+          npm_config_registry: https://registry.npmjs.org
+          PROVISIONING_URL: ${{ vars.PROVISIONING_URL }}
+          PROVISIONING_KEY: ${{ secrets.PROVISIONING_KEY }}
+      # Runs also when the plan failed or was refused: the comment says why.
+      - name: Post the plan on the pull request
+        if: always() && hashFiles('plan-comment.md') != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          # Update this workflow's earlier comment (by the Actions bot, starting with the marker), else create one.
+          id=$(gh api --paginate "repos/${GITHUB_REPOSITORY}/issues/${PR}/comments" \
+            --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("<!-- hubspot-provisioning -->"))) | .id' | head -n 1)
+          if [ -n "$id" ]; then
+            gh api --method PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${id}" -F body=@plan-comment.md
+          else
+            gh api --method POST "repos/${GITHUB_REPOSITORY}/issues/${PR}/comments" -F body=@plan-comment.md
+          fi
+
+  deploy:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency: blueprint-deploy
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npx -y @siloy/hubspot-provisioning@0.1.1 deploy
+        env:
+          npm_config_registry: https://registry.npmjs.org
+          PROVISIONING_URL: ${{ vars.PROVISIONING_URL }}
+          PROVISIONING_KEY: ${{ secrets.PROVISIONING_KEY }}
+```
+
+Notes:
+
+- Pull requests from forks get no secrets (`plan` exits 2) and a read-only token (the comment step fails), so the preview job runs only for branches in the same repository.
+- The samples pin the CLI's version and its registry (`npm_config_registry`) and do not install the repo's dependencies, so a branch cannot swap the CLI through the repo's dependencies or npm config. Anyone who can push a branch can still change the workflow itself: see "Trust boundary".
+
+On a push, `GITHUB_SHA` and `GITHUB_REF` are the pushed commit and branch, so `deploy` needs no commit flags.
+
+A deploy that would overwrite something someone changed by hand in HubSpot is refused (exit 1) and the output lists what changed. Adopt HubSpot's values in `blueprint.yaml` and deploy again.
+
+### Trust boundary
+
+`PROVISIONING_KEY` is like any GitHub secret: anyone who can push a branch to the integration repo can change the workflow on that branch and use the key. Keep write access to the integration repo to trusted developers. A key can deploy as well as preview, so a preview job's key could also deploy to its portal; a preview-only key is planned.
+
+## Editor support
+
+The package ships a JSON Schema for the blueprint. In VS Code with the YAML extension, add this as the first line of `blueprint.yaml`:
+
+```yaml
+# yaml-language-server: $schema=node_modules/@siloy/hubspot-provisioning/schema/blueprint.schema.json
+```
+
+or set it in `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "./node_modules/@siloy/hubspot-provisioning/schema/blueprint.schema.json": "blueprint.yaml"
+  }
+}
+```
+
+The schema is also available as `@siloy/hubspot-provisioning/schema.json`. It describes the shape; `validate` applies the full rules.
+
+## Upgrading
+
+When the blueprint rules change, the server may refuse older CLIs with `cli_outdated`. Upgrade with `npm install --save-dev @siloy/hubspot-provisioning@latest`, or raise the version in your workflow's `npx -y @siloy/hubspot-provisioning@0.1.1`.
+
+When a command fails after the server created a run, it prints `Plan run:` and `Apply run:` ids; look them up in the provisioning app. After a timeout or error while waiting for an apply, the apply may still be running: check it before re-running.
+
+## As a library
+
+The package also exports the offline validation (`validateBlueprintText`, `checkMappingTargets`) and a client for the CI API (`CiClient`, `CiApiError`, `CiTimeoutError` and the request and response types). The command-line output and comment rendering are internal.

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

@@ -0,0 +1,17 @@
+import type { Association, AssociationLabel } from './schema.ts';
+/** A label with the ends of its pair: `label` reads from `from`. The unit most consumers iterate. */
+export interface LabelEntry extends AssociationLabel {
+    from: string;
+    to: string;
+}
+/** Every label of every pair, in pair order, then label order. */
+export declare function labelEntries(associations: readonly Association[]): LabelEntry[];
+/** An unordered pair's name: its ends sorted, `a<->b`. */
+export declare function pairId(a: string, b: string): string;
+/** The pair entry for two objects in either order; `reversed` when it is written `b` → `a`. */
+export declare function findPair(associations: readonly Association[], a: string, b: string): {
+    pair: Association;
+    reversed: boolean;
+} | undefined;
+/** One direction's limit in words: "deals → projects: at most 1 per record". */
+export declare function describeLimit(from: string, to: string, max: number | undefined): string;

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

@@ -0,0 +1,22 @@
+/** Every label of every pair, in pair order, then label order. */
+export function labelEntries(associations) {
+    return associations.flatMap(({ from, to, labels }) => labels.map((label) => ({ ...label, from, to })));
+}
+/** An unordered pair's name: its ends sorted, `a<->b`. */
+export function pairId(a, b) {
+    return [a, b].sort().join('<->');
+}
+/** The pair entry for two objects in either order; `reversed` when it is written `b` → `a`. */
+export function findPair(associations, a, b) {
+    for (const pair of associations) {
+        if (pair.from === a && pair.to === b)
+            return { pair, reversed: false };
+        if (pair.from === b && pair.to === a)
+            return { pair, reversed: true };
+    }
+    return undefined;
+}
+/** One direction's limit in words: "deals → projects: at most 1 per record". */
+export function describeLimit(from, to, max) {
+    return `${from} → ${to}: ${max === undefined ? 'no limit' : `at most ${max} per record`}`;
+}

package/dist/engine/src/blueprint/field-types.d.ts

@@ -0,0 +1,14 @@
+import { type PropertyType } from './schema.ts';
+export type FieldTypeId = 'text' | 'textarea' | 'html' | 'file' | 'phone' | 'number' | 'date' | 'datetime' | 'select' | 'radio' | 'checkbox' | 'booleancheckbox' | 'equation';
+export interface FieldTypeChoice {
+    id: FieldTypeId;
+    label: string;
+    type: PropertyType;
+    fieldType: string;
+}
+/** The editor's "Field type" picker (spec #28 §5.4): one choice sets type and fieldType together, like HubSpot's form. */
+export declare const FIELD_TYPES: readonly FieldTypeChoice[];
+export declare function fieldTypeOf(property: {
+    type: string;
+    fieldType: string;
+}): FieldTypeChoice | undefined;

package/dist/engine/src/blueprint/field-types.js

@@ -0,0 +1,22 @@
+import { EQUATION_FIELD_TYPE } from './schema.js';
+/** The editor's "Field type" picker (spec #28 §5.4): one choice sets type and fieldType together, like HubSpot's form. */
+export const FIELD_TYPES = [
+    { id: 'text', label: 'Single-line text', type: 'string', fieldType: 'text' },
+    { id: 'textarea', label: 'Multi-line text', type: 'string', fieldType: 'textarea' },
+    { id: 'html', label: 'Rich text', type: 'string', fieldType: 'html' },
+    { id: 'file', label: 'File', type: 'string', fieldType: 'file' },
+    { id: 'phone', label: 'Phone number', type: 'phone_number', fieldType: 'phonenumber' },
+    { id: 'number', label: 'Number', type: 'number', fieldType: 'number' },
+    { id: 'date', label: 'Date', type: 'date', fieldType: 'date' },
+    { id: 'datetime', label: 'Date and time', type: 'datetime', fieldType: 'date' },
+    { id: 'select', label: 'Dropdown select', type: 'enumeration', fieldType: 'select' },
+    { id: 'radio', label: 'Radio select', type: 'enumeration', fieldType: 'radio' },
+    { id: 'checkbox', label: 'Multiple checkboxes', type: 'enumeration', fieldType: 'checkbox' },
+    { id: 'booleancheckbox', label: 'Single checkbox', type: 'bool', fieldType: 'booleancheckbox' },
+    { id: 'equation', label: 'Equation', type: 'number', fieldType: EQUATION_FIELD_TYPE },
+];
+export function fieldTypeOf(property) {
+    if (property.fieldType === EQUATION_FIELD_TYPE)
+        return FIELD_TYPES.find((c) => c.id === 'equation');
+    return FIELD_TYPES.find((c) => c.type === property.type && c.fieldType === property.fieldType);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * The property names a HubSpot calculation formula refers to, without duplicates (spec addendum
+ * §4.1). Lexical on purpose: identifiers outside double-quoted strings, minus keywords (any case)
+ * and anything immediately followed by `(` (a function call). There is no function list to keep in
+ * sync. It fails closed: whether a backslash escapes the next character in a string is unverified,
+ * so both readings are scanned and the union returned; an unterminated string is scanned as code.
+ * A mistake only ever over-reports, which the planner turns into a conflict. The order is
+ * deterministic but not strictly first use: the names of the backslash-escapes reading in order of
+ * first use, then any names only the other reading finds.
+ */
+export declare function formulaReferences(formula: string): string[];
+/**
+ * `formula` with every reference to `from` renamed to `to` (spec #28 §5.7). Only where both string readings
+ * agree the name is code, so text inside a string is never changed; a reference left alone stays visible
+ * in the editor's Uses list.
+ */
+export declare function renameInFormula(formula: string, from: string, to: string): string;
+/**
+ * Properties whose formulas refer to each other in a cycle, each with the names in its cycle (input order).
+ * HubSpot can create none of them first. References to names outside `properties` are ignored.
+ */
+export declare function formulaCycles(properties: ReadonlyArray<{
+    name: string;
+    calculationFormula?: string;
+}>): Map<string, string[]>;

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

@@ -0,0 +1,106 @@
+const KEYWORDS = new Set(['if', 'then', 'else', 'elseif', 'endif', 'and', 'or', 'not', 'true', 'false']);
+const IDENTIFIER_START = /[A-Za-z_]/;
+const IDENTIFIER_PART = /[A-Za-z0-9_]/;
+/**
+ * The property names a HubSpot calculation formula refers to, without duplicates (spec addendum
+ * §4.1). Lexical on purpose: identifiers outside double-quoted strings, minus keywords (any case)
+ * and anything immediately followed by `(` (a function call). There is no function list to keep in
+ * sync. It fails closed: whether a backslash escapes the next character in a string is unverified,
+ * so both readings are scanned and the union returned; an unterminated string is scanned as code.
+ * A mistake only ever over-reports, which the planner turns into a conflict. The order is
+ * deterministic but not strictly first use: the names of the backslash-escapes reading in order of
+ * first use, then any names only the other reading finds.
+ */
+export function formulaReferences(formula) {
+    return [...new Set([...scan(formula, true), ...scan(formula, false)])];
+}
+/** Identifier tokens that are property references under one reading of string escapes. */
+function identifierSpans(formula, backslashEscapes) {
+    const spans = [];
+    let i = 0;
+    while (i < formula.length) {
+        const ch = formula[i];
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < formula.length && formula[j] !== '"')
+                j += backslashEscapes && formula[j] === '\\' ? 2 : 1;
+            // No closing quote: the quote is an ordinary character and the rest is code.
+            i = j < formula.length ? j + 1 : i + 1;
+        }
+        else if (IDENTIFIER_START.test(ch)) {
+            let end = i + 1;
+            while (end < formula.length && IDENTIFIER_PART.test(formula[end]))
+                end++;
+            const word = formula.slice(i, end);
+            if (formula[end] !== '(' && !KEYWORDS.has(word.toLowerCase()))
+                spans.push({ start: i, end, word });
+            i = end;
+        }
+        else if (/[0-9]/.test(ch)) {
+            i = skipNumber(formula, i);
+        }
+        else {
+            i++;
+        }
+    }
+    return spans;
+}
+function scan(formula, backslashEscapes) {
+    return [...new Set(identifierSpans(formula, backslashEscapes).map((s) => s.word))];
+}
+/**
+ * `formula` with every reference to `from` renamed to `to` (spec #28 §5.7). Only where both string readings
+ * agree the name is code, so text inside a string is never changed; a reference left alone stays visible
+ * in the editor's Uses list.
+ */
+export function renameInFormula(formula, from, to) {
+    const other = new Set(identifierSpans(formula, false).filter((s) => s.word === from).map((s) => s.start));
+    const spans = identifierSpans(formula, true).filter((s) => s.word === from && other.has(s.start));
+    let out = formula;
+    for (const s of spans.reverse())
+        out = out.slice(0, s.start) + to + out.slice(s.end);
+    return out;
+}
+/** Whether `goal` is reachable from `from` through formula references. */
+function reaches(formulas, from, goal, seen) {
+    for (const next of formulas.get(from) ?? []) {
+        if (next === goal)
+            return true;
+        if (seen.has(next))
+            continue;
+        seen.add(next);
+        if (reaches(formulas, next, goal, seen))
+            return true;
+    }
+    return false;
+}
+/**
+ * Properties whose formulas refer to each other in a cycle, each with the names in its cycle (input order).
+ * HubSpot can create none of them first. References to names outside `properties` are ignored.
+ */
+export function formulaCycles(properties) {
+    const formulas = new Map();
+    for (const p of properties)
+        if (p.calculationFormula !== undefined)
+            formulas.set(p.name, formulaReferences(p.calculationFormula));
+    const cyclic = [...formulas.keys()].filter((name) => reaches(formulas, name, name, new Set()));
+    const cycles = new Map();
+    for (const name of cyclic) {
+        cycles.set(name, cyclic.filter((other) => other === name || (reaches(formulas, name, other, new Set()) && reaches(formulas, other, name, new Set()))));
+    }
+    return cycles;
+}
+/** A number is digits and dots; an exponent marker belongs to it only when a digit or sign follows. */
+function skipNumber(formula, start) {
+    let i = start;
+    while (i < formula.length) {
+        const c = formula[i];
+        if (/[0-9.]/.test(c))
+            i++;
+        else if ((c === 'e' || c === 'E') && /[0-9+-]/.test(formula[i + 1] ?? ''))
+            i += 2;
+        else
+            break;
+    }
+    return i;
+}

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

@@ -0,0 +1,16 @@
+import type { StandardObject } from './schema.ts';
+/** HubSpot rejects longer custom object names and labels (400 OBJECT_TYPE_NAME_LENGTH, Q12). */
+export declare const CUSTOM_OBJECT_NAME_MAX = 50;
+/** The group HubSpot creates with a custom object (Q12): the name lowercased, whatever its case. */
+export declare function defaultGroupName(objectType: string): string;
+export declare function defaultGroupLabel(singular: string): string;
+/** Each standard object's main group, measured on portals A and B (Q12). No underscore, unlike custom objects. */
+export declare const STOCK_PROPERTY_GROUPS: Record<StandardObject, {
+    name: string;
+    label: string;
+}>;
+/**
+ * Common HubSpot-defined property names, for an editor warning only. Not complete and not meant to be:
+ * the planner's origin conflict is the real check (spec #28 §4.1).
+ */
+export declare const STOCK_PROPERTY_NAMES: Record<StandardObject, readonly string[]>;

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

@@ -0,0 +1,30 @@
+/** HubSpot rejects longer custom object names and labels (400 OBJECT_TYPE_NAME_LENGTH, Q12). */
+export const CUSTOM_OBJECT_NAME_MAX = 50;
+/** The group HubSpot creates with a custom object (Q12): the name lowercased, whatever its case. */
+export function defaultGroupName(objectType) {
+    return `${objectType.toLowerCase()}_information`;
+}
+export function defaultGroupLabel(singular) {
+    return `${singular} Information`;
+}
+/** Each standard object's main group, measured on portals A and B (Q12). No underscore, unlike custom objects. */
+export const STOCK_PROPERTY_GROUPS = {
+    contacts: { name: 'contactinformation', label: 'Contact information' },
+    companies: { name: 'companyinformation', label: 'Company information' },
+    deals: { name: 'dealinformation', label: 'Deal information' },
+    tickets: { name: 'ticketinformation', label: 'Ticket information' },
+    products: { name: 'productinformation', label: 'Product information' },
+    line_items: { name: 'lineiteminformation', label: 'Line item information' },
+};
+/**
+ * Common HubSpot-defined property names, for an editor warning only. Not complete and not meant to be:
+ * the planner's origin conflict is the real check (spec #28 §4.1).
+ */
+export const STOCK_PROPERTY_NAMES = {
+    contacts: ['email', 'firstname', 'lastname', 'phone', 'mobilephone', 'company', 'jobtitle', 'address', 'city', 'state', 'zip', 'country', 'website', 'lifecyclestage', 'hubspot_owner_id'],
+    companies: ['name', 'domain', 'phone', 'address', 'city', 'state', 'zip', 'country', 'industry', 'website', 'numberofemployees', 'annualrevenue', 'description', 'hubspot_owner_id'],
+    deals: ['dealname', 'amount', 'closedate', 'dealstage', 'pipeline', 'dealtype', 'description', 'hubspot_owner_id'],
+    tickets: ['subject', 'content', 'hs_pipeline', 'hs_pipeline_stage', 'hs_ticket_priority', 'hubspot_owner_id'],
+    products: ['name', 'price', 'description', 'hs_sku'],
+    line_items: ['name', 'price', 'quantity', 'amount', 'hs_sku'],
+};

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

@@ -0,0 +1,10 @@
+export { ASSOCIATION_LIMIT_MAX, BLUEPRINT_FORMAT, BlueprintSchema, DraftBlueprintSchema, EQUATION_TYPES, GROUP_NAME_LOWERCASE, GROUP_NAME_MAX, GROUP_NAME_RULE, PROPERTY_TYPES, STANDARD_OBJECTS, isEquation, isGroupName, isLowercaseGroupName, isStandardObject, type Association, type AssociationLabel, type Blueprint, type BlueprintObject, type CustomObjectDefinition, type DraftBlueprint, type Pipeline, type Property, type PropertyGroup, type PropertyType, type Stage, type StageMetadata, type StandardObject, } from './schema.ts';
+export { DEFAULT_PIPELINE_IDS, STOCK_PIPELINES, adoptablePipeline, canHavePipelines, identifierSlug, isClosedStage, metadataKeyFor, pipelineKeySlug, type MetadataKey, } from './pipelines.ts';
+export { CUSTOM_OBJECT_NAME_MAX, STOCK_PROPERTY_GROUPS, STOCK_PROPERTY_NAMES, defaultGroupLabel, defaultGroupName } from './groups.ts';
+export { STANDARD_OBJECT_NAMES, isRenamed, objectDisplayName, type ObjectNames } from './object-names.ts';
+export { FIELD_TYPES, fieldTypeOf, type FieldTypeChoice, type FieldTypeId } from './field-types.ts';
+export { formulaCycles, formulaReferences, renameInFormula } from './formula.ts';
+export { describeLimit, findPair, labelEntries, pairId, type LabelEntry } from './associations.ts';
+export { blueprintIssues, issueText, validateBlueprint, type BlueprintIssue, type IssuePath } from './validate.ts';
+export { mappingTargetsSchema, type MappingTarget } from './mapping-targets.ts';
+export { blueprintJsonSchema, parseBlueprint, readDraftYaml, serializeBlueprint, type DraftYaml } from './serialize.ts';

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

@@ -0,0 +1,11 @@
+// The browser-safe part of the engine (@cc/engine/blueprint): zod and yaml only. test/blueprint/entry.test.ts keeps it that way.
+export { ASSOCIATION_LIMIT_MAX, BLUEPRINT_FORMAT, BlueprintSchema, DraftBlueprintSchema, EQUATION_TYPES, GROUP_NAME_LOWERCASE, GROUP_NAME_MAX, GROUP_NAME_RULE, PROPERTY_TYPES, STANDARD_OBJECTS, isEquation, isGroupName, isLowercaseGroupName, isStandardObject, } from './schema.js';
+export { DEFAULT_PIPELINE_IDS, STOCK_PIPELINES, adoptablePipeline, canHavePipelines, identifierSlug, isClosedStage, metadataKeyFor, pipelineKeySlug, } from './pipelines.js';
+export { CUSTOM_OBJECT_NAME_MAX, STOCK_PROPERTY_GROUPS, STOCK_PROPERTY_NAMES, defaultGroupLabel, defaultGroupName } from './groups.js';
+export { STANDARD_OBJECT_NAMES, isRenamed, objectDisplayName } from './object-names.js';
+export { FIELD_TYPES, fieldTypeOf } from './field-types.js';
+export { formulaCycles, formulaReferences, renameInFormula } from './formula.js';
+export { describeLimit, findPair, labelEntries, pairId } from './associations.js';
+export { blueprintIssues, issueText, validateBlueprint } from './validate.js';
+export { mappingTargetsSchema } from './mapping-targets.js';
+export { blueprintJsonSchema, parseBlueprint, readDraftYaml, serializeBlueprint } from './serialize.js';

package/dist/engine/src/blueprint/mapping-targets.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/** An object type and the property names an integration's mappings point at. */
+export interface MappingTarget {
+    objectType: string;
+    properties: string[];
+}
+export declare const mappingTargetsSchema: z.ZodArray<z.ZodObject<{
+    objectType: z.ZodString;
+    properties: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;

package/dist/engine/src/blueprint/mapping-targets.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export const mappingTargetsSchema = z.array(z.object({
+    objectType: z.string().min(1).max(100),
+    properties: z.array(z.string().min(1).max(100)).max(500),
+})).max(50);

package/dist/engine/src/blueprint/object-names.d.ts

@@ -0,0 +1,11 @@
+import { type StandardObject } from './schema.ts';
+export type ObjectNames = {
+    singular: string;
+    plural: string;
+};
+/** HubSpot's own names for the standard objects, before anyone renames them in Settings → Data model. */
+export declare const STANDARD_OBJECT_NAMES: Record<StandardObject, ObjectNames>;
+/** Renamed = either name differs from HubSpot's default by exact text. */
+export declare function isRenamed(objectType: StandardObject, names: ObjectNames): boolean;
+/** `Organizations (Companies)` for a renamed standard object, the default plural otherwise; anything else is returned as is. */
+export declare function objectDisplayName(objectType: string, labels?: ObjectNames): string;

package/dist/engine/src/blueprint/object-names.js

@@ -0,0 +1,22 @@
+import { isStandardObject } from './schema.js';
+/** HubSpot's own names for the standard objects, before anyone renames them in Settings → Data model. */
+export const STANDARD_OBJECT_NAMES = {
+    contacts: { singular: 'Contact', plural: 'Contacts' },
+    companies: { singular: 'Company', plural: 'Companies' },
+    deals: { singular: 'Deal', plural: 'Deals' },
+    tickets: { singular: 'Ticket', plural: 'Tickets' },
+    products: { singular: 'Product', plural: 'Products' },
+    line_items: { singular: 'Line item', plural: 'Line items' },
+};
+/** Renamed = either name differs from HubSpot's default by exact text. */
+export function isRenamed(objectType, names) {
+    const standard = STANDARD_OBJECT_NAMES[objectType];
+    return names.singular !== standard.singular || names.plural !== standard.plural;
+}
+/** `Organizations (Companies)` for a renamed standard object, the default plural otherwise; anything else is returned as is. */
+export function objectDisplayName(objectType, labels) {
+    if (!isStandardObject(objectType))
+        return objectType;
+    const defaultPlural = STANDARD_OBJECT_NAMES[objectType].plural;
+    return labels && isRenamed(objectType, labels) ? `${labels.plural} (${defaultPlural})` : defaultPlural;
+}

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

@@ -0,0 +1,40 @@
+import { type Pipeline, type StageMetadata } from './schema.ts';
+/** Pipelines exist on deals, tickets and custom objects only (P1). */
+export declare function canHavePipelines(objectType: string): boolean;
+export type MetadataKey = 'probability' | 'ticketState' | 'state';
+/** Each object kind keeps its stage semantics under a different metadata key (P2). */
+export declare function metadataKeyFor(objectType: string): MetadataKey;
+/** The pipeline HubSpot ships with a portal; adopted with origin: hubspot, never created. */
+export declare const DEFAULT_PIPELINE_IDS: Readonly<Record<string, string>>;
+export interface StockPipeline {
+    id: string;
+    label: string;
+    stages: Array<{
+        id: string;
+        label: string;
+        metadata: Record<string, string>;
+    }>;
+}
+/** The pipeline every new portal has on deals and tickets, measured on portals A and B (docs/hubspot-quirks.md, Pipelines). */
+export declare const STOCK_PIPELINES: Readonly<Record<'deals' | 'tickets', StockPipeline>>;
+/**
+ * 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 declare function adoptablePipeline(objectType: 'deals' | 'tickets'): Pipeline;
+/** The record property holding the stage id. */
+export declare function stagePropertyFor(objectType: string): string;
+/** HubSpot generates one set of these per stage; they are not ours to manage. */
+export declare const STAGE_PROPERTY_PATTERN: RegExp;
+export declare function isStageGeneratedProperty(name: string): boolean;
+/** Properties that pipelines and stages own, so the property engine must leave them alone. */
+export declare function isPipelineOwnedProperty(objectType: string, name: string): boolean;
+/** The four properties whose options are the pipelines and stages themselves. */
+export declare function isOptionsOwnedByPipelines(objectType: string, name: string): boolean;
+/** A readable identifier from a label: lower case letters, digits and underscores, starting with a letter. */
+export declare function identifierSlug(label: string, prefix: string, fallback: string): string;
+/** A readable, identifier-safe key from a label. */
+export declare function pipelineKeySlug(label: string, prefix: 'p' | 's'): string;
+/** isClosed is derived by HubSpot, so we infer it from the metadata that drives it (P2). */
+export declare function isClosedStage(objectType: string, metadata: StageMetadata): boolean;