extole-hubspot-app

Imported from extole/extole-hubspot-app (AGENTS.md). Install upstream with npx skills add extole/extole-hubspot-app. Copyright stays with the author.

AGENTS.md

Project: Extole HubSpot App

HubSpot app (2026.03 platform) connecting HubSpot to Extole's offer platform. See install.md for the installation guide and ARCHITECTURE.md for the technical overview.

Deploying

# Upload to HubSpot
hs project upload --account extolehsappdev

# Dev mode (hot reload — triggers install flow on first run)
hs project dev --testing-account extolehsappdev --project-account extolehsappdev

Always run deploys directly — never hand off to the user.

Target account alias: extolehsappdev (portal 245866198)

Secrets

Add secrets via: hs secret add <name> --account extolehsappdev

Commit messages

Do not add Co-Authored-By lines.

IMPORTANT: IF THE 'HubSpotDev' MCP SERVER IS INSTALLED USE THE TOOLS BEFORE TRYING TO MANUALLY USE CLI COMMANDS OR BEFORE TRYING TO DO ANYTHING WITH HUBSPOT ASSETS

HubSpot Project Information

• The project configuration is in the hsproject.json file
• A directory is considered a part of the project if it or a directory above it contains a hsproject.json file
• The project src directory is defined in the srcDir field in the hsproject.json
• The project's platform version is defined in platformVersion in the hs project.json
• The platformVersion determines what features the project has access to as well as the shape of the configuration files

Local Development

Local Development Server (hs project dev)

• Start a local development server with hs project dev to view extension changes without refreshing
• The server runs on your local machine and syncs changes to HubSpot in real-time
• When the server is running, UI extensions (cards, settings pages) display a "Developing locally" tag
• Saving changes to JSX files automatically refreshes the page

Local Proxy Configuration (local.json)

• During local development, you can proxy hubspot.fetch() requests to a locally running backend
• Create a local.json file in the same directory as your app's *-hsmeta.json file
• The proxy configuration maps HTTPS URLs to local URLs:

  {
    "proxy": {
      "https://example.com": "http://localhost:8080"
    }
  }

• Important: Proxy URLs must be valid HTTPS URLs (the key, not the value)
• Path-based routing is NOT supported (e.g., "https://example.com/a": "http://localhost:8080" will not work)
• When a local.json file is detected, the CLI confirms the proxy is active
• To disable the proxy, rename the file to local.json.bak and restart the dev server

Request Signing with CLIENT_SECRET

• You can inject the CLIENT_SECRET environment variable when starting the local dev server:

  CLIENT_SECRET="abc123" hs project dev

• This enables request signing during local development for testing secure backend communications

npm packages

@hubspot/ui-extensions

• In the @hubspot/ui-extensions npm package, only the component properties defined by the component are valid. style properties are not valid

hubspot.fetch API

• hubspot.fetch is a function provided by @hubspot/ui-extensions for making HTTP requests from UI components
• Critical: hubspot.fetch requires fully qualified domain names (FQDN) with HTTPS - relative paths are NOT supported
• All URLs must be added to the permittedUrls.fetch array in the app's *-hsmeta.json configuration file
• Example:

  "permittedUrls": {
    "fetch": ["https://api.example.com", "https://api.hubapi.com"],
    "iframe": [],
    "img": []
  }

• Fetch URLs must be valid HTTPS URLs and cannot be localhost
• To call a local backend during development, use the local.json proxy configuration (see Local Development section)

Component Information

General

• Component configuration files must end with -hsmeta.json
• The uid field in the -hsmeta.json files must be unique with the project
• The type field in the -hsmeta.json files defines the type of the component
• Components can not be in nested subdirectories, only the specified directories in their corresponding component rules.
• Example components can be found in https://github.com/HubSpot/hubspot-project-components. The directories are split up by platform version and follow this format ${platformVersion}/components. Note the project create tool only supports platform versions >= 2025.2.
• All component subdirectories must be in the project source directory

app component

• There can only be one app component
• app component must be in the app directory
• If the config.distribution field is set to marketplace, the only valid config.auth.type value is oauth

card

