@robinpath/hubspot - npm Package Compare versions

Comparing version

0.1.1

0.3.0

+27

dist/hubspot.d.ts

		/**
		* RobinPath HubSpot Module (Node port)
		*
		* HubSpot CRM API v3 — contacts, companies, deals, notes, tasks, and list
		* membership. Mirror of packages/php/hubspot/src/index.php for the
		* WordPress plugin; shares the same credential contract, metadata shape,
		* and error taxonomy so the visual editor can render both identically.
		*
		* HubSpot retired their legacy `hapikey` query-string API keys in 2022; this
		* module authenticates exclusively with Private App access tokens (scoped,
		* revocable OAuth-style bearer tokens). Create one in your HubSpot portal at
		* Settings → Integrations → Private Apps, then paste it into a RobinPath
		* credential of type `hubspot`.
		*
		* Every method takes a credential slug as its first argument; the module
		* resolves the stored token at call time via the injected ModuleHost.
		*
		* Credential type declared by this module:
		* - hubspot : { access_token } → Bearer auth with a Private App token
		*/
		import type { BuiltinHandler, CredentialTypeSchema, FunctionMetadata, ModuleHost, ModuleMetadata } from "@robinpath/core";
		export declare function configureHubspot(h: ModuleHost): void;
		export declare const HubspotFunctions: Record<string, BuiltinHandler>;
		export declare const HubspotCredentialTypes: CredentialTypeSchema[];
		export declare const HubspotFunctionMetadata: Record<string, FunctionMetadata>;
		export declare const HubspotModuleMetadata: ModuleMetadata;
		//# sourceMappingURL=hubspot.d.ts.map

+1

dist/hubspot.d.ts.map

{"version":3,"file":"hubspot.d.ts","sourceRoot":"","sources":["../src/hubspot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,cAAc,EAEf,MAAM,iBAAiB,CAAC;AAezB,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAEpD;AA6hBD,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAqB3D,CAAC;AAIF,eAAO,MAAM,sBAAsB,EAAE,oBAAoB,EAkBxD,CAAC;AAkHF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA+epE,CAAC;AAIF,eAAO,MAAM,qBAAqB,EAAE,cAsBnC,CAAC"}

+1082

dist/hubspot.js

		/**
		* RobinPath HubSpot Module (Node port)
		*
		* HubSpot CRM API v3 — contacts, companies, deals, notes, tasks, and list
		* membership. Mirror of packages/php/hubspot/src/index.php for the
		* WordPress plugin; shares the same credential contract, metadata shape,
		* and error taxonomy so the visual editor can render both identically.
		*
		* HubSpot retired their legacy `hapikey` query-string API keys in 2022; this
		* module authenticates exclusively with Private App access tokens (scoped,
		* revocable OAuth-style bearer tokens). Create one in your HubSpot portal at
		* Settings → Integrations → Private Apps, then paste it into a RobinPath
		* credential of type `hubspot`.
		*
		* Every method takes a credential slug as its first argument; the module
		* resolves the stored token at call time via the injected ModuleHost.
		*
		* Credential type declared by this module:
		* - hubspot : { access_token } → Bearer auth with a Private App token
		*/
		// ── Module-local state (populated by configure hook) ────────────────────
		const state = {};
		function host() {
		if (!state.host) {
		throw new Error("HubSpot module not initialized. Pass the adapter to rp.installModule() so its configure() hook runs first.");
		}
		return state.host;
		}
		export function configureHubspot(h) {
		state.host = h;
		}
		// ── Constants ──────────────────────────────────────────────────────────
		const API_BASE = "https://api.hubapi.com/";
		const CREDENTIAL_TYPE = "hubspot";
		function errorReturn(error, code, extra = {}) {
		return { error, code, ...extra };
		}
		// ── Credential resolver (mirrors PHP resolveToken) ─────────────────────
		async function resolveToken(credentialSlug) {
		if (!credentialSlug) {
		return errorReturn("Credential slug is required.", "credential_not_found");
		}
		let fields;
		try {
		fields = await host().credentials.get(credentialSlug);
		}
		catch (e) {
		return errorReturn(e instanceof Error ? e.message : String(e), "credential_not_found");
		}
		if (!fields) {
		return errorReturn(`Credential '${credentialSlug}' not found.`, "credential_not_found");
		}
		const token = String(fields.access_token ?? "");
		if (!token) {
		return errorReturn("Credential has no `access_token` field.", "token_missing");
		}
		return { token };
		}
		// ── HTTP helper (normalized envelope, never throws for API errors) ─────
		async function http(token, method, pathAndQuery, body) {
		const headers = {
		Authorization: `Bearer ${token}`,
		Accept: "application/json",
		};
		if (body !== undefined && body !== null) {
		headers["Content-Type"] = "application/json";
		}
		const init = { method, headers };
		if (body !== undefined && body !== null) {
		init.body = JSON.stringify(body);
		}
		let response;
		try {
		response = await fetch(`${API_BASE}${pathAndQuery.replace(/^\/+/, "")}`, init);
		}
		catch (e) {
		return errorReturn(e instanceof Error ? e.message : String(e), "transport");
		}
		const raw = await response.text();
		if (response.status === 204 \|\| raw === "") {
		if (response.status >= 200 && response.status < 300) {
		return { ok: true };
		}
		}
		let decoded;
		try {
		decoded = raw ? JSON.parse(raw) : null;
		}
		catch {
		decoded = { raw: raw.slice(0, 500) };
		}
		if (response.status >= 200 && response.status < 300) {
		if (decoded && typeof decoded === "object")
		return decoded;
		return { raw };
		}
		const decodedObj = (decoded && typeof decoded === "object")
		? decoded
		: { raw: typeof raw === "string" ? raw.slice(0, 500) : "" };
		let message = `HubSpot returned HTTP ${response.status}.`;
		if (typeof decodedObj.message === "string") {
		message = decodedObj.message;
		}
		let code = "hubspot_error";
		if (response.status === 404)
		code = "not_found";
		else if (response.status === 429)
		code = "rate_limited";
		return errorReturn(message, code, {
		status: response.status,
		hubspot_error: decodedObj,
		});
		}
		// ── Internal helpers ───────────────────────────────────────────────────
		/**
		* HubSpot's `properties` payload expects scalar string values for most
		* fields. Booleans and numbers are accepted but stringified here for
		* consistent behavior across the API surface. Nested arrays/objects are
		* JSON-encoded (rare — used for things like multi-select values).
		*/
		function stringifyProperties(props) {
		const out = {};
		for (const [k, v] of Object.entries(props)) {
		if (typeof v === "boolean") {
		out[k] = v ? "true" : "false";
		}
		else if (v === null \|\| v === undefined) {
		out[k] = "";
		}
		else if (typeof v === "string" \|\| typeof v === "number") {
		out[k] = String(v);
		}
		else {
		try {
		out[k] = JSON.stringify(v);
		}
		catch {
		out[k] = String(v);
		}
		}
		}
		return out;
		}
		/**
		* Convert a contact id like `"12345"` or `"email:ada@example.com"` into
		* a path + query-string pair. HubSpot supports looking up contacts by an
		* alternate identifier via the `idProperty` query parameter.
		*/
		function parseObjectId(basePath, id) {
		if (id.startsWith("email:")) {
		const email = id.slice(6);
		return {
		path: `${basePath}/${encodeURIComponent(email)}`,
		query: { idProperty: "email" },
		};
		}
		return { path: `${basePath}/${encodeURIComponent(id)}`, query: {} };
		}
		function buildQueryString(params) {
		const keys = Object.keys(params);
		if (keys.length === 0)
		return "";
		const sp = new URLSearchParams();
		for (const k of keys)
		sp.set(k, params[k]);
		return `?${sp.toString()}`;
		}
		/** Unix-epoch milliseconds as a string (HubSpot `hs_timestamp`). */
		function now() {
		return String(Date.now());
		}
		/**
		* Accept an ISO 8601 string, epoch-ms number, or null/undefined → epoch-ms string.
		*/
		function resolveTimestamp(value) {
		if (value === null \|\| value === undefined \|\| value === "") {
		return now();
		}
		if (typeof value === "number" && Number.isFinite(value)) {
		return String(Math.trunc(value));
		}
		if (typeof value === "string") {
		// Numeric string → treat as epoch ms.
		if (/^-?\d+$/.test(value)) {
		return value;
		}
		const parsed = Date.parse(value);
		if (!Number.isNaN(parsed)) {
		return String(parsed);
		}
		}
		return now();
		}
		/**
		* Convert a flat `{contact: id, company: id, deal: id}` shorthand into
		* HubSpot's `associations[]` payload with association type IDs. The
		* caller's source-object type (`note` / `task` / etc.) determines which
		* association type IDs to use — see
		* https://developers.hubspot.com/docs/api/crm/associations
		*/
		const ASSOCIATION_TYPE_IDS = {
		note: { contact: 202, company: 190, deal: 214, ticket: 228 },
		task: { contact: 204, company: 192, deal: 216, ticket: 230 },
		};
		function buildAssociations(map, from) {
		if (!map \|\| Object.keys(map).length === 0)
		return [];
		const table = ASSOCIATION_TYPE_IDS[from];
		if (!table)
		return [];
		const out = [];
		for (const [rawType, rawIds] of Object.entries(map)) {
		const objType = String(rawType).toLowerCase();
		const typeId = table[objType];
		if (typeId === undefined)
		continue;
		const ids = Array.isArray(rawIds) ? rawIds : [rawIds];
		for (const id of ids) {
		out.push({
		to: { id: String(id) },
		types: [
		{
		associationCategory: "HUBSPOT_DEFINED",
		associationTypeId: typeId,
		},
		],
		});
		}
		}
		return out;
		}
		/**
		* Shared caller — resolves the credential, invokes http(), passes through.
		*/
		async function call(cred, method, path, body) {
		const resolved = await resolveToken(cred);
		if ("error" in resolved)
		return resolved;
		return http(resolved.token, method, path, body);
		}
		function isPlainObject(v) {
		return !!v && typeof v === "object" && !Array.isArray(v);
		}
		/**
		* Shared list-handler used by listContacts / listCompanies / listDeals.
		*/
		async function genericList(args, objectType) {
		const cred = String(args[0] ?? "");
		const opts = (isPlainObject(args[1]) ? args[1] : {});
		const query = {};
		if (opts.limit !== undefined) {
		query.limit = String(Number(opts.limit) \| 0);
		}
		if (opts.after !== undefined) {
		query.after = String(opts.after);
		}
		if (opts.properties !== undefined) {
		query.properties = Array.isArray(opts.properties)
		? opts.properties.map((v) => String(v)).join(",")
		: String(opts.properties);
		}
		if (opts.archived !== undefined) {
		query.archived = opts.archived ? "true" : "false";
		}
		const path = `crm/v3/objects/${objectType}${buildQueryString(query)}`;
		return call(cred, "GET", path, null);
		}
		// ── Handlers: Contacts ─────────────────────────────────────────────────
		const createContact = async (args) => {
		const cred = String(args[0] ?? "");
		const props = (isPlainObject(args[1]) ? args[1] : {});
		if (Object.keys(props).length === 0) {
		return errorReturn("`properties` is required.", "validation_failed");
		}
		return (await call(cred, "POST", "crm/v3/objects/contacts", {
		properties: stringifyProperties(props),
		}));
		};
		const updateContact = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const props = (isPlainObject(args[2]) ? args[2] : {});
		if (!id) {
		return errorReturn("`contactId` is required.", "validation_failed");
		}
		if (Object.keys(props).length === 0) {
		return errorReturn("`properties` is required.", "validation_failed");
		}
		return (await call(cred, "PATCH", `crm/v3/objects/contacts/${encodeURIComponent(id)}`, { properties: stringifyProperties(props) }));
		};
		const getContact = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const sel = Array.isArray(args[2]) ? args[2] : null;
		if (!id) {
		return errorReturn("`contactId` is required.", "validation_failed");
		}
		const parsed = parseObjectId("crm/v3/objects/contacts", id);
		const query = { ...parsed.query };
		if (sel) {
		query.properties = sel.map((v) => String(v)).join(",");
		}
		const qs = buildQueryString(query);
		return (await call(cred, "GET", parsed.path + qs, null));
		};
		const searchContacts = async (args) => {
		const cred = String(args[0] ?? "");
		const query = String(args[1] ?? "");
		const opts = (isPlainObject(args[2]) ? args[2] : {});
		const body = {
		limit: opts.limit !== undefined ? Number(opts.limit) \| 0 : 10,
		};
		if (query !== "") {
		body.query = query;
		}
		if (opts.after !== undefined) {
		body.after = String(opts.after);
		}
		if (Array.isArray(opts.properties)) {
		body.properties = opts.properties;
		}
		if (Array.isArray(opts.sorts)) {
		body.sorts = opts.sorts;
		}
		if (Array.isArray(opts.filterGroups)) {
		body.filterGroups = opts.filterGroups;
		}
		return (await call(cred, "POST", "crm/v3/objects/contacts/search", body));
		};
		const listContacts = async (args) => {
		return (await genericList(args, "contacts"));
		};
		const deleteContact = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		if (!id) {
		return errorReturn("`contactId` is required.", "validation_failed");
		}
		return (await call(cred, "DELETE", `crm/v3/objects/contacts/${encodeURIComponent(id)}`, null));
		};
		// ── Handlers: Companies ────────────────────────────────────────────────
		const createCompany = async (args) => {
		const cred = String(args[0] ?? "");
		const props = (isPlainObject(args[1]) ? args[1] : {});
		if (Object.keys(props).length === 0) {
		return errorReturn("`properties` is required.", "validation_failed");
		}
		return (await call(cred, "POST", "crm/v3/objects/companies", {
		properties: stringifyProperties(props),
		}));
		};
		const updateCompany = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const props = (isPlainObject(args[2]) ? args[2] : {});
		if (!id) {
		return errorReturn("`companyId` is required.", "validation_failed");
		}
		if (Object.keys(props).length === 0) {
		return errorReturn("`properties` is required.", "validation_failed");
		}
		return (await call(cred, "PATCH", `crm/v3/objects/companies/${encodeURIComponent(id)}`, { properties: stringifyProperties(props) }));
		};
		const getCompany = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const sel = Array.isArray(args[2]) ? args[2] : null;
		if (!id) {
		return errorReturn("`companyId` is required.", "validation_failed");
		}
		let path = `crm/v3/objects/companies/${encodeURIComponent(id)}`;
		if (sel) {
		path += buildQueryString({ properties: sel.map((v) => String(v)).join(",") });
		}
		return (await call(cred, "GET", path, null));
		};
		const listCompanies = async (args) => {
		return (await genericList(args, "companies"));
		};
		// ── Handlers: Deals ────────────────────────────────────────────────────
		const createDeal = async (args) => {
		const cred = String(args[0] ?? "");
		const props = (isPlainObject(args[1]) ? args[1] : {});
		if (Object.keys(props).length === 0) {
		return errorReturn("`properties` is required.", "validation_failed");
		}
		return (await call(cred, "POST", "crm/v3/objects/deals", {
		properties: stringifyProperties(props),
		}));
		};
		const updateDeal = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const props = (isPlainObject(args[2]) ? args[2] : {});
		if (!id) {
		return errorReturn("`dealId` is required.", "validation_failed");
		}
		if (Object.keys(props).length === 0) {
		return errorReturn("`properties` is required.", "validation_failed");
		}
		return (await call(cred, "PATCH", `crm/v3/objects/deals/${encodeURIComponent(id)}`, { properties: stringifyProperties(props) }));
		};
		const getDeal = async (args) => {
		const cred = String(args[0] ?? "");
		const id = String(args[1] ?? "");
		const sel = Array.isArray(args[2]) ? args[2] : null;
		if (!id) {
		return errorReturn("`dealId` is required.", "validation_failed");
		}
		let path = `crm/v3/objects/deals/${encodeURIComponent(id)}`;
		if (sel) {
		path += buildQueryString({ properties: sel.map((v) => String(v)).join(",") });
		}
		return (await call(cred, "GET", path, null));
		};
		const listDeals = async (args) => {
		return (await genericList(args, "deals"));
		};
		// ── Handlers: Engagements (notes & tasks) ──────────────────────────────
		const createNote = async (args) => {
		const cred = String(args[0] ?? "");
		const body = String(args[1] ?? "");
		const associations = (isPlainObject(args[2]) ? args[2] : {});
		const extra = (isPlainObject(args[3]) ? args[3] : {});
		if (!body) {
		return errorReturn("`body` is required.", "validation_failed");
		}
		const props = {
		hs_note_body: body,
		hs_timestamp: now(),
		...extra,
		};
		const payload = {
		properties: stringifyProperties(props),
		};
		const assocs = buildAssociations(associations, "note");
		if (assocs.length > 0) {
		payload.associations = assocs;
		}
		return (await call(cred, "POST", "crm/v3/objects/notes", payload));
		};
		const createTask = async (args) => {
		const cred = String(args[0] ?? "");
		const subject = String(args[1] ?? "");
		const opts = (isPlainObject(args[2]) ? args[2] : {});
		const associations = (isPlainObject(args[3]) ? args[3] : {});
		if (!subject) {
		return errorReturn("`subject` is required.", "validation_failed");
		}
		const props = {
		hs_task_subject: subject,
		hs_task_status: String(opts.status ?? "NOT_STARTED"),
		hs_task_priority: String(opts.priority ?? "MEDIUM"),
		hs_task_type: String(opts.taskType ?? "TODO"),
		hs_timestamp: resolveTimestamp(opts.dueDate ?? null),
		};
		if (opts.body !== undefined) {
		props.hs_task_body = String(opts.body);
		}
		if (opts.ownerId !== undefined) {
		props.hubspot_owner_id = String(opts.ownerId);
		}
		const payload = {
		properties: stringifyProperties(props),
		};
		const assocs = buildAssociations(associations, "task");
		if (assocs.length > 0) {
		payload.associations = assocs;
		}
		return (await call(cred, "POST", "crm/v3/objects/tasks", payload));
		};
		// ── Exports: functions map ─────────────────────────────────────────────
		export const HubspotFunctions = {
		// Contacts.
		createContact,
		updateContact,
		getContact,
		searchContacts,
		listContacts,
		deleteContact,
		// Companies.
		createCompany,
		updateCompany,
		getCompany,
		listCompanies,
		// Deals.
		createDeal,
		updateDeal,
		getDeal,
		listDeals,
		// Engagements.
		createNote,
		createTask,
		};
		// ── Exports: credential types ──────────────────────────────────────────
		export const HubspotCredentialTypes = [
		{
		slug: CREDENTIAL_TYPE,
		title: "HubSpot Private App Token",
		icon: "users",
		fields: [
		{
		name: "access_token",
		title: "Access Token",
		type: "password",
		required: true,
		placeholder: "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		description: "Create one at Settings → Integrations → Private Apps in your HubSpot portal. Grant scopes for the objects you want to manage (crm.objects.contacts.read/write, crm.objects.deals.read/write, crm.objects.companies.read/write, etc.). Starts with `pat-`.",
		pattern: "^pat-",
		},
		],
		},
		];
		// ── Shared parameter metadata ──────────────────────────────────────────
		const credentialParam = {
		name: "credential",
		title: "Credential",
		description: "Slug of a saved `hubspot` credential (Private App token).",
		dataType: "string",
		formInputType: "resource",
		required: true,
		allowExpression: true,
		placeholder: "my_hubspot",
		resource: {
		type: "credential",
		listFn: "credential.list",
		modes: ["list", "expression"],
		searchable: true,
		filter: { type: CREDENTIAL_TYPE },
		},
		};
		const contactIdParam = {
		name: "contactId",
		title: "Contact ID",
		description: "Numeric HubSpot contact ID (e.g. `12345`). To fetch by email, prefix with `email:` — e.g. `\"email:ada@example.com\"`.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "12345",
		};
		const companyIdParam = {
		name: "companyId",
		title: "Company ID",
		description: "Numeric HubSpot company ID.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "67890",
		};
		const dealIdParam = {
		name: "dealId",
		title: "Deal ID",
		description: "Numeric HubSpot deal ID.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "9876543",
		};
		function propertiesParam(object, example) {
		return {
		name: "properties",
		title: "Properties",
		description: `Flat object of ${object} properties. Do NOT wrap in \`{properties: ...}\` — this module does that for you. Common fields vary by object; see HubSpot's property definitions.\n\nExample: ${example}`,
		dataType: "object",
		formInputType: "json",
		required: true,
		allowExpression: true,
		language: "json",
		rows: 6,
		};
		}
		const propertySelectParam = {
		name: "properties",
		title: "Properties to return",
		description: "Array of property names to include in the response. Omit to use HubSpot's default set. Pass `[\"*\"]` is NOT supported — enumerate what you need.",
		dataType: "array",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 3,
		advanced: true,
		};
		function listOptionsParam(defaults) {
		return {
		name: "options",
		title: "Options",
		description: `Recognized keys:\n limit : 1–100 (default 10)\n after : pagination cursor from previous response's \`paging.next.after\`\n properties : array of property names OR comma-separated string\n archived : bool — include archived records (default false)\n\n${defaults}`,
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 5,
		advanced: true,
		};
		}
		const commonErrors = {
		credential_not_found: "No credential with that slug exists in the vault.",
		token_missing: "The credential exists but has no `access_token` field.",
		validation_failed: "A required argument is missing or malformed.",
		transport: "Network failure calling api.hubapi.com.",
		hubspot_error: "HubSpot returned an error — see `hubspot_error.message` and `.category` in the response.",
		rate_limited: "Hit HubSpot rate limits (daily or burst). Slow down or upgrade your tier.",
		not_found: "No record with that ID exists (or it was archived).",
		};
		// ── Exports: function metadata ─────────────────────────────────────────
		export const HubspotFunctionMetadata = {
		// ===================== CONTACTS =====================
		createContact: {
		title: "Create contact",
		summary: "Add a new person to the CRM",
		description: "Calls `POST /crm/v3/objects/contacts`. HubSpot requires at least one of `email`, `firstname`, `lastname`, or another unique identifier. Returns the full contact record including the generated `id`. If a contact with the same email already exists, HubSpot returns a 409 error — use `updateContact` or the idempotent upsert pattern (lookup by email then patch).",
		group: "contacts",
		action: "write",
		icon: "user-plus",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["hubspot", "contact", "crm", "lead"],
		parameters: [
		credentialParam,
		propertiesParam("contact", '{email: "ada@example.com", firstname: "Ada", lastname: "Lovelace", phone: "+1-555-0100", company: "Analytical Engines", lifecyclestage: "lead"}'),
		],
		returnType: "object",
		returnDescription: "{id, properties: {…}, createdAt, updatedAt, archived}.",
		errors: { ...commonErrors, conflict: "A contact with that email already exists." },
		examples: [
		{
		title: "Sync a form submitter",
		code: 'hubspot.createContact "my_hubspot" {\n email: {{ form.email }},\n firstname: {{ form.first_name }},\n lastname: {{ form.last_name }},\n lead_source: "Website form"\n}',
		},
		],
		example: 'hubspot.createContact "my_hubspot" {email:"a@b.com", firstname:"Ada"}',
		},
		updateContact: {
		title: "Update contact",
		summary: "Patch properties on an existing contact",
		description: 'Calls `PATCH /crm/v3/objects/contacts/{id}`. Only the fields you supply are changed; unset fields keep their current values. Use the sentinel value `""` (empty string) to clear a property.',
		group: "contacts",
		action: "write",
		icon: "user-check",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "contact", "update"],
		parameters: [
		credentialParam,
		contactIdParam,
		propertiesParam("contact", '{lifecyclestage: "customer", hs_lead_status: "CONNECTED"}'),
		],
		returnType: "object",
		returnDescription: "Updated contact record.",
		errors: commonErrors,
		example: 'hubspot.updateContact "my_hubspot" "12345" {phone:"+1-555-0100"}',
		},
		getContact: {
		title: "Get contact",
		summary: "Fetch a single contact by ID or email",
		description: "Calls `GET /crm/v3/objects/contacts/{id}`. Pass a numeric ID, OR prefix with `email:` to look up by email address (uses the `idProperty=email` query parameter). Returns `{error: 'not_found'}` with code `not_found` if no match.",
		group: "contacts",
		action: "read",
		icon: "user",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "contact", "lookup"],
		parameters: [credentialParam, contactIdParam, propertySelectParam],
		returnType: "object",
		returnDescription: 'Contact record or `{error: "not_found"}`.',
		errors: commonErrors,
		examples: [
		{ title: "By ID", code: 'hubspot.getContact "my_hubspot" "12345"' },
		{ title: "By email", code: 'hubspot.getContact "my_hubspot" "email:ada@example.com"' },
		{
		title: "With custom property set",
		code: 'hubspot.getContact "my_hubspot" "12345" ["email","firstname","phone","lifecyclestage"]',
		},
		],
		example: 'hubspot.getContact "my_hubspot" "12345"',
		},
		searchContacts: {
		title: "Search contacts",
		summary: "Full-text search across contact properties",
		description: "Calls `POST /crm/v3/objects/contacts/search`. Matches against firstname, lastname, email, phone, and company by default. For precise filtering, pass `filterGroups` — an array of `{filters: [{propertyName, operator, value}]}`. Operators: `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE`, `BETWEEN`, `IN`, `NOT_IN`, `HAS_PROPERTY`, `NOT_HAS_PROPERTY`, `CONTAINS_TOKEN`, `NOT_CONTAINS_TOKEN`.",
		group: "contacts",
		action: "query",
		icon: "search",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "contact", "search", "filter"],
		parameters: [
		credentialParam,
		{
		name: "query",
		title: "Query",
		description: "Free-text search string. Pass an empty string when using `filterGroups` exclusively.",
		dataType: "string",
		formInputType: "text",
		required: false,
		allowExpression: true,
		placeholder: "ada@example.com",
		},
		{
		name: "options",
		title: "Options",
		description: "Recognized keys:\n limit : 1–100 (default 10)\n after : pagination cursor\n properties : array of property names to return\n sorts : array of `{propertyName, direction: 'ASCENDING'\|'DESCENDING'}`\n filterGroups : array of filter groups — see description for operator list",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 6,
		advanced: true,
		},
		],
		returnType: "object",
		returnDescription: "{total, results: [], paging: {next: {after}}}.",
		errors: commonErrors,
		examples: [
		{ title: "By email", code: 'hubspot.searchContacts "my_hubspot" "ada@example.com"' },
		{
		title: "Structured filter",
		code: 'hubspot.searchContacts "my_hubspot" "" {\n filterGroups: [{filters:[{propertyName:"lifecyclestage", operator:"EQ", value:"lead"}]}],\n limit: 50\n}',
		},
		],
		example: 'hubspot.searchContacts "my_hubspot" "ada@example.com"',
		},
		listContacts: {
		title: "List contacts",
		summary: "Page through contacts",
		description: "Calls `GET /crm/v3/objects/contacts`. Cursor-based pagination via `options.after`.",
		group: "contacts",
		action: "query",
		icon: "users",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "contact", "list", "paginate"],
		parameters: [credentialParam, listOptionsParam("Default sort is by `createdAt` descending.")],
		returnType: "object",
		returnDescription: "{results: [], paging?: {next: {after, link}}}.",
		errors: commonErrors,
		example: 'hubspot.listContacts "my_hubspot" {limit: 50}',
		},
		deleteContact: {
		title: "Delete (archive) contact",
		summary: "Archive a contact by ID",
		description: "Calls `DELETE /crm/v3/objects/contacts/{id}`. HubSpot soft-deletes (archives) rather than hard-delete — the contact can be restored via the UI within 90 days. GDPR erasure requires a separate `/gdpr-delete` endpoint not exposed here.",
		group: "contacts",
		action: "delete",
		icon: "user-minus",
		capability: "manage_options",
		sideEffects: ["makes_http_call", "destructive"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "contact", "delete", "archive"],
		parameters: [credentialParam, contactIdParam],
		returnType: "object",
		returnDescription: "{ok: true} on success.",
		errors: commonErrors,
		example: 'hubspot.deleteContact "my_hubspot" "12345"',
		},
		// ===================== COMPANIES =====================
		createCompany: {
		title: "Create company",
		summary: "Add a new organization to the CRM",
		description: "Calls `POST /crm/v3/objects/companies`. Common fields: `name`, `domain`, `industry`, `city`, `country`, `numberofemployees`, `annualrevenue`.",
		group: "companies",
		action: "write",
		icon: "building",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["hubspot", "company", "organization"],
		parameters: [
		credentialParam,
		propertiesParam("company", '{name: "Acme Inc", domain: "acme.com", industry: "Software", numberofemployees: 120}'),
		],
		returnType: "object",
		returnDescription: "Created company record with generated `id`.",
		errors: commonErrors,
		example: 'hubspot.createCompany "my_hubspot" {name:"Acme", domain:"acme.com"}',
		},
		updateCompany: {
		title: "Update company",
		summary: "Patch properties on an existing company",
		description: "Calls `PATCH /crm/v3/objects/companies/{id}`. Only supplied fields are changed.",
		group: "companies",
		action: "write",
		icon: "edit-3",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "company", "update"],
		parameters: [
		credentialParam,
		companyIdParam,
		propertiesParam("company", "{numberofemployees: 150, annualrevenue: 5000000}"),
		],
		returnType: "object",
		returnDescription: "Updated company record.",
		errors: commonErrors,
		example: 'hubspot.updateCompany "my_hubspot" "67890" {industry:"SaaS"}',
		},
		getCompany: {
		title: "Get company",
		summary: "Fetch a single company by ID",
		description: "Calls `GET /crm/v3/objects/companies/{id}`.",
		group: "companies",
		action: "read",
		icon: "building",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "company", "lookup"],
		parameters: [credentialParam, companyIdParam, propertySelectParam],
		returnType: "object",
		returnDescription: 'Company record or `{error: "not_found"}`.',
		errors: commonErrors,
		example: 'hubspot.getCompany "my_hubspot" "67890"',
		},
		listCompanies: {
		title: "List companies",
		summary: "Page through companies",
		description: "Calls `GET /crm/v3/objects/companies`.",
		group: "companies",
		action: "query",
		icon: "list",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "company", "list"],
		parameters: [credentialParam, listOptionsParam("")],
		returnType: "object",
		returnDescription: "{results: [], paging?: {next: {after}}}.",
		errors: commonErrors,
		example: 'hubspot.listCompanies "my_hubspot" {limit: 25}',
		},
		// ===================== DEALS =====================
		createDeal: {
		title: "Create deal",
		summary: "Open a new sales opportunity",
		description: "Calls `POST /crm/v3/objects/deals`. Required: `dealname`. Strongly recommended: `dealstage` (must match a stage in your pipeline — the API value, not the label) and `pipeline`. Other common fields: `amount`, `closedate` (epoch ms or ISO), `hubspot_owner_id`.",
		group: "deals",
		action: "write",
		icon: "dollar-sign",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["hubspot", "deal", "opportunity", "sales"],
		parameters: [
		credentialParam,
		propertiesParam("deal", '{dealname: "Acme Q4 renewal", amount: 15000, dealstage: "appointmentscheduled", pipeline: "default", closedate: "2026-06-30"}'),
		],
		returnType: "object",
		returnDescription: "Created deal record with generated `id`.",
		errors: commonErrors,
		examples: [
		{
		title: "Create an MQL deal",
		code: 'hubspot.createDeal "my_hubspot" {\n dealname: "{{ form.company_name }} trial",\n dealstage: "appointmentscheduled",\n pipeline: "default",\n amount: 2500\n}',
		},
		],
		example: 'hubspot.createDeal "my_hubspot" {dealname:"Big one", amount:10000}',
		},
		updateDeal: {
		title: "Update deal",
		summary: "Advance a deal through the pipeline or change its value",
		description: "Calls `PATCH /crm/v3/objects/deals/{id}`. Most common use: setting `dealstage` to move the deal forward, or updating `amount` / `closedate` as the deal evolves.",
		group: "deals",
		action: "write",
		icon: "trending-up",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "deal", "update", "stage"],
		parameters: [
		credentialParam,
		dealIdParam,
		propertiesParam("deal", '{dealstage: "closedwon", amount: 12500}'),
		],
		returnType: "object",
		returnDescription: "Updated deal record.",
		errors: commonErrors,
		example: 'hubspot.updateDeal "my_hubspot" "9876" {dealstage:"closedwon"}',
		},
		getDeal: {
		title: "Get deal",
		summary: "Fetch a single deal by ID",
		description: "Calls `GET /crm/v3/objects/deals/{id}`.",
		group: "deals",
		action: "read",
		icon: "dollar-sign",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "deal", "lookup"],
		parameters: [credentialParam, dealIdParam, propertySelectParam],
		returnType: "object",
		returnDescription: 'Deal record or `{error: "not_found"}`.',
		errors: commonErrors,
		example: 'hubspot.getDeal "my_hubspot" "9876"',
		},
		listDeals: {
		title: "List deals",
		summary: "Page through deals",
		description: "Calls `GET /crm/v3/objects/deals`.",
		group: "deals",
		action: "query",
		icon: "list",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: true,
		since: "1.0.0",
		tags: ["hubspot", "deal", "list", "pipeline"],
		parameters: [credentialParam, listOptionsParam("")],
		returnType: "object",
		returnDescription: "{results: [], paging?: {next: {after}}}.",
		errors: commonErrors,
		example: 'hubspot.listDeals "my_hubspot" {limit: 50, properties: ["dealname","amount","dealstage"]}',
		},
		// ===================== ENGAGEMENTS =====================
		createNote: {
		title: "Create note",
		summary: "Attach a note to a contact, company, or deal",
		description: 'Calls `POST /crm/v3/objects/notes`. Pass the body via `body` (HTML allowed). Optional `associations` argument attaches the note to records — pass an object like `{contact: "12345", deal: "9876"}` and the module converts it to HubSpot\'s association type IDs (202 contact, 190 company, 214 deal) automatically.',
		group: "engagements",
		action: "write",
		icon: "sticky-note",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["hubspot", "note", "engagement"],
		parameters: [
		credentialParam,
		{
		name: "body",
		title: "Body",
		description: "Note content. HTML allowed (HubSpot renders it in the CRM UI).",
		dataType: "string",
		formInputType: "textarea",
		required: true,
		allowExpression: true,
		rows: 4,
		placeholder: "Called customer — wants a demo next week.",
		},
		{
		name: "associations",
		title: "Associations",
		description: "Flat object of `{objectType: id}` to attach the note to. Recognized types: `contact`, `company`, `deal`, `ticket`. Values can be a single ID or an array of IDs.",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 3,
		},
		{
		name: "extraProperties",
		title: "Extra properties",
		description: "Any additional properties to set (e.g. `hubspot_owner_id`, `hs_timestamp`). `hs_timestamp` defaults to now.",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 3,
		advanced: true,
		},
		],
		returnType: "object",
		returnDescription: "Created note engagement record.",
		errors: commonErrors,
		examples: [
		{
		title: "Note on a contact",
		code: 'hubspot.createNote "my_hubspot" "Followed up via email" {contact: "12345"}',
		},
		],
		example: 'hubspot.createNote "my_hubspot" "Called today" {contact:"12345"}',
		},
		createTask: {
		title: "Create task",
		summary: "Schedule a follow-up task on a CRM record",
		description: "Calls `POST /crm/v3/objects/tasks`. Pass `subject` and optionally `body`, `dueDate` (ISO or epoch ms — sets `hs_timestamp`), `priority` ('LOW'\|'MEDIUM'\|'HIGH'), `status` ('NOT_STARTED'\|'IN_PROGRESS'\|'WAITING'\|'COMPLETED'\|'DEFERRED'), `taskType` ('CALL'\|'EMAIL'\|'TODO'), `ownerId`. Attach to records via `associations` (same shape as `createNote`).",
		group: "engagements",
		action: "write",
		icon: "check-square",
		capability: "manage_options",
		sideEffects: ["makes_http_call"],
		idempotent: false,
		since: "1.0.0",
		tags: ["hubspot", "task", "engagement", "todo"],
		parameters: [
		credentialParam,
		{
		name: "subject",
		title: "Subject",
		description: "Short task title shown in the CRM task list.",
		dataType: "string",
		formInputType: "text",
		required: true,
		allowExpression: true,
		placeholder: "Follow up on demo request",
		},
		{
		name: "options",
		title: "Options",
		description: "Recognized keys:\n body : longer description\n dueDate : ISO 8601 string or epoch ms\n priority : 'LOW' \| 'MEDIUM' \| 'HIGH' (default 'MEDIUM')\n status : 'NOT_STARTED' (default) \| 'IN_PROGRESS' \| 'WAITING' \| 'COMPLETED' \| 'DEFERRED'\n taskType : 'CALL' \| 'EMAIL' \| 'TODO' (default 'TODO')\n ownerId : hubspot_owner_id to assign to",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 6,
		},
		{
		name: "associations",
		title: "Associations",
		description: "Same shape as `createNote`: `{contact: id, company: id, deal: id, ticket: id}`.",
		dataType: "object",
		formInputType: "json",
		required: false,
		allowExpression: true,
		language: "json",
		rows: 3,
		},
		],
		returnType: "object",
		returnDescription: "Created task engagement record.",
		errors: commonErrors,
		examples: [
		{
		title: "Task on a deal",
		code: 'hubspot.createTask "my_hubspot" "Send contract" {\n dueDate: "2026-04-25T10:00:00Z",\n priority: "HIGH",\n taskType: "EMAIL"\n} {deal: "9876"}',
		},
		],
		example: 'hubspot.createTask "my_hubspot" "Call back" {priority:"HIGH"} {contact:"12345"}',
		},
		};
		// ── Exports: module metadata ───────────────────────────────────────────
		export const HubspotModuleMetadata = {
		description: "Sync form submissions into HubSpot contacts, create and advance deals through your sales pipeline, attach notes and tasks to records, and search your CRM — all from RobinPath scripts.\n\nAuthenticated via a Private App access token (HubSpot deprecated legacy API keys in 2022). Store the token as a `hubspot` credential and pass the slug as the first argument to every method.\n\nAll CRM object fields are passed as a flat object. The module wraps them in HubSpot's `properties` envelope automatically. Responses are returned untouched so you can read `.id`, `.properties.email`, `.createdAt`, etc.",
		slug: "hubspot",
		title: "HubSpot",
		summary: "Contacts, companies, deals, notes, tasks — manage your HubSpot CRM pipeline",
		category: "sales",
		icon: "icon.svg",
		color: "#FF7A59",
		version: "0.2.0",
		docsUrl: "https://docs.robinpath.com/modules/hubspot",
		status: "stable",
		requires: [],
		minNodeVersion: "18.0.0",
		credentialsType: CREDENTIAL_TYPE,
		operationGroups: {
		contacts: { title: "Contacts", description: "People records — the primary CRM object.", order: 1 },
		companies: { title: "Companies", description: "Organizations that contacts belong to.", order: 2 },
		deals: { title: "Deals", description: "Sales opportunities moving through a pipeline.", order: 3 },
		engagements: { title: "Engagements", description: "Notes and tasks attached to CRM records.", order: 4 },
		},
		methods: Object.keys(HubspotFunctions),
		};
		//# sourceMappingURL=hubspot.js.map

