@woodsportal/hubspot-kit 1.0.2

package/scripts/generate-module-config-example.mjs

@@ -0,0 +1,57 @@
+/**
+ * Generates {dev.moduleConfigDir}/module-config.example.json from public/fields.json defaults.
+ * Run: node scripts/generate-module-config-example.mjs
+ */
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { findProjectRoot } from './project-root.mjs'
+import { moduleConfigPaths } from './module-config-dir.mjs'
+
+const root = findProjectRoot()
+
+function isFieldGroup(field) {
+  return field.type === 'group' && Array.isArray(field.children)
+}
+
+function defaultForField(field) {
+  if (field.default !== undefined) return structuredClone(field.default)
+  if (isFieldGroup(field)) return buildDefaultsFromFields(field.children ?? [])
+  if (field.type === 'boolean') return false
+  if (field.type === 'number') return 0
+  if (field.type === 'color') return { color: '', opacity: 100 }
+  if (field.type === 'image') return { src: '', alt: '' }
+  if (field.type === 'url' || field.type === 'link') {
+    return {
+      url: { href: '', type: 'EXTERNAL' },
+      open_in_new_tab: false,
+      no_follow: false,
+    }
+  }
+  return ''
+}
+
+function buildDefaultsFromFields(fields) {
+  const result = {}
+  for (const field of fields) {
+    result[field.name] = defaultForField(field)
+  }
+  return result
+}
+
+const fieldsPath = path.join(root, 'public/fields.json')
+const { exampleConfigPath: outPath } = moduleConfigPaths(root)
+
+const fields = JSON.parse(await fs.readFile(fieldsPath, 'utf8'))
+const moduleValues = buildDefaultsFromFields(fields)
+
+const record = {
+  version: 1,
+  module: moduleValues,
+  updatedAt: new Date().toISOString(),
+  source: 'example',
+}
+
+await fs.mkdir(path.dirname(outPath), { recursive: true })
+await fs.writeFile(outPath, JSON.stringify(record, null, 2), 'utf8')
+console.log(`Wrote ${outPath}`)

package/scripts/hubspot-module-postbuild.mjs

