Schema.gs

/**
 * Schema.gs — Field definitions and Looker ↔ Plausible mapping.
 *
 * Each entry of {@link STATIC_FIELDS} carries:
 *   - `id`         — The Looker field identifier (used by Looker requests/filters).
 *   - `name`       — Human-readable label shown in the Looker UI.
 *   - `kind`       — `'metric'` or `'dimension'`.
 *   - `plausible`  — The corresponding Plausible API name (e.g. `event:page`).
 *   - `looker.type`— Looker FieldType enum key, resolved at runtime via
 *                    `cc.FieldType[...]`.
 *   - `looker.agg` — Default aggregation for metrics (`SUM`, `AVG`, …).
 *   - `scale`      — Optional multiplier applied in `convertMetricValue_`,
 *                    used to convert Plausible's 0–100 percentages to Looker's
 *                    0–1 PERCENT format.
 *   - `inversePercent` — When set, computes `1 - (v * scale)`. Used by
 *                        Engagement Rate, which is the inverse of Bounce Rate.
 *
 * Custom properties are appended at runtime by {@link buildFields_} based on
 * the comma-separated list provided in the data-source config.
 *
 * References:
 *   - Plausible metrics & dimensions: https://plausible.io/docs/stats-api
 *   - Looker Studio FieldType enum:
 *     https://developers.google.com/looker-studio/connector/reference#fieldtype
 *   - Looker Studio AggregationType enum:
 *     https://developers.google.com/looker-studio/connector/reference#aggregationtype
 */

/**
 * @const {!Array<!Object>}
 * Static field catalogue. Order here drives the order shown in Looker Studio.
 */
