Using the HubSpot TypeScript SDK in Workflood (Node 20 Runtime)
Complete reference for writing custom TypeScript workflow actions in Node 20 with the pre-injected @hubspot/api-client and full Monaco editor autocomplete.
The Node 20 Execution Context
In Workflood, all TypeScript actions execute in dedicated **Node 20** container sandboxes.
The official HubSpot client library (`@hubspot/api-client`) is pre-installed, pre-configured with your workspace's encrypted credentials, and globally available as `hubspot.client`.
**Key Environment Properties:** - **Runtime:** Node.js 20 LTS - **SDK Version:** `@hubspot/api-client` v11+ - **Global Object:** `hubspot.client` (Fully typed with CRM, Marketing, CMS, and Settings APIs) - **Memory Limit:** 512MB RAM per action - **Startup Latency:** <50ms with zero cold starts
Core SDK Methods & Common CRM Operations
Here are the most frequently used SDK methods for standard CRM automation:
// 1. Fetch Contact with specific properties
const contact = await hubspot.client.crm.contacts.basicApi.getById('12345', [
'email', 'firstname', 'lastname', 'lifecyclestage'
])
// 2. Search Deals using Filter Groups
const searchResponse = await hubspot.client.crm.deals.searchApi.doSearch({
filterGroups: [
{
filters: [
{ propertyName: 'dealstage', operator: 'EQ', value: 'closedwon' },
{ propertyName: 'amount', operator: 'GTE', value: '10000' }
]
}
],
properties: ['dealname', 'amount', 'closedate'],
limit: 50
})
// 3. Batch Update Company Records
await hubspot.client.crm.companies.batchApi.update({
inputs: [
{ id: '101', properties: { tier: 'Enterprise' } },
{ id: '102', properties: { tier: 'Mid-Market' } }
]
})Handler Signature & Return Values
Every TypeScript action must export a default asynchronous function named `main` or `handler`. Return JSON-serializable data so the run viewer can display structured outputs:
export default async function main(input: {
objectId?: string
[key: string]: unknown
}): Promise<{
status: 'success' | 'skipped' | 'error'
recordsProcessed: number
details: Record<string, unknown>
}> {
// Your logic here
return {
status: 'success',
recordsProcessed: 1,
details: { objectId: input.objectId, processedAt: new Date().toISOString() }
}
}Autocomplete & Types in Monaco Editor
The Workflood in-browser code editor includes full TypeScript type definitions for `@hubspot/api-client`. You get IntelliSense auto-completion for properties, parameters, and return types as you type.
Deal Health Score Calculator
Calculate health scores (0-100) for open deals based on close date recency, stage velocity, and owner assignment, then sync back to HubSpot.
Frequently Asked Questions
Can I install custom npm packages in TypeScript actions?
Workflood comes bundled with core utilities including Axios, Lodash, Date-fns, and the HubSpot SDK. Support for custom npm package dependencies via package.json is available on Pro & Enterprise plans.