@@ -0,0 +1,151 @@
+/**
+ * HubSpot custom module post-build: escape HubL tokens in module.js, validate, sync public assets.
+ * Invoked after `vite build` via scripts/run-hubspot-module-postbuild.mjs (build:dev / build:prod).
+ */
+import { execSync } from 'node:child_process'
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { resolve } from 'node:path'
+
+/** Substrings that break when HubSpot tokenizes module.js (Jinja/HubL). */
+export const FORBIDDEN_HUBL_IN_MODULE_JS = ['{{', '{%', '<%', '%>']
+
+const ALLOWED_DIST_FILES = new Set([
+  'module.html',
+  'module.js',
+  'module.css',
+  'fields.json',
+])
+
+/**
+ * react-html-parser ships mustache/erb detector regexes; escape so HubSpot does not parse them as HubL.
+ */
+export function escapeHubSpotModuleJs(js) {
+  let out = js
+  if (out.includes('{{')) out = out.replaceAll('{{', '\\u007b\\u007b')
+  if (out.includes('{%')) out = out.replaceAll('{%', '\\u007b%')
+  if (out.includes('<%')) out = out.replaceAll('<%', '\\u003c%')
+  if (out.includes('%>')) out = out.replaceAll('%>', '%\\u003e')
+  if (out.includes('|^[\\w\\W]*}}')) {
+    out = out.replaceAll('|^[\\w\\W]*}}', '|^[\\w\\W]*\\u007d\\u007d')
+  }
+  return out
+}
+
+export function assertNoForbiddenHubLTokens(js, label = 'module.js') {
+  for (const token of FORBIDDEN_HUBL_IN_MODULE_JS) {
+    if (js.includes(token)) {
+      throw new Error(
+        `${label}: HubL-sensitive token ${JSON.stringify(token)} remains after escape pass`,
+      )
+    }
+  }
+}
+
+export function assertValidJavaScriptSyntax(jsPath) {
+  execSync(`node --check ${JSON.stringify(jsPath)}`, { stdio: 'pipe' })
+}
+
+/**
+ * Replace CDN placeholders in module.html from dist/cdn/manifest.json.
+ * @param {string} html
+ * @param {string} manifestPath
+ */
+export function injectCdnManifestIntoModuleHtml(html, manifestPath) {
+  if (!existsSync(manifestPath)) {
+    if (html.includes('__PORTAL_CDN_BASE__')) {
+      throw new Error(
+        `Missing ${manifestPath} — run yarn build:cdn:dev or yarn build:cdn:prod before hubspot post-build`,
+      )
+    }
+    return html
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  const vendor = manifest.scripts?.find((s) => s.name === 'vendor')
+  const app = manifest.scripts?.find((s) => s.name === 'app')
+  const appCss = manifest.styles?.find((s) => s.name === 'app') ?? manifest.styles?.[0]
+
+  if (!vendor?.file || !app?.file) {
+    throw new Error('manifest.json must include vendor and app scripts')
+  }
+
+  if (!appCss?.file) {
+    throw new Error('manifest.json must include app styles (app.*.css from yarn build:cdn:dev or build:cdn:prod)')
+  }
+
+  return html
+    .replaceAll('__PORTAL_CDN_BASE__', manifest.baseUrl)
+    .replaceAll('__PORTAL_BUILD_ID__', manifest.buildId)
+    .replaceAll('__PORTAL_VENDOR_FILE__', vendor.file)
+    .replaceAll('__PORTAL_APP_FILE__', app.file)
+    .replaceAll('__PORTAL_APP_CSS_FILE__', appCss.file)
+}
+
+/**
+ * @param {string} moduleDir absolute path to dist/WoodsPortal.Module
+ * @param {string} publicDir absolute path to public/
+ * @param {{ manifestPath?: string, bootstrapRawLimit?: number }} [options]
+ */
+export function finalizeHubSpotModuleDist(moduleDir, publicDir, options = {}) {
+  const { bootstrapRawLimit = 200 * 1024 } = options
+  const manifestPath =
+    options.manifestPath ?? resolve(moduleDir, '../cdn/manifest.json')
+  mkdirSync(moduleDir, { recursive: true })
+
+  const jsPath = resolve(moduleDir, 'module.js')
+  if (!existsSync(jsPath)) {
+    const entries = existsSync(moduleDir) ? readdirSync(moduleDir) : []
+    throw new Error(
+      `Missing ${jsPath} — Vite lib build must emit module.js first. Found in ${moduleDir}: ${entries.join(', ') || '(empty)'}`,
+    )
+  }
+
+  const cssPath = resolve(moduleDir, 'module.css')
+  if (!existsSync(cssPath)) {
+    const entries = existsSync(moduleDir) ? readdirSync(moduleDir) : []
+    throw new Error(
+      `Missing ${cssPath} — Vite lib build must emit module.css first. Found in ${moduleDir}: ${entries.join(', ') || '(empty)'}`,
+    )
+  }
+
+  for (const file of ['module.html', 'fields.json']) {
+    const src = resolve(publicDir, file)
+    if (!existsSync(src)) {
+      throw new Error(`Missing public/${file} (required for HubSpot module upload)`)
+    }
+    if (file === 'module.html') {
+      let html = readFileSync(src, 'utf8')
+      html = injectCdnManifestIntoModuleHtml(html, manifestPath)
+      writeFileSync(resolve(moduleDir, file), html, 'utf8')
+    } else {
+      cpSync(src, resolve(moduleDir, file), { force: true })
+    }
+  }
+
+  const escaped = escapeHubSpotModuleJs(readFileSync(jsPath, 'utf8'))
+  assertNoForbiddenHubLTokens(escaped, jsPath)
+  writeFileSync(jsPath, escaped, 'utf8')
+  assertValidJavaScriptSyntax(jsPath)
+
+  if (escaped.length > bootstrapRawLimit) {
+    throw new Error(
+      `module.js bootstrap ${escaped.length} bytes exceeds ${bootstrapRawLimit} byte limit`,
+    )
+  }
+
+  for (const entry of readdirSync(moduleDir)) {
+    if (!ALLOWED_DIST_FILES.has(entry)) {
+      rmSync(resolve(moduleDir, entry), { recursive: true, force: true })
+    }
+  }
+
+  return { jsBytes: escaped.length, cssBytes: readFileSync(cssPath).length }
+}

package/scripts/load-portal-cdn-config.mjs

@@ -0,0 +1,91 @@
+/**
+ * Load CDN publish settings from woodscli.json (cdn.mode, cdn.mirror) with portal.cdn.json fallback.
+ * Env overrides: VITE_PORTAL_CDN_PUBLISH_MODE, VITE_PORTAL_CDN_GITHUB, PORTAL_CDN_GIT_REMOTE, VITE_PORTAL_CDN_BASE_URL
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { findProjectRoot } from './project-root.mjs'
+import { resolveProjectConfigPath } from './config-files.mjs'
+
+const DEFAULTS = {
+  publishMode: 'jsdelivr',
+  github: 'Digital-Woods/woodsportal-client-frontend-cdn',
+  gitRemote: 'https://github.com/Digital-Woods/woodsportal-client-frontend-cdn.git',
+  cdnPathInRepo: 'dist/cdn',
+  defaultBranch: 'main',
+}
+
+function readWoodscliConfig(projectRoot) {
+  const configPath = resolveProjectConfigPath(projectRoot)
+  if (!configPath) {
+    return null
+  }
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function resolveMirrorPath(projectRoot, hsConfig) {
+  const mirror = hsConfig?.cdn?.mirror?.trim() || 'portal.cdn.json'
+  return resolve(projectRoot, mirror)
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [projectRoot]
+ */
+export function loadPortalCdnConfig(env = process.env, projectRoot) {
+  const root = projectRoot ?? findProjectRoot()
+  const hsConfig = readWoodscliConfig(root)
+  const cdnMode = hsConfig?.cdn?.mode ?? DEFAULTS.publishMode
+  const mirrorPath = resolveMirrorPath(root, hsConfig)
+  const examplePath = resolve(root, 'portal.cdn.example.json')
+
+  let fileConfig = {}
+  let loadedFrom = null
+
+  if (existsSync(mirrorPath)) {
+    fileConfig = JSON.parse(readFileSync(mirrorPath, 'utf8'))
+    loadedFrom = mirrorPath
+  } else if (existsSync(examplePath)) {
+    fileConfig = JSON.parse(readFileSync(examplePath, 'utf8'))
+    loadedFrom = examplePath
+  }
+
+  const publishMode =
+    env.VITE_PORTAL_CDN_PUBLISH_MODE?.trim() ||
+    cdnMode ||
+    fileConfig.publishMode ||
+    DEFAULTS.publishMode
+
+  return {
+    publishMode,
+    cdnMode,
+    github: env.VITE_PORTAL_CDN_GITHUB?.trim() || fileConfig.github || DEFAULTS.github,
+    gitRemote: env.PORTAL_CDN_GIT_REMOTE?.trim() || fileConfig.gitRemote || DEFAULTS.gitRemote,
+    cdnPathInRepo: fileConfig.cdnPathInRepo || DEFAULTS.cdnPathInRepo,
+    defaultBranch: fileConfig.defaultBranch || DEFAULTS.defaultBranch,
+    configPath: loadedFrom,
+  }
+}
+
+/** Merge CDN config into env for Vite / child processes. */
+export function envWithPortalCdnConfig(baseEnv = process.env, projectRoot) {
+  const config = loadPortalCdnConfig(baseEnv, projectRoot)
+  return {
+    ...baseEnv,
+    VITE_PORTAL_CDN_PUBLISH_MODE: config.publishMode,
+    VITE_PORTAL_CDN_GITHUB: config.github,
+  }
+}
+
+/** jsDelivr base URL for a tagged release. */
+export function jsDelivrBaseUrl(github, buildId, cdnPathInRepo = DEFAULTS.cdnPathInRepo) {
+  const path = cdnPathInRepo.replace(/^\//, '').replace(/\/$/, '')
+  return `https://cdn.jsdelivr.net/gh/${github}@${buildId}/${path}`
+}
+
+export { DEFAULTS }

package/scripts/migrate-sdk-3-api.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * One-time codemod: woodsportal-client-sdk 2.x flat api → 3.0 nested api.
+ */
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
+import { join, extname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(fileURLToPath(new URL('..', import.meta.url)), 'src')
+
+function walk(dir) {
+    const out = []
+    for (const name of readdirSync(dir)) {
+        const p = join(dir, name)
+        if (statSync(p).isDirectory()) out.push(...walk(p))
+        else if (['.ts', '.tsx'].includes(extname(name))) out.push(p)
+    }
+    return out
+}
+
+const factoryReplacements = [
+    ['api.sideBarObjects', 'api.crm.objects.listSidebar'],
+    ['api.objectFormOptions', 'api.crm.objects.getFormOptions'],
+    ['api.updateObjectsDetails', 'api.crm.objects.updateDetails'],
+    ['api.createExistingObject', 'api.crm.objects.createExisting'],
+    ['api.removeExistingObject', 'api.crm.objects.removeExisting'],
+    ['api.objectsDetails', 'api.crm.objects.getDetails'],
+    ['api.objectsForm', 'api.crm.objects.getForm'],
+    ['api.createObject', 'api.crm.objects.create'],
+    ['api.fileDownload', 'api.crm.files.download'],
+    ['api.attachmentUpload', 'api.crm.uploads.uploadAttachment'],
+    ['api.imageUpload', 'api.crm.uploads.uploadImage'],
+    ['api.cachePurgeStatus', 'api.crm.cache.getPurgeStatus'],
+    ['api.purgeCache', 'api.crm.cache.purge'],
+    ['api.createEmail', 'api.crm.emails.create'],
+    ['api.updateEmail', 'api.crm.emails.update'],
+    ['api.createNote', 'api.crm.notes.create'],
+    ['api.updateNote', 'api.crm.notes.update'],
+    ['api.resetPasswordVerifyToken', 'api.auth.resetPasswordVerifyToken'],
+    ['api.registerExistingUser', 'api.auth.registerExistingUser'],
+    ['api.verifyEmailResend', 'api.auth.verifyEmailResend'],
+    ['api.forgetPassword', 'api.auth.forgetPassword'],
+    ['api.changePassword', 'api.auth.changePassword'],
+    ['api.getSsoDetails', 'api.auth.sso.getDetails'],
+    ['api.generateSsoUrl', 'api.auth.sso.generateUrl'],
+    ['api.ssoCallback', 'api.auth.sso.callback'],
+    ['api.profileUpdate', 'api.auth.updateProfile'],
+    ['api.preLogin', 'api.auth.preLogin'],
+    ['api.verifyEmail', 'api.auth.verifyEmail'],
+    ['api.resetPassword', 'api.auth.resetPassword'],
+    ['api.resendEmail', 'api.auth.resendEmail'],
+    ['api.pipelines', 'api.crm.pipelines.list'],
+    ['api.addFolder', 'api.crm.files.addFolder'],
+    ['api.addFile', 'api.crm.files.addFile'],
+    ['api.stages', 'api.crm.stages.list'],
+    ['api.objects', 'api.crm.objects.list'],
+    ['api.notes', 'api.crm.notes.list'],
+    ['api.emails', 'api.crm.emails.list'],
+    ['api.files', 'api.crm.files.list'],
+    ['api.file', 'api.crm.files.getDetails'],
+    ['api.login', 'api.auth.login'],
+    ['api.logout', 'api.auth.logout'],
+    ['api.profile', 'api.auth.profile'],
+    ['api.me', 'api.auth.me']
+]
+
+const sessionReplacements = [
+    ['api.getRefreshToken', 'api.auth.session.getRefreshToken'],
+    ['api.getAuthRefreshToken', 'api.auth.session.refreshAccessToken'],
+    ['api.getAccessToken', 'api.auth.session.getAccessToken'],
+    ['api.isAuthenticateApp', 'api.auth.session.isAuthenticated'],
+    ['api.isExpiresAccessToken', 'api.auth.session.isAccessTokenExpired'],
+    ['api.isCookieExpired', 'api.auth.session.isCookieExpired']
+]
+
+const destructureReplacements = [
+    ['getSideBarObjects', 'listSidebar'],
+    ['getObjectsDetails', 'getDetails'],
+    ['getObjectsForm', 'getForm'],
+    ['updateObjectsDetails', 'updateDetails'],
+    ['createExistingObject', 'createExisting'],
+    ['removeExistingObject', 'removeExisting'],
+    ['createObject', 'create'],
+    ['createNote', 'create'],
+    ['updateNote', 'update'],
+    ['createEmail', 'create'],
+    ['updateEmail', 'update'],
+    ['downloadFile', 'download'],
+    ['getObjects', 'list'],
+    ['getPipelines', 'list'],
+    ['getStages', 'list'],
+    ['getNotes', 'list'],
+    ['getEmails', 'list'],
+    ['getFiles', 'list'],
+    ['getFile', 'getDetails'],
+    ['objectFormOptions', 'getFormOptions'],
+    ['imageUpload', 'uploadImage'],
+    ['attachmentUpload', 'uploadAttachment']
+]
+
+let changed = 0
+for (const file of walk(root)) {
+    let content = readFileSync(file, 'utf8')
+    const original = content
+
+    for (const [from, to] of factoryReplacements) content = content.split(from).join(to)
+    for (const [from, to] of sessionReplacements) content = content.split(from).join(to)
+    for (const [from, to] of destructureReplacements) {
+        content = content.replace(new RegExp(`\\b${from}\\b`, 'g'), to)
+    }
+
+    if (content.includes('woodsportal-client-sdk')) {
+        content = content.replace(
+            /import \{([^}]*)\burl\b([^}]*)\} from ['"]woodsportal-client-sdk['"]/g,
+            (_match, before, after) => {
+                const parts = `${before}${after}`.split(',').map((s) => s.trim()).filter(Boolean)
+                const withoutUrl = parts.filter((p) => p !== 'url' && !p.startsWith('url '))
+                if (withoutUrl.length === 0) return "import { api } from 'woodsportal-client-sdk'"
+                const hasApi = withoutUrl.some((p) => p === 'api' || p.startsWith('api '))
+                return hasApi
+                    ? `import { ${withoutUrl.join(', ')} } from 'woodsportal-client-sdk'`
+                    : `import { ${withoutUrl.join(', ')}, api } from 'woodsportal-client-sdk'`
+            }
+        )
+        content = content.replace(/\burl\.makeLink\b/g, 'api.navigation.url.makeLink')
+        content = content.replace(/\burl\.updateLink\b/g, 'api.navigation.url.updateLink')
+        content = content.replace(
+            /const \{ makeLink: createMakeLink \} = url/g,
+            'const { makeLink: createMakeLink } = api.navigation.url'
+        )
+        content = content.replace(
+            /const \{ updateLink: createUpdateLink \} = url/g,
+            'const { updateLink: createUpdateLink } = api.navigation.url'
+        )
+    }
+
+    if (content !== original) {
+        writeFileSync(file, content)
+        changed++
+        console.log('updated', file.replace(root, 'src'))
+    }
+}
+
+console.log(`Done. ${changed} files updated.`)

package/scripts/module-config-dir.mjs

@@ -0,0 +1,12 @@
+/**
+ * @deprecated Import from ./wphs-paths.mjs
+ */
+export {
+  DEFAULT_MODULE_CONFIG_DIR,
+  WPHS_WORKSPACE_DIR,
+  moduleConfigPaths,
+  readModuleConfigDir,
+  readWphsWorkspaceDir,
+  wphsPaths,
+  wphsWorkspaceSubdirs,
+} from './wphs-paths.mjs'

package/scripts/portal-env-mode.mjs

@@ -0,0 +1,24 @@
+/**
+ * Portal Vite modes — align with `.env.dev` | `.env.stg` | `.env.prod`.
+ */
+
+/** @typedef {'dev' | 'stg' | 'prod'} PortalViteMode */
+
+/** @param {string[]} [argv] */
+export function resolvePortalViteMode(argv = process.argv) {
+  if (argv.includes('--stg') || argv.includes('--staging')) return /** @type {PortalViteMode} */ ('stg')
+  if (argv.includes('--dev') || argv.includes('--development')) return /** @type {PortalViteMode} */ ('dev')
+  return /** @type {PortalViteMode} */ ('prod')
+}
+
+/** React / bundler NODE_ENV (not the same as portal tier). */
+/** @param {PortalViteMode | string} mode */
+export function nodeEnvForPortalMode(mode) {
+  return mode === 'dev' ? 'development' : 'production'
+}
+
+/** Tailwind class prefix applies on CDN / HubSpot builds, not local dev. */
+/** @param {PortalViteMode | string} mode */
+export function isPrefixBuildMode(mode) {
+  return mode === 'stg' || mode === 'prod' || mode === 'staging' || mode === 'production'
+}

package/scripts/portal-vite-env.mjs

@@ -0,0 +1,39 @@
+/**
+ * Vite env for HubSpot/CDN builds — .env.[mode] wins over stale shell VITE_* vars.
+ */
+import { loadEnv } from 'vite'
+import { envWithPortalBuildId } from './resolve-portal-build-id.mjs'
+import { envWithPortalCdnConfig } from './load-portal-cdn-config.mjs'
+
+/**
+ * @param {'stg' | 'prod' | 'dev'} mode
+ * @param {string} root
+ * @param {NodeJS.ProcessEnv} [extra]
+ */
+export function envForPortalBuild(mode, root, extra = {}) {
+  const fileEnv = loadEnv(mode, root, '')
+  const base = { ...process.env }
+
+  for (const key of Object.keys(base)) {
+    if (key.startsWith('VITE_')) {
+      delete base[key]
+    }
+  }
+
+  return {
+    ...base,
+    ...fileEnv,
+    ...envWithPortalCdnConfig(envWithPortalBuildId({ ...process.env, ...fileEnv, ...extra })),
+    ...extra,
+  }
+}
+
+/**
+ * @param {'stg' | 'prod' | 'dev'} mode
+ */
+export function defaultDatadogFlag(mode) {
+  if (process.env.VITE_DATADOG_RUM_ENABLED != null) {
+    return process.env.VITE_DATADOG_RUM_ENABLED
+  }
+  return mode === 'prod' ? 'false' : 'false'
+}

package/scripts/project-root.mjs

@@ -0,0 +1,30 @@
+/**
+ * Resolve consumer project root (woodscli.json) vs kit package root.
+ */
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { findProjectRootWithConfig } from './config-files.mjs'
+
+const kitRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/**
+ * @param {string} [from]
+ */
+export function findProjectRoot(from = process.cwd()) {
+  return findProjectRootWithConfig(from)
+}
+
+export function getKitRoot() {
+  return kitRoot
+}
+
+/**
+ * @param {...string} segments
+ */
+export function kitPath(...segments) {
+  return resolve(kitRoot, ...segments)
+}
+
+export { resolveProjectConfigPath, WOODSCLI_CONFIG_FILE, LEGACY_WOODSPORTAL_HS_FILE } from './config-files.mjs'