var STATIC_FIELDS = [
    // ---- Metrics ----
    { id: 'visitors',              name: 'Visitors',              kind: 'metric',    plausible: 'visitors',              looker: { type: 'NUMBER',  agg: 'SUM' } },
    { id: 'visits',                name: 'Visits',                kind: 'metric',    plausible: 'visits',                looker: { type: 'NUMBER',  agg: 'SUM' } },
    { id: 'pageviews',             name: 'Pageviews',             kind: 'metric',    plausible: 'pageviews',             looker: { type: 'NUMBER',  agg: 'SUM' } },
    { id: 'views_per_visit',       name: 'Views per Visit',       kind: 'metric',    plausible: 'views_per_visit',       looker: { type: 'NUMBER',  agg: 'AVG' } },
    { id: 'bounce_rate',           name: 'Bounce Rate',           kind: 'metric',    plausible: 'bounce_rate',           looker: { type: 'PERCENT', agg: 'AVG' }, scale: 0.01 },
    { id: 'engagement_rate',       name: 'Engagement Rate',       kind: 'metric',    plausible: 'bounce_rate',           looker: { type: 'PERCENT', agg: 'AVG' }, scale: 0.01, inversePercent: true },
    { id: 'visit_duration',        name: 'Visit Duration (s)',    kind: 'metric',    plausible: 'visit_duration',        looker: { type: 'NUMBER',  agg: 'AVG' } },
    { id: 'events',                name: 'Events',                kind: 'metric',    plausible: 'events',                looker: { type: 'NUMBER',  agg: 'SUM' } },
    { id: 'scroll_depth',          name: 'Scroll Depth',          kind: 'metric',    plausible: 'scroll_depth',          looker: { type: 'PERCENT', agg: 'AVG' }, scale: 0.01 },
    { id: 'time_on_page',          name: 'Time on Page (s)',      kind: 'metric',    plausible: 'time_on_page',          looker: { type: 'NUMBER',  agg: 'AVG' } },
    { id: 'conversion_rate',       name: 'Conversion Rate',       kind: 'metric',    plausible: 'conversion_rate',       looker: { type: 'PERCENT', agg: 'AVG' }, scale: 0.01 },
    { id: 'group_conversion_rate', name: 'Group Conversion Rate', kind: 'metric',    plausible: 'group_conversion_rate', looker: { type: 'PERCENT', agg: 'AVG' }, scale: 0.01 },
    // Revenue metrics are NOT available in Plausible Community Edition (only in
    // Plausible Cloud with paid Revenue Goals). Re-enable these lines if a future
    // CE release exposes them.
    // { id: 'total_revenue',         name: 'Total Revenue',         kind: 'metric',    plausible: 'total_revenue',         looker: { type: 'NUMBER',  agg: 'SUM' } },
    // { id: 'average_revenue',       name: 'Average Revenue',       kind: 'metric',    plausible: 'average_revenue',       looker: { type: 'NUMBER',  agg: 'AVG' } },
    { id: 'percentage',            name: 'Percentage',            kind: 'metric',    plausible: 'percentage',            looker: { type: 'PERCENT', agg: 'AVG' }, scale: 0.01 },

    // ---- Time dimensions ----
    { id: 'date',                  name: 'Date',                  kind: 'dimension', plausible: 'time:day',              looker: { type: 'YEAR_MONTH_DAY' } },
    { id: 'hour',                  name: 'Hour',                  kind: 'dimension', plausible: 'time:hour',             looker: { type: 'YEAR_MONTH_DAY_HOUR' } },
    { id: 'week',                  name: 'Week',                  kind: 'dimension', plausible: 'time:week',             looker: { type: 'YEAR_WEEK' } },
    { id: 'month',                 name: 'Month',                 kind: 'dimension', plausible: 'time:month',            looker: { type: 'YEAR_MONTH' } },

    // ---- Event dimensions ----
    { id: 'page',                  name: 'Page',                  kind: 'dimension', plausible: 'event:page',            looker: { type: 'URL' } },
    { id: 'hostname',              name: 'Hostname',              kind: 'dimension', plausible: 'event:hostname',        looker: { type: 'TEXT' } },
    { id: 'goal',                  name: 'Goal',                  kind: 'dimension', plausible: 'event:goal',            looker: { type: 'TEXT' } },

    // ---- Visit dimensions ----
    { id: 'entry_page',            name: 'Entry Page',            kind: 'dimension', plausible: 'visit:entry_page',      looker: { type: 'URL' } },
    { id: 'exit_page',             name: 'Exit Page',             kind: 'dimension', plausible: 'visit:exit_page',       looker: { type: 'URL' } },
    { id: 'source',                name: 'Source',                kind: 'dimension', plausible: 'visit:source',          looker: { type: 'TEXT' } },
    { id: 'referrer',              name: 'Referrer',              kind: 'dimension', plausible: 'visit:referrer',        looker: { type: 'TEXT' } },
    { id: 'channel',               name: 'Channel',               kind: 'dimension', plausible: 'visit:channel',         looker: { type: 'TEXT' } },
    { id: 'utm_medium',            name: 'UTM Medium',            kind: 'dimension', plausible: 'visit:utm_medium',      looker: { type: 'TEXT' } },
    { id: 'utm_source',            name: 'UTM Source',            kind: 'dimension', plausible: 'visit:utm_source',      looker: { type: 'TEXT' } },
    { id: 'utm_campaign',          name: 'UTM Campaign',          kind: 'dimension', plausible: 'visit:utm_campaign',    looker: { type: 'TEXT' } },
    { id: 'utm_content',           name: 'UTM Content',           kind: 'dimension', plausible: 'visit:utm_content',     looker: { type: 'TEXT' } },
    { id: 'utm_term',              name: 'UTM Term',              kind: 'dimension', plausible: 'visit:utm_term',        looker: { type: 'TEXT' } },
    { id: 'device',                name: 'Device',                kind: 'dimension', plausible: 'visit:device',          looker: { type: 'TEXT' } },
    { id: 'browser',               name: 'Browser',               kind: 'dimension', plausible: 'visit:browser',         looker: { type: 'TEXT' } },
    { id: 'browser_version',       name: 'Browser Version',       kind: 'dimension', plausible: 'visit:browser_version', looker: { type: 'TEXT' } },
    { id: 'os',                    name: 'OS',                    kind: 'dimension', plausible: 'visit:os',              looker: { type: 'TEXT' } },
    { id: 'os_version',            name: 'OS Version',            kind: 'dimension', plausible: 'visit:os_version',      looker: { type: 'TEXT' } },
    { id: 'country',               name: 'Country (ISO-2)',       kind: 'dimension', plausible: 'visit:country',         looker: { type: 'COUNTRY' } },
    { id: 'country_name',          name: 'Country Name',          kind: 'dimension', plausible: 'visit:country_name',    looker: { type: 'TEXT' } },
    { id: 'region',                name: 'Region (ISO)',          kind: 'dimension', plausible: 'visit:region',          looker: { type: 'TEXT' } },
    { id: 'region_name',           name: 'Region Name',           kind: 'dimension', plausible: 'visit:region_name',     looker: { type: 'TEXT' } },
    { id: 'city',                  name: 'City (GeoName ID)',     kind: 'dimension', plausible: 'visit:city',            looker: { type: 'CITY' } },
    { id: 'city_name',             name: 'City Name',             kind: 'dimension', plausible: 'visit:city_name',       looker: { type: 'TEXT' } }
];


