fg-devkit 1.17.3 → 1.19.2

package/scripts/piwik-common.mjs

@@ -0,0 +1,653 @@
+/**
+ * Piwik PRO management API client and consumer config discovery.
+ *
+ * Auth is OAuth2 client credentials against https://{account}.piwik.pro/auth/token.
+ * Client id and secret come from the environment or a local env file, never from
+ * piwik/.piwik.json.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { getFlagValue, parseFlags } from './poeditor-common.mjs'
+import {
+  PiwikDimensionError,
+  applyDesiredNames,
+  parseDimensionSource,
+} from './piwik-dimensions.mjs'
+
+export const JSON_API = 'application/vnd.api+json'
+
+export const DIMENSION_CANDIDATES = [
+  'src/analytics/dimensions.ts',
+  'src/util/piwikDimensions.ts',
+]
+
+const ENV_NAMES = ['production', 'preprod', 'development', 'localhost']
+
+/**
+ * @param {string} filePath
+ * @param {string} key
+ */
+function readEnvValueFromFile(filePath, key) {
+  if (!fs.existsSync(filePath)) return ''
+  const raw = fs.readFileSync(filePath, 'utf8')
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const noExport = trimmed.startsWith('export ') ? trimmed.slice(7).trim() : trimmed
+    const eqIdx = noExport.indexOf('=')
+    if (eqIdx <= 0) continue
+    if (noExport.slice(0, eqIdx).trim() !== key) continue
+    let value = noExport.slice(eqIdx + 1).trim()
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1)
+    } else {
+      const hashIdx = value.indexOf(' #')
+      if (hashIdx >= 0) value = value.slice(0, hashIdx).trim()
+    }
+    return value
+  }
+  return ''
+}
+
+/**
+ * @param {string} key
+ * @param {string} cwd
+ */
+function readSecret(key, cwd) {
+  if (process.env[key]) return process.env[key]
+  for (const file of ['env.local', '.env.local', '.env']) {
+    const value = readEnvValueFromFile(path.join(cwd, file), key)
+    if (value) return value
+  }
+  return ''
+}
+
+/**
+ * @param {string} url
+ */
+export function accountFromPiwikUrl(url) {
+  let hostname = ''
+  try {
+    hostname = new URL(url).hostname
+  } catch {
+    throw new PiwikDimensionError(`Invalid Piwik URL: ${url}`)
+  }
+  const account = hostname.split('.')[0]
+  if (!account || !hostname.endsWith('.piwik.pro')) {
+    throw new PiwikDimensionError(`Expected a https://{account}.piwik.pro URL, got ${url}`)
+  }
+  return account
+}
+
+/**
+ * @param {string} source
+ * @param {number} openIndex
+ */
+function readBrace(source, openIndex) {
+  let depth = 0
+  for (let i = openIndex; i < source.length; i += 1) {
+    if (source[i] === '{') depth += 1
+    else if (source[i] === '}') {
+      depth -= 1
+      if (depth === 0) return source.slice(openIndex + 1, i)
+    }
+  }
+  return ''
+}
+
+/**
+ * Find piwikUrl/piwikId (or piwikProBaseUrl/piwikProId) on each environment object.
+ * @param {string} source
+ */
+export function discoverPiwikSites(source) {
+  /** @type {{ environment: string, account: string, websiteId: string, url: string }[]} */
+  const sites = []
+  const re = /const\s+([A-Za-z0-9_]+)\s*(?::[^=]+)?=\s*\{/g
+  let match = re.exec(source)
+  while (match) {
+    const constName = match[1]
+    const braceAt = source.indexOf('{', match.index)
+    const body = readBrace(source, braceAt)
+    const environmentMatch = body.match(/environment:\s*['"]([A-Za-z0-9_:-]+)['"]/)
+    const environment = environmentMatch?.[1] ?? (ENV_NAMES.includes(constName) ? constName : '')
+    const url = body.match(/piwik(?:ProBase)?Url:\s*['"]([^'"]+)['"]/)?.[1] ?? ''
+    const websiteId = body.match(/piwik(?:Pro)?Id:\s*['"]([^'"]+)['"]/)?.[1] ?? ''
+    if (environment && url && websiteId) {
+      sites.push({
+        environment,
+        account: accountFromPiwikUrl(url),
+        websiteId,
+        url,
+      })
+    }
+    match = re.exec(source)
+  }
+  return sites
+}
+
+/** Prefer these names when several environments share one piwik id. */
+const ENV_LABEL_PREFERENCE = ['preprod', 'staging', 'production', 'demo', 'development', 'localhost', 'local']
+
+/**
+ * One entry per piwik id. localhost/development/preprod that share an id become a single "preprod" choice.
+ * @param {{ environment: string, account: string, websiteId: string, url?: string }[]} sites
+ */
+export function uniquePiwikEnvironments(sites) {
+  /** @type {Map<string, { environment: string, account: string, websiteId: string }[]>} */
+  const groups = new Map()
+  for (const site of sites) {
+    const group = groups.get(site.websiteId) ?? []
+    group.push(site)
+    groups.set(site.websiteId, group)
+  }
+
+  const unique = [...groups.values()].map((group) => {
+    const preferred =
+      ENV_LABEL_PREFERENCE.map((name) => group.find((site) => site.environment === name)).find(Boolean) ?? group[0]
+    return {
+      environment: preferred.environment,
+      account: preferred.account,
+      websiteId: preferred.websiteId,
+    }
+  })
+
+  const rank = (name) => {
+    const index = ENV_LABEL_PREFERENCE.indexOf(name)
+    return index === -1 ? ENV_LABEL_PREFERENCE.length : index
+  }
+  unique.sort((a, b) => rank(a.environment) - rank(b.environment))
+  return unique
+}
+
+/**
+ * Default site is the first non-production environment. Production is used only when it is the only site.
+ * @param {{ environment: string }[]} environments
+ */
+export function defaultPiwikEnvironment(environments) {
+  const preferred = environments.find((item) => item.environment !== 'production')
+  return preferred?.environment || environments[0]?.environment || ''
+}
+
+/**
+ * Compare and migrate from the first non-production site to production when that site exists.
+ * @param {{ environment: string }[]} environments
+ */
+export function defaultEnvironmentPair(environments) {
+  const from = defaultPiwikEnvironment(environments)
+  const to =
+    environments.find((item) => item.environment === 'production' && item.environment !== from)?.environment ||
+    environments.find((item) => item.environment !== from)?.environment ||
+    ''
+  return { from, to }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} fromName
+ * @param {string} toName
+ */
+export function resolveEnvironmentPair(cwd, fromName, toName) {
+  const environments = listPiwikEnvironments(cwd)
+  if (environments.length < 2) {
+    throw new PiwikDimensionError('Need two Piwik sites in src/config/env.ts to compare environments.')
+  }
+  const defaults = defaultEnvironmentPair(environments)
+  const from = environments.find((item) => item.environment === (fromName || defaults.from))
+  const to = environments.find((item) => item.environment === (toName || defaults.to))
+  const known = environments.map((item) => item.environment).join(', ')
+  if (!from) {
+    throw new PiwikDimensionError(`No Piwik site named "${fromName || defaults.from}". Found: ${known}.`)
+  }
+  if (!to) {
+    throw new PiwikDimensionError(`No Piwik site named "${toName || defaults.to}". Found: ${known}.`)
+  }
+  if (from.websiteId === to.websiteId) {
+    throw new PiwikDimensionError(`${from.environment} and ${to.environment} use the same Piwik site.`)
+  }
+  return { from, to }
+}
+
+/**
+ * @param {string} cwd
+ */
+export function listPiwikEnvironments(cwd) {
+  const envFile = path.join(cwd, 'src/config/env.ts')
+  if (!fs.existsSync(envFile)) return []
+  return uniquePiwikEnvironments(discoverPiwikSites(fs.readFileSync(envFile, 'utf8')))
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} [relativePath]
+ */
+function readJson(cwd, relativePath) {
+  const filePath = path.resolve(cwd, relativePath ?? 'piwik/.piwik.json')
+  if (!fs.existsSync(filePath)) return { filePath, json: null }
+  try {
+    return { filePath, json: JSON.parse(fs.readFileSync(filePath, 'utf8')) }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new PiwikDimensionError(`Could not parse ${filePath}: ${message}`)
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {string} [cwd]
+ */
+export function resolvePiwikConfig(argv, cwd = process.cwd()) {
+  const { positional, flags } = parseFlags(argv)
+  const command = positional[0] ?? ''
+  const configArg = getFlagValue(flags, 'config')
+  const { filePath: configPath, json } = readJson(cwd, typeof configArg === 'string' ? configArg : undefined)
+  const config = json && typeof json === 'object' ? json : {}
+
+  let envName = String(getFlagValue(flags, 'env', typeof config.environment === 'string' ? config.environment : ''))
+  const dimensionsFlag = getFlagValue(flags, 'dimensions')
+  const configuredFile = typeof config.dimensionsFile === 'string' ? config.dimensionsFile : ''
+  const dimensionFiles = resolveDimensionFiles(cwd, dimensionsFlag, configuredFile)
+
+  let account = String(getFlagValue(flags, 'account', config.account ?? process.env.PIWIK_ACCOUNT ?? ''))
+  let websiteId = String(getFlagValue(flags, 'website-id', config.websiteId ?? process.env.PIWIK_WEBSITE_ID ?? ''))
+  let siteSource = websiteId ? 'flag, config, or PIWIK_WEBSITE_ID' : ''
+
+  if (!websiteId || !account) {
+    const envFile = path.join(cwd, 'src/config/env.ts')
+    if (fs.existsSync(envFile)) {
+      const sites = discoverPiwikSites(fs.readFileSync(envFile, 'utf8'))
+      if (!envName) envName = defaultPiwikEnvironment(uniquePiwikEnvironments(sites))
+      const site = sites.find((item) => item.environment === envName)
+      if (!site && (!websiteId || !account)) {
+        const known = sites.map((item) => item.environment).join(', ') || 'none'
+        throw new PiwikDimensionError(
+          `No Piwik site for environment "${envName}" in src/config/env.ts. Found: ${known}. Pass --website-id and --account, or --env.`,
+        )
+      }
+      if (site) {
+        if (!account) account = site.account
+        if (!websiteId) {
+          websiteId = site.websiteId
+          siteSource = `src/config/env.ts (${site.environment})`
+        }
+      }
+    }
+  }
+
+  const clientId = String(getFlagValue(flags, 'client-id', readSecret('PIWIK_CLIENT_ID', cwd)))
+  const clientSecret = String(getFlagValue(flags, 'client-secret', readSecret('PIWIK_CLIENT_SECRET', cwd)))
+  const names = config.names && typeof config.names === 'object' ? config.names : undefined
+  const scope = String(getFlagValue(flags, 'scope', ''))
+  if (scope && scope !== 'event' && scope !== 'session' && scope !== 'product') {
+    throw new PiwikDimensionError(`Unknown --scope ${scope}. Use event, session, or product.`)
+  }
+
+  return {
+    command,
+    cwd,
+    configPath: json ? configPath : '',
+    envName,
+    account,
+    websiteId,
+    siteSource,
+    clientId,
+    clientSecret,
+    dimensionFiles,
+    names,
+    scope,
+    yes: getFlagValue(flags, 'yes') === 'true' || flags.has('yes'),
+    dryRun: getFlagValue(flags, 'dry-run') === 'true' || flags.has('dry-run'),
+    localOnly: getFlagValue(flags, 'local') === 'true' || flags.has('local'),
+    fromEnv: String(getFlagValue(flags, 'from', '')),
+    toEnv: String(getFlagValue(flags, 'to', '')),
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string | undefined} flag
+ * @param {string} configuredFile
+ */
+function resolveDimensionFiles(cwd, flag, configuredFile) {
+  if (typeof flag === 'string' && flag.trim() !== '') {
+    return [path.resolve(cwd, flag)]
+  }
+  if (configuredFile.trim() !== '') {
+    return [path.resolve(cwd, configuredFile)]
+  }
+  return DIMENSION_CANDIDATES.map((relative) => path.join(cwd, relative)).filter((file) => fs.existsSync(file))
+}
+
+/**
+ * @param {ReturnType<typeof resolvePiwikConfig>} config
+ */
+export function loadLocalDimensions(config) {
+  if (config.dimensionFiles.length === 0) {
+    throw new PiwikDimensionError(
+      'No local dimension file found. Expected src/analytics/dimensions.ts or src/util/piwikDimensions.ts, or pass --dimensions.',
+    )
+  }
+  const missing = config.dimensionFiles.filter((file) => !fs.existsSync(file))
+  if (missing.length > 0) {
+    throw new PiwikDimensionError(`Dimension file not found: ${missing.join(', ')}`)
+  }
+
+  const locals = config.dimensionFiles.flatMap((file) =>
+    parseDimensionSource(fs.readFileSync(file, 'utf8'), path.relative(config.cwd, file)),
+  )
+  const named = applyDesiredNames(locals, config.names)
+  const filtered = config.scope ? named.filter((item) => item.scope === config.scope) : named
+
+  const seen = new Set()
+  for (const item of filtered) {
+    const key = `${item.scope}:${item.slot}`
+    if (seen.has(key)) {
+      throw new PiwikDimensionError(`Duplicate ${item.scope} slot ${item.slot} across local dimension files.`)
+    }
+    seen.add(key)
+  }
+  return filtered
+}
+
+/**
+ * @param {number} status
+ * @param {unknown} body
+ */
+function formatApiError(status, body) {
+  if (body && typeof body === 'object' && Array.isArray(/** @type {{ errors?: unknown }} */ (body).errors)) {
+    const details = /** @type {{ errors: { detail?: string, title?: string }[] }} */ (body).errors
+      .map((error) => error.detail || error.title || '')
+      .filter(Boolean)
+    if (details.length > 0) return `Piwik API ${status}: ${details.join('; ')}`
+  }
+  const text = typeof body === 'string' ? body : JSON.stringify(body)
+  return `Piwik API ${status}: ${text}`
+}
+
+/**
+ * @param {{ account: string, clientId: string, clientSecret: string, fetchImpl?: typeof fetch }} options
+ */
+export function createPiwikClient(options) {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const base = `https://${options.account}.piwik.pro`
+  /** @type {{ token: string, expiresAt: number }} */
+  const cache = { token: '', expiresAt: 0 }
+
+  async function accessToken() {
+    if (cache.token && Date.now() < cache.expiresAt) return cache.token
+    const response = await fetchImpl(`${base}/auth/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({
+        grant_type: 'client_credentials',
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+      }),
+    })
+    const body = await response.json().catch(() => ({}))
+    if (!response.ok) {
+      throw new PiwikDimensionError(formatApiError(response.status, body))
+    }
+    const token = body?.access_token
+    if (typeof token !== 'string' || token === '') {
+      throw new PiwikDimensionError('Piwik token response did not include access_token.')
+    }
+    const expiresIn = Number(body.expires_in ?? 1800)
+    cache.token = token
+    cache.expiresAt = Date.now() + Math.max(30, expiresIn - 30) * 1000
+    return token
+  }
+
+  /**
+   * @param {string} method
+   * @param {string} pathname
+   * @param {{ query?: Record<string, string | number>, body?: unknown }} [extra]
+   */
+  async function request(method, pathname, extra = {}) {
+    const token = await accessToken()
+    const url = new URL(pathname, base)
+    for (const [key, value] of Object.entries(extra.query ?? {})) {
+      url.searchParams.set(key, String(value))
+    }
+    const response = await fetchImpl(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: JSON_API,
+        ...(extra.body ? { 'Content-Type': JSON_API } : {}),
+      },
+      body: extra.body ? JSON.stringify(extra.body) : undefined,
+    })
+    const text = await response.text()
+    /** @type {unknown} */
+    let body = {}
+    if (text) {
+      try {
+        body = JSON.parse(text)
+      } catch {
+        body = text
+      }
+    }
+    if (!response.ok) {
+      throw new PiwikDimensionError(formatApiError(response.status, body))
+    }
+    return body
+  }
+
+  /**
+   * @param {string} pathname
+   * @param {string} websiteId
+   */
+  async function listAll(pathname, websiteId) {
+    /** @type {unknown[]} */
+    const rows = []
+    let offset = 0
+    const limit = 1000
+    while (true) {
+      const page = await request('GET', pathname, { query: { website_id: websiteId, limit, offset } })
+      const data = Array.isArray(page?.data) ? page.data : []
+      rows.push(...data)
+      const total = Number(page?.meta?.total ?? rows.length)
+      offset += data.length
+      if (data.length === 0 || rows.length >= total) break
+    }
+    return rows
+  }
+
+  return {
+    /**
+     * @param {string} websiteId
+     */
+    async listDimensions(websiteId) {
+      const [custom, product, slots] = await Promise.all([
+        listAll('/api/analytics/v1/manage/custom-dimensions/', websiteId),
+        listAll('/api/analytics/v1/manage/product-custom-dimensions/', websiteId).catch((error) => {
+          const message = error instanceof Error ? error.message : String(error)
+          if (/Piwik API (400|403|404)/.test(message)) return []
+          throw error
+        }),
+        request('GET', '/api/analytics/v1/manage/custom-dimensions/slots/', { query: { website_id: websiteId } }),
+      ])
+      return {
+        dimensions: [
+          ...custom.map((row) => normalizeDimension(row, 'event')),
+          ...product.map((row) => normalizeDimension(row, 'product')),
+        ],
+        slots: slots?.data?.attributes ?? {},
+      }
+    },
+    /**
+     * @param {{ websiteId: string, name: string, scope: 'event' | 'session', description?: string, active?: boolean }} input
+     */
+    async createDimension(input) {
+      const body = await request('POST', '/api/analytics/v1/manage/custom-dimensions/', {
+        body: {
+          data: {
+            type: 'CustomDimension',
+            attributes: {
+              website_id: input.websiteId,
+              name: input.name,
+              active: input.active !== false,
+              case_sensitive: false,
+              scope: input.scope,
+              ...(input.description ? { description: input.description } : {}),
+            },
+          },
+        },
+      })
+      return normalizeDimension(body?.data, input.scope)
+    },
+    /**
+     * @param {import('./piwik-dimensions.mjs').RemoteDimension} remote
+     * @param {string} name
+     */
+    async updateDimension(remote, name) {
+      const body = await request('PUT', `/api/analytics/v1/manage/custom-dimensions/${remote.id}/`, {
+        body: {
+          data: {
+            type: 'CustomDimension',
+            id: remote.id,
+            attributes: {
+              website_id: remote.websiteId,
+              name,
+              active: remote.active,
+              case_sensitive: remote.caseSensitive,
+              scope: remote.scope,
+              ...(remote.description ? { description: remote.description } : {}),
+            },
+          },
+        },
+      })
+      return normalizeDimension(body?.data, remote.scope)
+    },
+    /**
+     * @param {import('./piwik-dimensions.mjs').RemoteDimension} remote
+     * @param {{ name: string, description: string, active: boolean }} desired
+     */
+    async updateDimensionState(remote, desired) {
+      const body = await request('PUT', `/api/analytics/v1/manage/custom-dimensions/${remote.id}/`, {
+        body: {
+          data: {
+            type: 'CustomDimension',
+            id: remote.id,
+            attributes: {
+              website_id: remote.websiteId,
+              name: desired.name,
+              active: desired.active,
+              case_sensitive: remote.caseSensitive,
+              scope: remote.scope,
+              description: desired.description,
+            },
+          },
+        },
+      })
+      return normalizeDimension(body?.data, remote.scope)
+    },
+    /**
+     * @param {{ websiteId: string, name: string, slot: number, description?: string }} input
+     */
+    async createProductDimension(input) {
+      const body = await request('POST', '/api/analytics/v1/manage/product-custom-dimensions/', {
+        body: {
+          data: {
+            type: 'ProductCustomDimension',
+            attributes: {
+              website_id: input.websiteId,
+              name: input.name,
+              slot: input.slot,
+              ...(input.description ? { description: input.description } : {}),
+            },
+          },
+        },
+      })
+      return normalizeDimension(body?.data, 'product')
+    },
+    /**
+     * @param {import('./piwik-dimensions.mjs').RemoteDimension} remote
+     * @param {string} name
+     */
+    async updateProductDimension(remote, name) {
+      const body = await request('PUT', `/api/analytics/v1/manage/product-custom-dimensions/${remote.id}/`, {
+        body: {
+          data: {
+            type: 'ProductCustomDimension',
+            id: remote.id,
+            attributes: {
+              website_id: remote.websiteId,
+              name,
+              ...(remote.description ? { description: remote.description } : {}),
+            },
+          },
+        },
+      })
+      return normalizeDimension(body?.data, 'product')
+    },
+    /**
+     * @param {import('./piwik-dimensions.mjs').RemoteDimension} remote
+     * @param {{ name: string, description: string }} desired
+     */
+    async updateProductDimensionState(remote, desired) {
+      const body = await request('PUT', `/api/analytics/v1/manage/product-custom-dimensions/${remote.id}/`, {
+        body: {
+          data: {
+            type: 'ProductCustomDimension',
+            id: remote.id,
+            attributes: {
+              website_id: remote.websiteId,
+              name: desired.name,
+              description: desired.description,
+            },
+          },
+        },
+      })
+      return normalizeDimension(body?.data, 'product')
+    },
+  }
+}
+
+/**
+ * @param {unknown} row
+ * @param {'event' | 'session' | 'product'} scopeFallback
+ * @returns {import('./piwik-dimensions.mjs').RemoteDimension & { websiteId: string }}
+ */
+export function normalizeDimension(row, scopeFallback) {
+  const record = row && typeof row === 'object' ? /** @type {Record<string, unknown>} */ (row) : {}
+  const attributes =
+    record.attributes && typeof record.attributes === 'object'
+      ? /** @type {Record<string, unknown>} */ (record.attributes)
+      : {}
+  const scope = attributes.scope === 'session' || attributes.scope === 'event' || attributes.scope === 'product'
+    ? attributes.scope
+    : scopeFallback
+  const slot = Number(attributes.slot)
+  const trackingId = Number(attributes.tracking_id ?? attributes.slot)
+  return {
+    id: String(record.id ?? ''),
+    name: String(attributes.name ?? ''),
+    slot,
+    trackingId,
+    scope,
+    active: attributes.active !== false,
+    caseSensitive: Boolean(attributes.case_sensitive),
+    description: typeof attributes.description === 'string' ? attributes.description : '',
+    websiteId: String(attributes.website_id ?? ''),
+  }
+}
+
+/**
+ * @param {ReturnType<typeof resolvePiwikConfig>} config
+ */
+export function assertApiConfig(config) {
+  if (!config.account) {
+    throw new PiwikDimensionError('Missing Piwik account. Pass --account or set it in src/config/env.ts / piwik/.piwik.json.')
+  }
+  if (!config.websiteId) {
+    throw new PiwikDimensionError('Missing website id. Pass --website-id or set piwikId in src/config/env.ts.')
+  }
+  if (!config.clientId || !config.clientSecret) {
+    throw new PiwikDimensionError(
+      'Missing Piwik API credentials. Set PIWIK_CLIENT_ID and PIWIK_CLIENT_SECRET in the environment, .env.local, or env.local.',
+    )
+  }
+}