@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 missingconst result = await runSetup(templateConfig); // create what is missingif (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.
Config
Section titled “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.
| Kind | Matched in the portal by | Notes |
|---|---|---|
propertyGroup | objectType + name | |
property | objectType + name | Fails if its groupName does not exist. |
pipeline | objectType + 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.
Legacy lists
Section titled “Legacy lists”setup.propertyGroups and setup.properties are still read. They run before steps, groups first, and can be mixed with steps in the same config.
Results
Section titled “Results”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.
Scopes
Section titled “Scopes”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.