• card components must be in the app/cards directory
• The global window object is not available in the card component
• Cannot use window.fetch, and instead must use the hubspot.fetch function provided by the @hubspot/ui-extensions npm package. Any urls called with the hubspot.fetch function must be added to the config.permittedUrls.fetch array in the app component's hsmeta.json file
• hubspot.fetch requires fully qualified HTTPS URLs (e.g., https://api.example.com/endpoint) - relative paths like /api/endpoint are NOT supported
• Only components exported from the @hubspot/ui-extensions npm package can be used in card components

app-event

• app-event components must be in the app/app-events directory

app-object

• app-object components must be in the app/app-object directory

app-function

• app-function components must be in the app/functions directory
• app-function components are not available when config.distribution is set to marketplace in the app component -hsmeta.son file

settings

• There can only be one settings component
• settings components must be in the app/settings directory
• The global window object is not available in the settings component
• Cannot use window.fetch, and instead must use the hubspot.fetch function provided by the @hubspot/ui-extensions npm package. Any urls called with the hubspot.fetch function must be added to the config.permittedUrls.fetch array in the app component's hsmeta.json file
• hubspot.fetch requires fully qualified HTTPS URLs - relative paths are NOT supported
• Only components exported from the @hubspot/ui-extensions npm package can be used in settings components
• React Components from @hubspot/ui-extensions/crm cannot be used in settings components

scim

• There can only be one scim component
• scim components must be in the app/scim directory

webhooks

• There can only be one webhooks component.
• webhooks components must be in the app/webhooks directory

workflow-actions

• workflow-action components must be in the app/workflow-actions directory

HubSpot CLI commands

• All the commands and subcommands have a --help argument that provides details on the command and it's arguments
• The help output is standard yargs output
• The commands for working with projects in HubSpot are subcommands of hs project
• Debugging flag that can be added to hs commands and subcommands: --debug
• Debugging problems with CLI installation: hs doctor

Project Commands

• hs project create - Create a new HubSpot project interactively
• hs project upload - Upload the project to HubSpot (build is created automatically)
• hs project deploy - Deploy a specific build of the project to make it live
• hs project dev - Start a local development server for real-time development of UI extensions
• hs project watch - Watch for file changes and automatically upload them
• hs project list - List all projects in the account
• hs project download - Download a project from HubSpot to local
• hs project open - Open the current project page in the browser
• hs project logs - View logs for deployed projects
• hs project list-builds - List all builds for a project
• hs project validate - Validate project configuration files
• hs project migrate - Migrate a project to a newer platform version
• hs project migrate-app - Migrate a legacy app to the projects framework
• hs project clone-app - Clone an existing app configuration

Account Management

• hs init - Initial setup of the hubspot configuration file
• hs account auth - Authenticate a new account (requires browser interaction)
• hs account list - List all configured accounts
• hs account use - Switch the default account
• hs account info - Display information about an account
• hs account rename - Rename an account in the config
• hs account remove - Remove an account from the config
• hs account clean - Clean up invalid/expired authentication
• hs account create-override - Create a project-specific account override
• hs account remove-override - Remove a project-specific account override

CMS Commands

• hs cms upload <src> <dest> - Upload files to HubSpot
• hs cms fetch <src> <dest> - Download files from HubSpot
• hs cms watch <src> <dest> - Watch for changes and automatically upload
• hs cms list <path> - List remote files in HubSpot
• hs cms delete <path> - Delete files from HubSpot
• hs cms mv <srcPath> <destPath> - Move/rename files in HubSpot
• hs cms function list - List all serverless functions
• hs cms function logs <path> - View logs for a serverless function
• hs create template <name> - Create a new template
• hs create module <name> - Create a new module
• hs create function <name> - Create a new serverless function
• hs theme preview - Preview a theme locally at https://hslocal.net:3000/

Sandbox Management

• hs sandbox create - Create a development sandbox account
• hs sandbox delete - Delete a sandbox account

Secrets Management

• hs secret list - List secrets for serverless functions
• hs secret add <name> <value> - Add a secret
• hs secret update <name> <value> - Update a secret
• hs secret delete <name> - Delete a secret

Test Account Management

• hs test-account create - Create a configurable test account
• hs test-account delete - Delete a test account
• hs test-account import-data - Import test data

General

• Follow existing patterns in the codebase
• Use proper component structure based on component type in the -hsmeta.json file
• Ensure configuration files follow HubSpot naming conventions
• Always validate that components are placed in correct directories
• When working with UI extensions, remember that hubspot.fetch requires HTTPS URLs in permittedUrls.fetch
• Use hs project dev for iterative development of cards and settings pages
• Use local.json to proxy API requests to a local backend during development