A Node.js server that manages property mappings between native systems and HubSpot, featuring OAuth integration, Prisma database management, and a caching layer for optimized HubSpot API interactions.

• What this project does
• Why is this project useful
• Getting started with the project
  • Setup
  • Scopes
• Endpoints
  • Authentication Endpoints
  • Properties Endpoints
  • Mappings Endpoints
• Available Scripts
• Dependencies
  • Core
  • Development
• Where to get help?
• Who maintains and contributes to this project
• License

This project is an Express.js application designed to integrate with HubSpot's API, facilitating the management and synchronization of properties and mappings between a native system and HubSpot. For the client-side interface, please refer to the React frontend repository which works in conjunction with this backend application.

Key concepts:

• Properties in HubSpot refer to the fields that store information about CRM objects (contacts, companies, etc.). For instance, a contact can have properties like "First Name", "Last Name", or custom properties specific to your business needs.

• Property mapping refers to the configuration process where users set up the rules or criteria that define how properties from their native system should map to HubSpot properties. This ensures data consistency when syncing between systems.

• Property definition involves specifying the nature and characteristics of the property, such as its type (string, number, etc.), whether it's required, and any validation rules.

• Comprehensive Property Management: Provides endpoints for managing properties and their mappings between native systems and HubSpot, allowing for complex data synchronization.
• Data Consistency: Ensures data consistency across platforms by:
  • Maintaining property mappings in a local database
  • Caching HubSpot property definitions to reduce API calls
  • Validating property types and formats
  • Handling bidirectional updates between systems

1. Download and install PostgreSQL, make sure it's running, and create an empty database. You need the username and password (defaults username is postgres and no password)
2. Clone the repo
3. In your HubSpot public app, add localhost:3001/oauth-callback as a redirect URL, set the required scopes to be those in the Scopes section down below
4. Create the .env file with these entries (see examples in the .env.example file):
   • DATABASE_URL the (local) url to the postgres database (e.g. postgresql://{username}:{password}@localhost:5432/{database name})
   • CLIENT_ID from Hubspot public app
   • CLIENT_SECRET from Hubspot public app
5. Run npm install to install the required Node packages.
6. Run npm run db-init to create the necessary tables in PostgreSQL
7. Optional: Run npm run seed to seed the database with test data
8. Run npm run dev to start the server
9. Visit http://localhost:3001/api/install in a browser to get the OAuth install link, note, this is normally handled by the React frontend repository so you will be redirected to non-existant location if that's not running.

• crm.schemas.companies.write - Create, delete, or make changes to property settings for companies
• crm.schemas.contacts.write - Create, delete, or make changes to property settings for contacts
• crm.schemas.companies.read - View details about property settings for companies
• crm.schemas.contacts.read - View details about property settings for contacts

• GET /api/install: Initiates the OAuth installation process and returns the authorization URL for HubSpot.

• GET /oauth-callback: Endpoint for handling HubSpot OAuth callback, processing the provided code to obtain an access token.

• GET /api/hubspot-properties: Retrieves all HubSpot properties, leveraging cache to improve performance.

• GET /api/hubspot-properties-skip-cache: Retrieves all HubSpot properties bypassing cache to ensure up-to-date data.

• POST /api/native-properties: Creates new native properties in the system based on data sent in the request body.

• GET /api/native-properties-with-mappings: Retrieves native properties along with their HubSpot mappings for the authenticated customer.

• POST /api/mappings: Saves a new mapping between native properties and HubSpot properties.

• DELETE /api/mappings/{mappingID} Deletes a specified mapping by its ID.

• npm run dev - Start development server with hot reload
• npm run prod - Run production server
• npm run build - Build TypeScript files
• npm run seed - Seed the database with initial data
• npm run db-init - Initialize database schema
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm test - Run tests
• npm run test:watch - Run tests in watch mode

• @prisma/client - Database ORM
• express - Web framework
• @hubspot/api-client - HubSpot API client
• dotenv - Environment configuration
• swagger-jsdoc/swagger-ui-express - API documentation

• typescript - TypeScript compiler
• prisma - Database toolkit
• jest - Testing framework
• nodemon - Development server
• eslint/prettier - Code formatting and linting
• ts-node - TypeScript execution
• supertest - HTTP testing

If you encounter any bugs or issues, please report them by opening a GitHub issue. For feedback or suggestions for new code examples, we encourage you to use this form.

Various teams at HubSpot that focus on developer experience and app marketplace quality maintain and contribute to this project. In particular, this project was made possible by @therealdadams, @rahmona-henry, @zman81988, @natalijabujevic0708, and @zradford

MIT