/**
 * Build the effective field catalogue for a given config.
 *
 * Returns the static catalogue plus:
 *   - One TEXT dimension per custom property in `configParams.customProps`
 *     (identified by `isCustomProp: true`).
 *   - A single "Sprachversion" TEXT dimension when `configParams.languageVersionPrefixes`
 *     is non-empty (identified by `isLanguageVersion: true`). This dimension
 *     derives its values from `event:page` at response-mapping time by matching
 *     the configured URL prefixes (e.g. `de-de` → `/de-de/`).
 *
 * @param {?{customProps: ?string, languageVersionPrefixes: ?string}} configParams
 * @return {!Array<!Object>}
 */
function buildFields_(configParams) {
    var fields = STATIC_FIELDS.slice();
    var props = parseCustomProps_(configParams && configParams.customProps);

    props.forEach(function (propName) {
        fields.push({
            id: 'prop_' + propName.replace(/[^a-zA-Z0-9_]/g, '_'),
            name: 'Property: ' + propName,
            kind: 'dimension',
            plausible: 'event:props:' + propName,
            looker: { type: 'TEXT' },
            isCustomProp: true
        });
    });

    var langPrefixes = parseCustomProps_(configParams && configParams.languageVersionPrefixes);
    if (langPrefixes.length > 0) {
        fields.push({
            id: 'language_version',
            name: 'Language Version',
            kind: 'dimension',
            plausible: 'event:page',
            looker: { type: 'TEXT' },
            isLanguageVersion: true,
            langPrefixes: langPrefixes
        });
    }

    return fields;
}


/**
 * Build a flat lookup `{ fieldId → plausibleName }` for the active config.
 * Used by {@link translateFilters_} to turn Looker `fieldName`s into
 * Plausible dimension names.
 *
 * @param {?Object} configParams
 * @return {!Object<string, string>}
 */
function buildFieldToPlausibleMap_(configParams) {
    var map = {};
    buildFields_(configParams).forEach(function (f) {
        map[f.id] = f.plausible;
    });
    return map;
}


/**
 * Linear lookup of a field by its Looker id.
 *
 * Linear search is fine here — the catalogue has ~40 entries and is hit a
 * handful of times per request, so building a lookup map per call would be
 * more overhead than savings.
 *
 * @param {!Array<!Object>} fields
 * @param {string} id
 * @return {?Object} The field, or `null` if not found.
 */
function getFieldById_(fields, id) {
    for (var i = 0; i < fields.length; i++) {
        if (fields[i].id === id) return fields[i];
    }
    return null;
}


/**
 * Translate the internal field catalogue into a Looker Studio `Fields`
 * builder, ready to be `.build()`-ed by the connector entry points.
 *
 * @param {?Object} configParams
 * @return {!GoogleAppsScript.Data_Studio.Fields}
 */
function getSchemaFields(configParams) {
    var cc = DataStudioApp.createCommunityConnector();
    var types = cc.FieldType;
    var aggs = cc.AggregationType;
    var fields = cc.getFields();

    buildFields_(configParams).forEach(function (f) {
        var b = (f.kind === 'metric') ? fields.newMetric() : fields.newDimension();
        b.setId(f.id).setName(f.name).setType(types[f.looker.type]);
        if (f.kind === 'metric' && f.looker.agg && aggs[f.looker.agg]) {
            b.setAggregation(aggs[f.looker.agg]);
        }
    });

    return fields;
}