+1

dist/hubspot.js.map

+6

dist/index.d.ts

		import type { ModuleAdapter } from "@robinpath/core";
		declare const HubspotModule: ModuleAdapter;
		export default HubspotModule;
		export { HubspotModule };
		export { HubspotFunctions, HubspotFunctionMetadata, HubspotModuleMetadata, HubspotCredentialTypes, } from "./hubspot.js";
		//# sourceMappingURL=index.d.ts.map

+1

dist/index.d.ts.map

{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AASrD,QAAA,MAAM,aAAa,EAAE,aAQpB,CAAC;AAEF,eAAe,aAAa,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

+14

dist/index.js

		import { HubspotFunctions, HubspotFunctionMetadata, HubspotModuleMetadata, HubspotCredentialTypes, configureHubspot, } from "./hubspot.js";
		const HubspotModule = {
		name: "hubspot",
		functions: HubspotFunctions,
		functionMetadata: HubspotFunctionMetadata,
		moduleMetadata: HubspotModuleMetadata,
		credentialTypes: HubspotCredentialTypes,
		configure: configureHubspot,
		global: false,
		};
		export default HubspotModule;
		export { HubspotModule };
		export { HubspotFunctions, HubspotFunctionMetadata, HubspotModuleMetadata, HubspotCredentialTypes, } from "./hubspot.js";
		//# sourceMappingURL=index.js.map

+1

dist/index.js.map

{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,MAAM,aAAa,GAAkB;IACnC,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,gBAAgB;IAC3B,gBAAgB,EAAE,uBAAuB;IACzC,cAAc,EAAE,qBAAqB;IACrC,eAAe,EAAE,sBAAsB;IACvC,SAAS,EAAE,gBAAgB;IAC3B,MAAM,EAAE,KAAK;CACd,CAAC;AAEF,eAAe,aAAa,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

+20

-8

package.json

		{
		"name": "@robinpath/hubspot",
		"version": "0.1.1",
		"version": "0.3.0",
		"publishConfig": {
		@@ -23,12 +23,18 @@ "access": "public"
		"peerDependencies": {
		"@robinpath/core": ">=0.20.0"
		"@robinpath/core": ">=0.40.0"
		},
		"devDependencies": {
		"@robinpath/core": "^0.30.1",
		"@robinpath/core": "^0.40.0",
		"typescript": "^5.6.0"
		},
		"description": "HubSpot module for RobinPath.",
		"description": "HubSpot CRM API v3 — contacts, companies, deals, notes, tasks, and list membership. Uses the encrypted credential vault for Private App tokens.",
		"keywords": [
		"hubspot",
		"crm"
		"crm",
		"sales",
		"marketing",
		"contacts",
		"deals",
		"companies",
		"pipeline"
		],
		@@ -38,7 +44,13 @@ "license": "MIT",
		"category": "crm",
		"type": "integration",
		"auth": "bearer-token",
		"type": "module",
		"auth": "credential-vault",
		"functionCount": 12,
		"baseUrl": "https://api.hubapi.com"
		"baseUrl": "https://api.hubapi.com",
		"language": "nodejs",
		"platforms": [
		"cloud",
		"cli",
		"desktop"
		]
		}
		}

+1

-1

README.md

		@@ -22,3 +22,3 @@ # @robinpath/hubspot
		```bash
		npm install @robinpath/hubspot
		robinpath add @robinpath/hubspot
		```
		@@ -25,0 +25,0 @@

@robinpath/hubspot - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics