@tradingcards-dev/config

@tradingcards-dev/config provides encrypted config storage for HubSpot serverless functions — no third-party services or custom CRM objects required. Used for Settings, API keys, and other app data.

Configs are stored as AES-256-GCM encrypted text directly in the HubSpot Files API, scoped per portal and app.

Example

Say your template has a settings page where the user enters a Mapbox API key. You want that key to persist across sessions without storing it in a custom CRM property or an external database.

Saving the key (settings function):

const { saveConfig } = require('@tradingcards-dev/config');

exports.main = async (context) => {
  const { portalId, mapboxKey } = context.parameters;
  const token = process.env.PRIVATE_APP_ACCESS_TOKEN;

  await saveConfig(token, portalId, 'my_app_id', { mapboxKey });
  return { success: true };
};

Reading the key (card or app function):

const { getConfig } = require('@tradingcards-dev/config');

exports.main = async (context) => {
  const { portalId } = context.parameters;
  const token = process.env.PRIVATE_APP_ACCESS_TOKEN;

  const config = await getConfig(token, portalId, 'my_app_id');
  const { mapboxKey } = config;

  // use mapboxKey...
};

The config is encrypted before being written and decrypted on read — your token never leaves HubSpot’s infrastructure, and the stored file is unreadable without the originating token.

Installation

npm install @tradingcards-dev/config

Or add it directly to your template’s src/app/functions/package.json:

{
  "dependencies": {
    "@tradingcards-dev/config": "^1.0.0"
  }
}

Available on npmjs.com.

API

The appId string identifies your app’s config file — use a unique value per template (e.g. my_app_id). The token is your PRIVATE_APP_ACCESS_TOKEN environment variable.

getConfig(token, portalId, appId)

Reads and decrypts config for the given portal and app. Returns an empty object {} if no config file exists yet.

Parameter	Type	Description
token	string	HubSpot private app access token
portalId	string	HubSpot portal ID
appId	string	Unique identifier for your app’s config

saveConfig(token, portalId, appId, config)

Encrypts and saves config to the HubSpot Files API. Creates the file on first save, replaces it on subsequent saves.

Parameter	Type	Description
token	string	HubSpot private app access token
portalId	string	HubSpot portal ID
appId	string	Unique identifier for your app’s config
config	object	Plain object to encrypt and store

How it works

Config is stored in HubSpot Files API under /TradingCards/{portalId}-{appId}.txt. The file contents are AES-256-GCM encrypted using a key derived from the private app access token via SHA-256. This means config is portal-scoped — each portal has its own encrypted file that only its own token can decrypt.

Required HubSpot scope

Your private app must have the files scope to read and write to the Files API.

Source

github.com/TradingCards-Dev/TC-Packages