@hubspot/local-dev-lib 0.0.1-experimental.0

package/models/HubSpotHttpError.d.ts

@@ -0,0 +1,24 @@
+import { HubSpotHttpErrorContext } from '../types/Error';
+export declare class HubSpotHttpError<T = any> extends Error {
+    status?: number;
+    code?: string;
+    statusText?: string;
+    data?: T;
+    headers?: {
+        [key: string]: unknown;
+    };
+    method: string | undefined;
+    context: HubSpotHttpErrorContext | undefined;
+    derivedContext: HubSpotHttpErrorContext | undefined;
+    validationErrors: string[] | undefined;
+    detailedMessage?: string;
+    private divider;
+    cause: ErrorOptions['cause'];
+    constructor(message?: string, options?: ErrorOptions, context?: HubSpotHttpErrorContext);
+    updateContext(context: Partial<HubSpotHttpErrorContext>): void;
+    toString(): string;
+    formattedValidationErrors(): string;
+    private extractDerivedContext;
+    private parseValidationErrors;
+    private joinErrorMessages;
+}

package/models/HubSpotHttpError.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubSpotHttpError = void 0;
+const axios_1 = require("axios");
+const api_1 = require("../constants/api");
+const lang_1 = require("../utils/lang");
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+class HubSpotHttpError extends Error {
+    status;
+    code;
+    statusText;
+    data;
+    headers;
+    method;
+    context;
+    derivedContext;
+    validationErrors;
+    detailedMessage;
+    divider = `\n- `;
+    cause;
+    constructor(message, options, context) {
+        super(message, options);
+        this.name = 'HubSpotHttpError';
+        this.context = context;
+        this.cause = options?.cause;
+        if (options && (0, axios_1.isAxiosError)(options.cause)) {
+            this.extractDerivedContext(options.cause);
+            const { response, config, code } = options.cause;
+            this.message = this.joinErrorMessages(options.cause, {
+                accountId: this.context?.accountId || this.derivedContext?.accountId,
+            });
+            this.detailedMessage = this.joinErrorMessages(options.cause, this.context);
+            this.code = code;
+            this.method = config?.method;
+            // Pull the request fields to the top level
+            if (response) {
+                this.status = response.status;
+                this.statusText = response.statusText;
+                this.data = response.data;
+                this.headers = response.headers;
+                this.parseValidationErrors(response.data);
+            }
+        }
+        else if (options && options.cause instanceof Error) {
+            const messages = options.cause.name !== 'Error' ? [`${options.cause.name}:`] : [];
+            if (options.cause.message) {
+                messages.push(options.cause.message);
+            }
+            if ('reason' in options.cause && options.cause.reason) {
+                messages.push(`${options.cause.reason}`);
+            }
+            this.message = messages.join(' ');
+        }
+    }
+    updateContext(context) {
+        this.context = { ...this.context, ...context };
+        // Update the error messages when the context is updated
+        if ((0, axios_1.isAxiosError)(this.cause)) {
+            this.message = this.joinErrorMessages(this.cause, this.context);
+        }
+    }
+    toString() {
+        const messages = [
+            `${this.name}: ${this.divider}message: ${this.detailedMessage}`,
+        ];
+        ['status', 'statusText', 'method', 'code'].forEach(field => {
+            if (Object.hasOwn(this, field)) {
+                // @ts-expect-error this[field] exists, so we know it is a property of this
+                messages.push(`${field}: ${this[field]}`);
+            }
+        });
+        if (this.validationErrors && this.validationErrors.length > 0) {
+            messages.push(`errors: ${this.formattedValidationErrors()}`);
+        }
+        if (this.context) {
+            messages.push(`context: ${JSON.stringify(this.context, undefined, 2)}`);
+        }
+        if (this.derivedContext) {
+            messages.push(`derivedContext: ${JSON.stringify(this.derivedContext, undefined, 2)}`);
+        }
+        return messages.join(this.divider);
+    }
+    formattedValidationErrors() {
+        if (!this.validationErrors || this.validationErrors?.length === 0) {
+            return '';
+        }
+        return this.validationErrors?.join(this.divider);
+    }
+    extractDerivedContext(cause) {
+        const generatedContext = {};
+        if (!cause) {
+            return;
+        }
+        generatedContext.accountId = cause.config?.params?.portalId;
+        generatedContext.payload = JSON.stringify(cause.config?.data);
+        // This will just be the url path
+        generatedContext.request = cause.config?.url;
+        // Allow the provided context to override the generated context
+        this.derivedContext = { ...this.derivedContext, ...generatedContext };
+    }
+    parseValidationErrors(responseData = { errors: [], message: '' }) {
+        if (!responseData) {
+            return;
+        }
+        const errorMessages = [];
+        const { errors, message } = responseData;
+        if (message) {
+            errorMessages.push(message);
+        }
+        if (errors) {
+            const specificErrors = errors.map(error => {
+                let errorMessage = error.message;
+                if (error.context?.requiredScopes) {
+                    // Sometimes the scopes come back with duplicates
+                    const scopes = new Set(error.context.requiredScopes);
+                    scopes.forEach(item => {
+                        errorMessage = `${errorMessage}\n  - ${item}`;
+                    });
+                }
+                else if (error.errorTokens && error.errorTokens.line) {
+                    errorMessage = `line ${error.errorTokens.line}: ${errorMessage}`;
+                }
+                return errorMessage;
+            });
+            errorMessages.push(...specificErrors);
+        }
+        this.validationErrors = errorMessages;
+    }
+    joinErrorMessages(error, context = {}) {
+        const i18nKey = 'errors.apiErrors';
+        const status = error.response?.status;
+        const method = error.config?.method;
+        let messageDetail;
+        if (context.accountId) {
+            const action = (method && api_1.HTTP_METHOD_VERBS[method]) || api_1.HTTP_METHOD_VERBS.get;
+            const preposition = (method && api_1.HTTP_METHOD_PREPOSITIONS[method]) ||
+                api_1.HTTP_METHOD_PREPOSITIONS.get;
+            const requestName = context.request
+                ? `${action} ${preposition} '${context.request}'`
+                : action;
+            messageDetail = (0, lang_1.i18n)(`${i18nKey}.messageDetail`, {
+                accountId: context.accountId,
+                requestName,
+            });
+        }
+        else {
+            messageDetail = (0, lang_1.i18n)(`${i18nKey}.genericMessageDetail`);
+        }
+        const errorMessage = [];
+        if ((method === 'put' || method === 'post') && context.payload) {
+            errorMessage.push((0, lang_1.i18n)(`${i18nKey}.unableToUpload`, { payload: context.payload }));
+        }
+        switch (status) {
+            case 400:
+                errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.400`, { messageDetail }));
+                break;
+            case 401:
+                errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.401`, { messageDetail }));
+                break;
+            case 403:
+                break;
+            case 404:
+                errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.404`, { messageDetail }));
+                break;
+            case 429:
+                errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.429`, { messageDetail }));
+                break;
+            case 503:
+                errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.503`, { messageDetail }));
+                break;
+            default:
+                if (status && status >= 500 && status < 600) {
+                    errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.500Generic`, { messageDetail }));
+                }
+                else if (status && status >= 400 && status < 500) {
+                    errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.400Generic`, { messageDetail }));
+                }
+                else {
+                    errorMessage.push((0, lang_1.i18n)(`${i18nKey}.codes.generic`, { messageDetail }));
+                }
+                break;
+        }
+        if (error?.response?.data) {
+            const { message, errors } = error.response.data;
+            if (message) {
+                errorMessage.push(message);
+            }
+            (errors || []).forEach(err => {
+                if (err.message) {
+                    errorMessage.push(`${this.divider}${err.message}`);
+                }
+            });
+        }
+        return errorMessage.join(' ');
+    }
+}
+exports.HubSpotHttpError = HubSpotHttpError;

package/models/OAuth2Manager.d.ts

@@ -0,0 +1,12 @@
+import { FlatAccountFields, OAuth2ManagerAccountConfig, WriteTokenInfoFunction, RefreshTokenResponse, ExchangeProof } from '../types/Accounts';
+export declare class OAuth2Manager {
+    account: OAuth2ManagerAccountConfig;
+    writeTokenInfo?: WriteTokenInfoFunction;
+    refreshTokenRequest: Promise<RefreshTokenResponse> | null;
+    constructor(account: OAuth2ManagerAccountConfig, writeTokenInfo?: WriteTokenInfoFunction);
+    accessToken(): Promise<string | undefined>;
+    fetchAccessToken(exchangeProof: ExchangeProof): Promise<void>;
+    exchangeForTokens(exchangeProof: ExchangeProof): Promise<void>;
+    refreshAccessToken(): Promise<void>;
+    static fromConfig(accountConfig: FlatAccountFields, writeTokenInfo: WriteTokenInfoFunction): OAuth2Manager;
+}

package/models/OAuth2Manager.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuth2Manager = void 0;
+const axios_1 = __importDefault(require("axios"));
+const moment_1 = __importDefault(require("moment"));
+const urls_1 = require("../lib/urls");
+const environment_1 = require("../lib/environment");
+const logger_1 = require("../lib/logger");
+const getAccountIdentifier_1 = require("../config/getAccountIdentifier");
+const auth_1 = require("../constants/auth");
+const lang_1 = require("../utils/lang");
+const i18nKey = 'models.OAuth2Manager';
+class OAuth2Manager {
+    account;
+    writeTokenInfo;
+    refreshTokenRequest;
+    constructor(account, writeTokenInfo) {
+        this.writeTokenInfo = writeTokenInfo;
+        this.refreshTokenRequest = null;
+        this.account = account;
+        if (this.account.env) {
+            this.account.env = (0, environment_1.getValidEnv)(this.account.env, '');
+        }
+    }
+    async accessToken() {
+        if (!this.account.tokenInfo?.refreshToken) {
+            throw new Error((0, lang_1.i18n)(`${i18nKey}.errors.missingRefreshToken`, {
+                accountId: (0, getAccountIdentifier_1.getAccountIdentifier)(this.account),
+            }));
+        }
+        if (!this.account.tokenInfo?.accessToken ||
+            (0, moment_1.default)()
+                .add(5, 'minutes')
+                .isAfter((0, moment_1.default)(new Date(this.account.tokenInfo.expiresAt || '')))) {
+            await this.refreshAccessToken();
+        }
+        return this.account.tokenInfo.accessToken;
+    }
+    async fetchAccessToken(exchangeProof) {
+        logger_1.logger.debug((0, lang_1.i18n)(`${i18nKey}.fetchingAccessToken`, {
+            accountId: (0, getAccountIdentifier_1.getAccountIdentifier)(this.account),
+            clientId: this.account.clientId || '',
+        }));
+        try {
+            const { data } = await (0, axios_1.default)({
+                url: `${(0, urls_1.getHubSpotApiOrigin)((0, environment_1.getValidEnv)(this.account.env))}/oauth/v1/token`,
+                method: 'post',
+                data: exchangeProof,
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            });
+            this.refreshTokenRequest = data;
+            const { refresh_token: refreshToken, access_token: accessToken, expires_in: expiresIn, } = data;
+            if (!this.account.tokenInfo) {
+                this.account.tokenInfo = {};
+            }
+            this.account.tokenInfo.refreshToken = refreshToken;
+            this.account.tokenInfo.accessToken = accessToken;
+            this.account.tokenInfo.expiresAt = (0, moment_1.default)()
+                .add(Math.round(parseInt(expiresIn) * 0.75), 'seconds')
+                .toString();
+            if (this.writeTokenInfo) {
+                logger_1.logger.debug((0, lang_1.i18n)(`${i18nKey}.updatingTokenInfo`, {
+                    accountId: (0, getAccountIdentifier_1.getAccountIdentifier)(this.account),
+                    clientId: this.account.clientId || '',
+                }));
+                this.writeTokenInfo(this.account.tokenInfo);
+            }
+        }
+        finally {
+            this.refreshTokenRequest = null;
+        }
+    }
+    async exchangeForTokens(exchangeProof) {
+        if (this.refreshTokenRequest) {
+            logger_1.logger.debug((0, lang_1.i18n)(`${i18nKey}.refreshingAccessToken`, {
+                accountId: (0, getAccountIdentifier_1.getAccountIdentifier)(this.account),
+                clientId: this.account.clientId || '',
+            }));
+            await this.refreshTokenRequest;
+        }
+        else {
+            await this.fetchAccessToken(exchangeProof);
+        }
+    }
+    async refreshAccessToken() {
+        const refreshTokenProof = {
+            grant_type: 'refresh_token',
+            client_id: this.account.clientId,
+            client_secret: this.account.clientSecret,
+            refresh_token: this.account.tokenInfo?.refreshToken,
+        };
+        await this.exchangeForTokens(refreshTokenProof);
+    }
+    static fromConfig(accountConfig, writeTokenInfo) {
+        return new OAuth2Manager({
+            ...accountConfig,
+            authType: auth_1.AUTH_METHODS.oauth.value,
+            ...(accountConfig.auth || {}),
+        }, writeTokenInfo);
+    }
+}
+exports.OAuth2Manager = OAuth2Manager;

package/package.json

@@ -0,0 +1,81 @@
+{
+    "name": "@hubspot/local-dev-lib",
+    "version": "0.0.1-experimental.0",
+    "description": "Provides library functionality for HubSpot local development tooling, including the HubSpot CLI",
+    "main": "lib/index.js",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/HubSpot/hubspot-local-dev-lib"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/",
+        "access": "public"
+    },
+    "scripts": {
+        "build": "ts-node ./scripts/build.ts",
+        "lint": "eslint --max-warnings=0 . && prettier . --check",
+        "local-dev": "yarn build && cd dist && yarn link && cd .. && tsc --watch --rootDir . --outdir dist",
+        "prettier:write": "prettier . --write",
+        "release": "ts-node ./scripts/release.ts release",
+        "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ./node_modules/.bin/jest"
+    },
+    "license": "Apache-2.0",
+    "devDependencies": {
+        "@inquirer/prompts": "^7.0.1",
+        "@types/content-disposition": "^0.5.5",
+        "@types/cors": "^2.8.15",
+        "@types/debounce": "^1.2.1",
+        "@types/express": "^4.17.18",
+        "@types/findup-sync": "^4.0.2",
+        "@types/fs-extra": "^11.0.1",
+        "@types/jest": "^29.5.0",
+        "@types/js-yaml": "^4.0.5",
+        "@types/node": "^18.14.2",
+        "@types/unixify": "^1.0.0",
+        "@typescript-eslint/eslint-plugin": "^5.54.0",
+        "@typescript-eslint/parser": "^5.59.7",
+        "eslint": "^8.35.0",
+        "eslint-plugin-import": "^2.29.1",
+        "husky": "^8.0.0",
+        "jest": "^29.5.0",
+        "ts-jest": "^29.0.5",
+        "ts-node": "^10.9.2",
+        "typescript": "^4.9.5",
+        "yargs": "^17.7.2"
+    },
+    "exports": {
+        "./*": "./lib/*.js",
+        "./api/*": "./api/*.js",
+        "./errors/*": "./errors/*.js",
+        "./http": "./http/index.js",
+        "./http/*": "./http/*.js",
+        "./config/getAccountIdentifier": "./config/getAccountIdentifier.js",
+        "./config": "./config/index.js",
+        "./constants/*": "./constants/*.js",
+        "./models/*": "./models/*.js",
+        "./types/*": "./types/*.d.ts"
+    },
+    "dependencies": {
+        "address": "^2.0.1",
+        "axios": "^1.3.5",
+        "chalk": "^2.4.2",
+        "chokidar": "^3.5.3",
+        "content-disposition": "^0.5.4",
+        "cors": "^2.8.5",
+        "debounce": "^1.2.0",
+        "express": "^4.18.2",
+        "extract-zip": "^2.0.1",
+        "findup-sync": "^5.0.0",
+        "fs-extra": "^11.1.0",
+        "ignore": "^5.1.4",
+        "js-yaml": "^4.1.0",
+        "moment": "^2.29.4",
+        "p-queue": "^6.0.2",
+        "prettier": "^3.3.0",
+        "semver": "^6.3.0",
+        "unixify": "^1.0.0"
+    },
+    "engines": {
+        "node": ">=16.20.0"
+    }
+}

package/types/Accounts.d.ts

@@ -0,0 +1,178 @@
+import { HUBSPOT_ACCOUNT_TYPES } from '../constants/config';
+import { Mode } from './Files';
+import { Environment } from './Config';
+import { ValueOf } from './Utils';
+export type AuthType = 'personalaccesskey' | 'apikey' | 'oauth2';
+export interface CLIAccount_NEW {
+    name?: string;
+    accountId: number;
+    accountType?: AccountType;
+    defaultMode?: Mode;
+    env: Environment;
+    authType?: AuthType;
+    auth?: {
+        tokenInfo?: TokenInfo;
+    };
+    sandboxAccountType?: string | null;
+    parentAccountId?: number | null;
+    apiKey?: string;
+    personalAccessKey?: string;
+}
+export interface CLIAccount_DEPRECATED {
+    name?: string;
+    portalId?: number;
+    defaultMode?: Mode;
+    env: Environment;
+    accountType?: AccountType;
+    authType?: AuthType;
+    auth?: {
+        tokenInfo?: TokenInfo;
+    };
+    sandboxAccountType?: string | null;
+    parentAccountId?: number | null;
+    apiKey?: string;
+    personalAccessKey?: string;
+}
+export type CLIAccount = CLIAccount_NEW | CLIAccount_DEPRECATED;
+export type GenericAccount = {
+    portalId?: number;
+    accountId?: number;
+};
+export type AccountType = ValueOf<typeof HUBSPOT_ACCOUNT_TYPES>;
+export type TokenInfo = {
+    accessToken?: string;
+    expiresAt?: string;
+    refreshToken?: string;
+};
+export interface PersonalAccessKeyAccount_NEW extends CLIAccount_NEW {
+    authType: 'personalaccesskey';
+    personalAccessKey: string;
+}
+export interface PersonalAccessKeyAccount_DEPRECATED extends CLIAccount_DEPRECATED {
+    authType: 'personalaccesskey';
+    personalAccessKey: string;
+}
+export type PersonalAccessKeyAccount = PersonalAccessKeyAccount_NEW | PersonalAccessKeyAccount_DEPRECATED;
+export interface OAuthAccount_NEW extends CLIAccount_NEW {
+    authType: 'oauth2';
+    auth: {
+        clientId?: string;
+        clientSecret?: string;
+        scopes?: Array<string>;
+        tokenInfo?: TokenInfo;
+    };
+}
+export interface OAuthAccount_DEPRECATED extends CLIAccount_DEPRECATED {
+    authType: 'oauth2';
+    auth: {
+        clientId?: string;
+        clientSecret?: string;
+        scopes?: Array<string>;
+        tokenInfo?: TokenInfo;
+    };
+}
+export type OAuthAccount = OAuthAccount_NEW | OAuthAccount_DEPRECATED;
+export interface APIKeyAccount_NEW extends CLIAccount_NEW {
+    authType: 'apikey';
+    apiKey: string;
+}
+export interface APIKeyAccount_DEPRECATED extends CLIAccount_DEPRECATED {
+    authType: 'apikey';
+    apiKey: string;
+}
+export type APIKeyAccount = APIKeyAccount_NEW | APIKeyAccount_DEPRECATED;
+export interface FlatAccountFields_NEW extends CLIAccount_NEW {
+    tokenInfo?: TokenInfo;
+    clientId?: string;
+    clientSecret?: string;
+    scopes?: Array<string>;
+    apiKey?: string;
+    personalAccessKey?: string;
+}
+export interface FlatAccountFields_DEPRECATED extends CLIAccount_DEPRECATED {
+    tokenInfo?: TokenInfo;
+    clientId?: string;
+    clientSecret?: string;
+    scopes?: Array<string>;
+    apiKey?: string;
+    personalAccessKey?: string;
+}
+export type FlatAccountFields = FlatAccountFields_NEW | FlatAccountFields_DEPRECATED;
+export type ScopeData = {
+    portalScopesInGroup: Array<string>;
+    userScopesInGroup: Array<string>;
+};
+export type AccessTokenResponse = {
+    hubId: number;
+    userId: number;
+    oauthAccessToken: string;
+    expiresAtMillis: number;
+    enabledFeatures?: {
+        [key: string]: number;
+    };
+    scopeGroups: Array<string>;
+    encodedOAuthRefreshToken: string;
+    hubName: string;
+    accountType: ValueOf<typeof HUBSPOT_ACCOUNT_TYPES>;
+};
+export type EnabledFeaturesResponse = {
+    enabledFeatures: {
+        [key: string]: boolean;
+    };
+};
+export type UpdateAccountConfigOptions = Partial<FlatAccountFields_DEPRECATED> & {
+    environment?: Environment;
+};
+export type PersonalAccessKeyOptions = {
+    accountId: number;
+    personalAccessKey: string;
+    env: Environment;
+};
+export type OAuthOptions = {
+    accountId: number;
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    scopes: Array<string>;
+    env: Environment;
+};
+export type APIKeyOptions = {
+    accountId: number;
+    apiKey: string;
+    env: Environment;
+};
+export type AccessToken = {
+    portalId: number;
+    accessToken: string;
+    expiresAt: string;
+    scopeGroups: Array<string>;
+    enabledFeatures?: {
+        [key: string]: number;
+    };
+    encodedOAuthRefreshToken: string;
+    hubName: string;
+    accountType: ValueOf<typeof HUBSPOT_ACCOUNT_TYPES>;
+};
+export type OAuth2ManagerAccountConfig = {
+    name?: string;
+    accountId?: number;
+    clientId?: string;
+    clientSecret?: string;
+    scopes?: Array<string>;
+    env?: Environment;
+    environment?: Environment;
+    tokenInfo?: TokenInfo;
+    authType?: 'oauth2';
+};
+export type WriteTokenInfoFunction = (tokenInfo: TokenInfo) => void;
+export type RefreshTokenResponse = {
+    refresh_token: string;
+    access_token: string;
+    expires_in: string;
+};
+export type ExchangeProof = {
+    grant_type: string;
+    client_id?: string;
+    client_secret?: string;
+    refresh_token?: string;
+};

package/types/Accounts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/types/Activity.d.ts

@@ -0,0 +1,20 @@
+import { ACTIVITY_SOURCE } from '../enums/project';
+import { ValueOf } from './Utils';
+import { GithubSourceData } from './Github';
+export interface GithubActivitySource extends GithubSourceData {
+    authorEmail: string;
+    authorName: string;
+    branchName: string;
+    branch: string;
+    commitHash: string;
+    committersUsername: string;
+    ownerName: string;
+    owner: string;
+    repositoryName: string;
+    type: typeof ACTIVITY_SOURCE.GITHUB_USER;
+}
+export type HubspotActivitySource = {
+    userId?: number;
+    type: ValueOf<typeof ACTIVITY_SOURCE>;
+};
+export type ActivitySource = GithubActivitySource | HubspotActivitySource;

package/types/Activity.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/types/Api.d.ts

@@ -0,0 +1,2 @@
+import { HTTP_METHOD_VERBS } from '../constants/api';
+export type HttpMethod = keyof typeof HTTP_METHOD_VERBS;

package/types/Api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });