Skip to content

@tradingcards-dev/setup

@tradingcards-dev/setup creates the CRM resources an app needs before it can work: property groups, properties and pipelines. A template lists them in the setup block of its tc-config.json; the runner checks which already exist in the portal and creates the rest, using the app’s own access token (PRIVATE_APP_ACCESS_TOKEN). Running it again is safe: anything that already exists is skipped.

It is the package behind the One-time CRM setup pattern.

Source: TradingCards-Dev/TC-Packages. npm: @tradingcards-dev/setup.

const { getSetupStatus, runSetup, formatSetupFailures } = require('@tradingcards-dev/setup');
const templateConfig = require('../../../tc-config.json');
const status = await getSetupStatus(templateConfig); // what exists, what is missing
const result = await runSetup(templateConfig); // create what is missing
if (result.failed.length > 0) console.error(formatSetupFailures(result.failed));

Add the package to the functions package.json and mark it external when bundling (--external:@tradingcards-dev/setup), the same way as @tradingcards-dev/config.

"setup": {
"enabled": true,
"crmChangesSummary": [{ "objectType": "deals", "title": "...", "description": "..." }],
"steps": [
{ "kind": "propertyGroup", "objectType": "deals", "name": "my_group", "label": "My Group" },
{
"kind": "property",
"objectType": "deals",
"groupName": "my_group",
"name": "my_property",
"label": "My Property",
"type": "string",
"fieldType": "text"
},
{
"kind": "pipeline",
"objectType": "deals",
"name": "my_pipeline",
"label": "My Pipeline",
"stages": [
{ "label": "Open", "metadata": { "probability": "0.2" } },
{ "label": "Won", "metadata": { "probability": "1.0" } },
{ "label": "Lost", "metadata": { "probability": "0.0" } }
]
}
]
}

Steps run in the order listed, so declare a property group before the properties that use it.

KindMatched in the portal byNotes
propertyGroupobjectType + name
propertyobjectType + nameFails if its groupName does not exist.
pipelineobjectType + label (case-insensitive)An existing pipeline is left untouched. Stage metadata follows the Pipelines API: probability for deals, ticketState for tickets. stageId and displayOrder are optional.

The step discriminator is kind, not type, because a property step already uses type for the HubSpot property type.

setup.propertyGroups and setup.properties are still read. They run before steps, groups first, and can be mixed with steps in the same config.

getSetupStatus resolves to docsUrl, crmChangesSummary, scopeStatus, steps (one entry per step with exists) and resourceStatus (complete, missingItems, existingItems, plus the group and property counts the settings pages read).

runSetup resolves to created, skipped, failed, summary and steps (one entry per step in run order with status). Created entries carry what HubSpot assigned, such as a pipeline’s id and stage ids. A failed step is recorded with HubSpot’s error and the run continues.

The template’s app needs the scopes for what it creates, for example crm.schemas.deals.write for deal property groups and properties. A pipeline step needs a scope that allows pipeline writes for its object; check the Pipelines API reference when adding one.