fullstackgtm 0.10.0

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+import type { GtmAuditRule, GtmPolicy } from "./types.ts";
+/**
+ * Project-level configuration: `fullstackgtm.config.json` in the working
+ * directory (or an explicit `--config` path). Policy thresholds, rule
+ * selection, and rule packages — third-party modules exporting additional
+ * `GtmAuditRule`s — all live here so a team's audit standard is reviewable
+ * in version control.
+ */
+export declare const CONFIG_FILE_NAME = "fullstackgtm.config.json";
+export type FullstackgtmConfig = {
+    policy?: Partial<GtmPolicy>;
+    rules?: {
+        /** If set, only these rule ids run (after rule packages are loaded). */
+        enabled?: string[];
+        /** Removed from the effective set after `enabled` is applied. */
+        disabled?: string[];
+    };
+    /**
+     * Module specifiers resolved relative to the config file. Each module must
+     * export `rules: GtmAuditRule[]`. Use compiled .js/.mjs modules so they
+     * load under plain Node.
+     */
+    rulePackages?: string[];
+};
+export type LoadedConfig = {
+    config: FullstackgtmConfig;
+    path: string;
+};
+export declare function loadConfig(explicitPath?: string, cwd?: string): LoadedConfig | null;
+/** Overlay config policy values onto a base policy; defined values win. */
+export declare function mergePolicy(base: GtmPolicy, config?: FullstackgtmConfig): GtmPolicy;
+/**
+ * Build the effective rule set: built-ins plus rule-package exports, then
+ * `enabled` (allow-list) and `disabled` filters.
+ */
+export declare function resolveConfiguredRules(loaded?: LoadedConfig | null, baseRules?: GtmAuditRule[]): Promise<GtmAuditRule[]>;

package/dist/config.js

@@ -0,0 +1,85 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { builtinAuditRules } from "./rules.js";
+/**
+ * Project-level configuration: `fullstackgtm.config.json` in the working
+ * directory (or an explicit `--config` path). Policy thresholds, rule
+ * selection, and rule packages — third-party modules exporting additional
+ * `GtmAuditRule`s — all live here so a team's audit standard is reviewable
+ * in version control.
+ */
+export const CONFIG_FILE_NAME = "fullstackgtm.config.json";
+export function loadConfig(explicitPath, cwd = process.cwd()) {
+    const path = explicitPath ? resolve(cwd, explicitPath) : resolve(cwd, CONFIG_FILE_NAME);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        if (explicitPath)
+            throw new Error(`Could not read config file: ${path}`);
+        return null;
+    }
+    const config = JSON.parse(raw);
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        throw new Error(`${path} must contain a JSON object.`);
+    }
+    return { config, path };
+}
+/** Overlay config policy values onto a base policy; defined values win. */
+export function mergePolicy(base, config) {
+    if (!config?.policy)
+        return base;
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(config.policy)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * Build the effective rule set: built-ins plus rule-package exports, then
+ * `enabled` (allow-list) and `disabled` filters.
+ */
+export async function resolveConfiguredRules(loaded, baseRules = builtinAuditRules) {
+    let rules = [...baseRules];
+    for (const specifier of loaded?.config.rulePackages ?? []) {
+        const resolvedSpecifier = specifier.startsWith(".") || isAbsolute(specifier)
+            ? pathToFileURL(resolve(dirname(loaded.path), specifier)).href
+            : specifier;
+        const rulePackage = await import(__rewriteRelativeImportExtension(resolvedSpecifier));
+        const imported = rulePackage.rules ?? rulePackage.default?.rules;
+        if (!Array.isArray(imported)) {
+            throw new Error(`Rule package ${specifier} must export \`rules: GtmAuditRule[]\`.`);
+        }
+        for (const rule of imported) {
+            if (!rule?.id || typeof rule.evaluate !== "function") {
+                throw new Error(`Rule package ${specifier} exported an invalid rule.`);
+            }
+            rules.push(rule);
+        }
+    }
+    const enabled = loaded?.config.rules?.enabled;
+    if (enabled?.length) {
+        const known = new Map(rules.map((rule) => [rule.id, rule]));
+        rules = enabled.map((id) => {
+            const rule = known.get(id);
+            if (!rule) {
+                throw new Error(`Config enables unknown rule: ${id}. Known rules: ${Array.from(known.keys()).join(", ")}`);
+            }
+            return rule;
+        });
+    }
+    const disabled = new Set(loaded?.config.rules?.disabled ?? []);
+    return rules.filter((rule) => !disabled.has(rule.id));
+}

package/dist/connector.d.ts

@@ -0,0 +1,30 @@
+import type { GtmConnector, PatchPlan, PatchPlanRun } from "./types.ts";
+export type ApplyPatchPlanOptions = {
+    /**
+     * Explicit allow-list of operation ids the human approved. Operations not
+     * listed are skipped without any provider call. An empty list rejects the
+     * whole run.
+     */
+    approvedOperationIds: string[];
+    /**
+     * Concrete values supplied at approval time for operations whose
+     * `afterValue` is a `requires_human_*` placeholder, keyed by operation id.
+     */
+    valueOverrides?: Record<string, unknown>;
+    /**
+     * Compare-and-set: before each field write, read the live provider value
+     * and refuse the write (`conflict` result) if it no longer matches the
+     * plan's `beforeValue`. Defaults to on when the connector supports
+     * `readField`.
+     */
+    checkConflicts?: boolean;
+};
+/**
+ * Apply an approved subset of a patch plan through a connector.
+ *
+ * The safety contract lives here, not in connectors:
+ * - nothing is written unless the operation id was explicitly approved
+ * - placeholder values are never written; they require an override
+ * - every operation produces a result, and the run is the audit record
+ */
+export declare function applyPatchPlan(connector: GtmConnector, plan: PatchPlan, options: ApplyPatchPlanOptions): Promise<PatchPlanRun>;

package/dist/connector.js

@@ -0,0 +1,94 @@
+import { requiresHumanInput } from "./rules.js";
+const FIELD_WRITE_OPERATIONS = new Set(["set_field", "clear_field", "link_record"]);
+function normalizeForComparison(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    return String(value);
+}
+/**
+ * Apply an approved subset of a patch plan through a connector.
+ *
+ * The safety contract lives here, not in connectors:
+ * - nothing is written unless the operation id was explicitly approved
+ * - placeholder values are never written; they require an override
+ * - every operation produces a result, and the run is the audit record
+ */
+export async function applyPatchPlan(connector, plan, options) {
+    if (!connector.applyOperation) {
+        throw new Error(`The ${connector.provider} connector is read-only.`);
+    }
+    const startedAt = new Date().toISOString();
+    const approved = new Set(options.approvedOperationIds);
+    const checkConflicts = options.checkConflicts ?? typeof connector.readField === "function";
+    const results = [];
+    let attempted = 0;
+    let applied = 0;
+    for (const operation of plan.operations) {
+        if (!approved.has(operation.id)) {
+            results.push({
+                operationId: operation.id,
+                status: "skipped",
+                detail: "Operation was not approved.",
+            });
+            continue;
+        }
+        const override = options.valueOverrides?.[operation.id];
+        if (requiresHumanInput(operation.afterValue) && override === undefined) {
+            results.push({
+                operationId: operation.id,
+                status: "skipped",
+                detail: "Operation needs a concrete value; supply a value override.",
+            });
+            continue;
+        }
+        if (checkConflicts &&
+            connector.readField &&
+            operation.field &&
+            FIELD_WRITE_OPERATIONS.has(operation.operation)) {
+            const current = await connector.readField(operation.objectType, operation.objectId, operation.field);
+            const expected = normalizeForComparison(operation.beforeValue);
+            const found = normalizeForComparison(current);
+            if (expected !== found) {
+                results.push({
+                    operationId: operation.id,
+                    status: "conflict",
+                    detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+                    providerData: { currentValue: current ?? null },
+                });
+                continue;
+            }
+        }
+        const resolved = override === undefined ? operation : { ...operation, afterValue: override };
+        attempted += 1;
+        try {
+            const result = await connector.applyOperation(resolved);
+            results.push(result);
+            if (result.status === "applied")
+                applied += 1;
+        }
+        catch (error) {
+            results.push({
+                operationId: operation.id,
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        planId: plan.id,
+        provider: connector.provider,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        status: runStatus(attempted, applied),
+        results,
+    };
+}
+function runStatus(attempted, applied) {
+    if (attempted === 0)
+        return "rejected";
+    if (applied === attempted)
+        return "applied";
+    if (applied > 0)
+        return "partial";
+    return "failed";
+}

package/dist/connectors/hubspot.d.ts

@@ -0,0 +1,20 @@
+import { type FieldMappings } from "../mappings.ts";
+import type { GtmConnector } from "../types.ts";
+export type HubspotConnectorOptions = {
+    /** Returns a HubSpot access token (private app token or OAuth access token). */
+    getAccessToken: () => string | Promise<string>;
+    /** Per-org canonical-to-provider field overrides. Defaults cover standard properties. */
+    fieldMappings?: FieldMappings;
+    apiBaseUrl?: string;
+    /** Injectable fetch for testing. */
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Reference connector for HubSpot.
+ *
+ * Unlike sync pipelines that drop records they cannot fully resolve, the
+ * connector returns every record it can read — including ownerless or
+ * amountless deals — so audit rules can surface the gaps instead of hiding
+ * them.
+ */
+export declare function createHubspotConnector(options: HubspotConnectorOptions): Required<GtmConnector>;

package/dist/connectors/hubspot.js

@@ -0,0 +1,409 @@
+import { HUBSPOT_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, readMappedValue, } from "../mappings.js";
+const DEFAULT_API_BASE_URL = "https://api.hubapi.com";
+const OBJECT_PATHS = {
+    account: "companies",
+    contact: "contacts",
+    deal: "deals",
+};
+const MAPPING_OBJECT_TYPES = {
+    account: "accounts",
+    contact: "contacts",
+    deal: "deals",
+};
+/**
+ * Reference connector for HubSpot.
+ *
+ * Unlike sync pipelines that drop records they cannot fully resolve, the
+ * connector returns every record it can read — including ownerless or
+ * amountless deals — so audit rules can surface the gaps instead of hiding
+ * them.
+ */
+export function createHubspotConnector(options) {
+    const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const mappings = options.fieldMappings;
+    async function request(path, init = {}) {
+        const token = await options.getAccessToken();
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+                ...(init.headers ?? {}),
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`HubSpot API error ${response.status}: ${body}`);
+        }
+        // DELETE and some association writes return 204 with an empty body.
+        const text = await response.text();
+        return text ? JSON.parse(text) : null;
+    }
+    async function list(path) {
+        const results = [];
+        let after;
+        const seen = new Set();
+        do {
+            // Guard against a provider returning a repeating cursor (would loop
+            // forever): stop if the same `after` is handed back twice.
+            if (after) {
+                if (seen.has(after))
+                    break;
+                seen.add(after);
+            }
+            const separator = path.includes("?") ? "&" : "?";
+            const data = await request(`${path}${after ? `${separator}after=${encodeURIComponent(after)}` : ""}`);
+            results.push(...(data.results ?? []));
+            after = data.paging?.next?.after;
+        } while (after);
+        return results;
+    }
+    async function assembleSnapshot(fetchObjects) {
+        const owners = await list("/crm/v3/owners?limit=100");
+        const users = owners
+            .filter((owner) => owner.id)
+            .map((owner) => ({
+            id: String(owner.id),
+            provider: "hubspot",
+            crmId: String(owner.id),
+            identities: [{ provider: "hubspot", externalId: String(owner.id) }],
+            name: [owner.firstName, owner.lastName].filter(Boolean).join(" ") ||
+                stringOrFallback(owner.email, `Owner ${owner.id}`),
+            email: stringOrUndefined(owner.email),
+            active: owner.archived !== true,
+        }));
+        const companyProperties = mappedFields(mappings, "accounts", HUBSPOT_DEFAULT_FIELD_MAPPINGS.accounts).join(",");
+        const companies = await fetchObjects("companies", companyProperties, false);
+        const accounts = companies
+            .filter((company) => company.id)
+            .map((company) => {
+            const props = company.properties ?? {};
+            return {
+                id: String(company.id),
+                provider: "hubspot",
+                crmId: String(company.id),
+                identities: [{ provider: "hubspot", externalId: String(company.id) }],
+                name: stringOrFallback(readMapped(props, "accounts", "name", "name"), "Unknown Company"),
+                domain: stringOrUndefined(readMapped(props, "accounts", "domain", "domain")),
+                industry: stringOrUndefined(readMapped(props, "accounts", "industry", "industry")),
+                employeeCount: numberOrUndefined(readMapped(props, "accounts", "employeeCount", "numberofemployees")),
+                annualRevenue: numberOrUndefined(readMapped(props, "accounts", "annualRevenue", "annualrevenue")),
+                ownerId: stringOrUndefined(readMapped(props, "accounts", "ownerId", "hubspot_owner_id")),
+                lastSyncAt: stringOrUndefined(company.updatedAt),
+                raw: company,
+            };
+        });
+        const contactProperties = mappedFields(mappings, "contacts", HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts).join(",");
+        const hubspotContacts = await fetchObjects("contacts", contactProperties, true);
+        const contacts = hubspotContacts
+            .filter((contact) => contact.id)
+            .map((contact) => {
+            const props = contact.properties ?? {};
+            const companyId = contact.associations?.companies?.results?.[0]?.id;
+            return {
+                id: String(contact.id),
+                provider: "hubspot",
+                crmId: String(contact.id),
+                identities: [{ provider: "hubspot", externalId: String(contact.id) }],
+                accountId: companyId ? String(companyId) : undefined,
+                firstName: stringOrUndefined(readMapped(props, "contacts", "firstName", "firstname")),
+                lastName: stringOrUndefined(readMapped(props, "contacts", "lastName", "lastname")),
+                email: stringOrUndefined(readMapped(props, "contacts", "email", "email")),
+                phone: stringOrUndefined(readMapped(props, "contacts", "phone", "phone")),
+                title: stringOrUndefined(readMapped(props, "contacts", "title", "jobtitle")),
+                ownerId: stringOrUndefined(readMapped(props, "contacts", "ownerId", "hubspot_owner_id")),
+                lastSyncAt: stringOrUndefined(contact.updatedAt),
+                raw: contact,
+            };
+        });
+        const dealProperties = mappedFields(mappings, "deals", HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals).join(",");
+        const hubspotDeals = await fetchObjects("deals", dealProperties, true);
+        const deals = hubspotDeals
+            .filter((deal) => deal.id)
+            .map((deal) => {
+            const props = deal.properties ?? {};
+            const companyId = deal.associations?.companies?.results?.[0]?.id;
+            const stage = stringOrUndefined(readMapped(props, "deals", "stage", "dealstage"));
+            const normalizedStage = (stage ?? "").toLowerCase();
+            const isWon = normalizedStage.includes("closedwon");
+            const isClosed = isWon || normalizedStage.includes("closedlost");
+            const forecastCategory = isWon
+                ? "closed_won"
+                : normalizedStage.includes("closedlost")
+                    ? "closed_lost"
+                    : "pipeline";
+            const lastActivityAt = stringOrUndefined(readMapped(props, "deals", "lastActivityAt", "hs_last_sales_activity_timestamp"));
+            return {
+                id: String(deal.id),
+                provider: "hubspot",
+                crmId: String(deal.id),
+                identities: [{ provider: "hubspot", externalId: String(deal.id) }],
+                accountId: companyId ? String(companyId) : undefined,
+                ownerId: stringOrUndefined(readMapped(props, "deals", "ownerId", "hubspot_owner_id")),
+                name: stringOrFallback(readMapped(props, "deals", "name", "dealname"), "Untitled Deal"),
+                amount: numberOrUndefined(readMapped(props, "deals", "amount", "amount")),
+                stage,
+                closeDate: stringOrUndefined(readMapped(props, "deals", "closeDate", "closedate"))?.split("T")[0],
+                dealType: stringOrUndefined(readMapped(props, "deals", "dealType", "dealtype")),
+                // hs_deal_stage_probability is already a 0..1 fraction in HubSpot,
+                // so it maps straight to the canonical 0..1 unit (no /100, unlike
+                // Salesforce's 0..100 Probability field).
+                probability: numberOrUndefined(readMapped(props, "deals", "probability", "hs_deal_stage_probability")),
+                forecastCategory,
+                isClosed,
+                isWon,
+                // hs_last_sales_activity_timestamp is an ISO timestamp; keep the
+                // date portion when it looks like one, otherwise pass through (e.g.
+                // an epoch-millis string).
+                lastActivityAt: lastActivityAt?.includes("T")
+                    ? lastActivityAt.split("T")[0]
+                    : lastActivityAt,
+                lastSyncAt: stringOrUndefined(deal.updatedAt),
+                raw: deal,
+            };
+        });
+        return {
+            generatedAt: new Date().toISOString(),
+            provider: "hubspot",
+            users,
+            accounts,
+            contacts,
+            deals,
+            // Engagement reads need additional scopes; activity staleness falls back
+            // to record sync timestamps until engagements are supported.
+            activities: [],
+        };
+    }
+    async function fetchSnapshot() {
+        return assembleSnapshot((objectType, properties, withAssociations) => list(`/crm/v3/objects/${objectType}?limit=100&properties=${properties}${withAssociations ? "&associations=companies" : ""}`));
+    }
+    const MODIFIED_DATE_PROPERTIES = {
+        companies: "hs_lastmodifieddate",
+        contacts: "lastmodifieddate",
+        deals: "hs_lastmodifieddate",
+    };
+    async function searchList(objectType, properties, sinceMs) {
+        const results = [];
+        let after;
+        // HubSpot's search API hard-caps at 10,000 results (100 pages of 100) and
+        // 400s past it. Stop at the boundary rather than throwing mid-sync; an
+        // incremental window this large should fall back to a full snapshot.
+        const MAX_PAGES = 100;
+        for (let page = 0; page < MAX_PAGES; page += 1) {
+            const data = await request(`/crm/v3/objects/${objectType}/search`, {
+                method: "POST",
+                body: JSON.stringify({
+                    filterGroups: [
+                        {
+                            filters: [
+                                {
+                                    propertyName: MODIFIED_DATE_PROPERTIES[objectType],
+                                    operator: "GTE",
+                                    value: String(sinceMs),
+                                },
+                            ],
+                        },
+                    ],
+                    properties: properties.split(","),
+                    limit: 100,
+                    ...(after ? { after } : {}),
+                }),
+            });
+            results.push(...(data.results ?? []));
+            const next = data.paging?.next?.after;
+            if (!next || next === after)
+                break;
+            after = next;
+        }
+        return results;
+    }
+    /**
+     * Records modified since `sinceIso`, via the CRM search API. HubSpot search
+     * results carry no associations, so contact/deal accountIds are absent in
+     * change feeds — consumers merging deltas must preserve associations from
+     * the last full snapshot.
+     */
+    async function fetchChanges(sinceIso) {
+        const sinceMs = Date.parse(sinceIso);
+        if (!Number.isFinite(sinceMs))
+            throw new Error(`Invalid since timestamp: ${sinceIso}`);
+        return assembleSnapshot((objectType, properties) => searchList(objectType, properties, sinceMs));
+    }
+    // HubSpot-defined association type ids from a task engagement to its parent.
+    const TASK_ASSOCIATION_TYPE_IDS = {
+        contact: 204,
+        account: 192,
+        deal: 216,
+    };
+    function humanizeField(field) {
+        return field
+            .replace(/_task$/, "")
+            .replace(/[_-]+/g, " ")
+            .replace(/\b\w/g, (c) => c.toUpperCase())
+            .trim();
+    }
+    async function setField(operation) {
+        const objectPath = OBJECT_PATHS[operation.objectType];
+        const mappingType = MAPPING_OBJECT_TYPES[operation.objectType];
+        if (!objectPath || !mappingType || !operation.field) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "Field writes are only supported for accounts, contacts, and deals with an explicit field.",
+            };
+        }
+        const defaults = HUBSPOT_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+        const property = mappedField(mappings, mappingType, operation.field, defaults[operation.field] ?? operation.field);
+        const value = operation.operation === "clear_field" ? "" : String(operation.afterValue ?? "");
+        const response = await request(`/crm/v3/objects/${objectPath}/${encodeURIComponent(operation.objectId)}`, { method: "PATCH", body: JSON.stringify({ properties: { [property]: value } }) });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Set ${property} on ${objectPath}/${operation.objectId}.`,
+            providerData: { id: response?.id, property },
+        };
+    }
+    async function linkRecord(operation) {
+        // Associate a deal or contact with a company (the only link the built-in
+        // rules emit — missing-deal-account). afterValue is the target company id.
+        const fromPath = OBJECT_PATHS[operation.objectType];
+        if ((operation.objectType !== "deal" && operation.objectType !== "contact") || !fromPath) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "link_record is supported for deals and contacts (to a company).",
+            };
+        }
+        const companyId = String(operation.afterValue ?? "");
+        if (!companyId) {
+            return { operationId: operation.id, status: "skipped", detail: "link_record needs a target company id." };
+        }
+        await request(`/crm/v4/objects/${fromPath}/${encodeURIComponent(operation.objectId)}/associations/default/companies/${encodeURIComponent(companyId)}`, { method: "PUT" });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Linked ${fromPath}/${operation.objectId} to company ${companyId}.`,
+            providerData: { companyId },
+        };
+    }
+    async function createTask(operation) {
+        const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
+        if (associationTypeId === undefined) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "Tasks can be attached to accounts, contacts, and deals.",
+            };
+        }
+        const subject = operation.field ? humanizeField(operation.field) : "Follow up";
+        const body = String(operation.afterValue ?? operation.reason ?? "");
+        const response = await request(`/crm/v3/objects/tasks`, {
+            method: "POST",
+            body: JSON.stringify({
+                properties: {
+                    hs_task_subject: subject,
+                    hs_task_body: body,
+                    hs_task_status: "NOT_STARTED",
+                    hs_task_priority: "MEDIUM",
+                    hs_timestamp: Date.now(),
+                },
+                associations: [
+                    {
+                        to: { id: operation.objectId },
+                        types: [
+                            { associationCategory: "HUBSPOT_DEFINED", associationTypeId },
+                        ],
+                    },
+                ],
+            }),
+        });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Created task "${subject}" on ${operation.objectType}/${operation.objectId}.`,
+            providerData: { id: response?.id },
+        };
+    }
+    async function archiveRecord(operation) {
+        const objectPath = OBJECT_PATHS[operation.objectType];
+        if (!objectPath) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "archive_record is supported for accounts, contacts, and deals.",
+            };
+        }
+        await request(`/crm/v3/objects/${objectPath}/${encodeURIComponent(operation.objectId)}`, {
+            method: "DELETE",
+        });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Archived ${objectPath}/${operation.objectId}.`,
+        };
+    }
+    async function applyOperation(operation) {
+        try {
+            switch (operation.operation) {
+                case "set_field":
+                case "clear_field":
+                    return await setField(operation);
+                case "link_record":
+                    return await linkRecord(operation);
+                case "create_task":
+                    return await createTask(operation);
+                case "archive_record":
+                    return await archiveRecord(operation);
+                default:
+                    return {
+                        operationId: operation.id,
+                        status: "skipped",
+                        detail: `Unknown operation ${operation.operation}.`,
+                    };
+            }
+        }
+        catch (error) {
+            return {
+                operationId: operation.id,
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    function readMapped(source, objectType, targetField, fallbackField) {
+        return readMappedValue(source, mappings, objectType, targetField, fallbackField);
+    }
+    async function readField(objectType, objectId, field) {
+        const objectPath = OBJECT_PATHS[objectType];
+        const mappingType = MAPPING_OBJECT_TYPES[objectType];
+        if (!objectPath || !mappingType) {
+            throw new Error(`Field reads are only supported for accounts, contacts, and deals.`);
+        }
+        const defaults = HUBSPOT_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+        const property = mappedField(mappings, mappingType, field, defaults[field] ?? field);
+        const data = await request(`/crm/v3/objects/${objectPath}/${encodeURIComponent(objectId)}?properties=${encodeURIComponent(property)}`);
+        return data?.properties?.[property] ?? null;
+    }
+    return {
+        provider: "hubspot",
+        fetchSnapshot,
+        fetchChanges,
+        applyOperation,
+        readField,
+    };
+}
+function stringOrUndefined(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    return String(value);
+}
+function stringOrFallback(value, fallback) {
+    return stringOrUndefined(value) ?? fallback;
+}
+function numberOrUndefined(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number.parseFloat(String(value));
+    return Number.isFinite(parsed) ? parsed : undefined;
+}