@memberjunction/connector-ga4 0.2.0

package/dist/GA4Rows.js

@@ -0,0 +1,117 @@
+/**
+ * Projection of a GA4 report row into an `ExternalRecord`.
+ *
+ * Pure: row in, record out. This is where the two things GA4 does differently from a normal API get
+ * handled — values are POSITIONAL rather than named, and everything, including counts, arrives as a
+ * string.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Upper bound for `ExternalID`.
+ *
+ * `CompanyIntegrationRecordMap.ExternalSystemRecordID` is `nvarchar(750)`. A key that overflows it
+ * does not corrupt anything — the insert fails and the record is dead-lettered — but the row never
+ * lands, silently, for as long as the offending value keeps appearing. Below this length the key is
+ * the readable join; above it, {@link buildExternalID} substitutes a digest. The margin under 750 is
+ * for the fallback prefix.
+ */
+export const MAX_EXTERNAL_ID_LENGTH = 700;
+/** GA4's sentinel for rows collapsed together once a dimension exceeds its cardinality limit. */
+export const OTHER_ROW_SENTINEL = '(other)';
+/**
+ * Build the `ExternalID` from the declared key values.
+ *
+ * It must equal the key fields joined on '|' — that is what the engine's REST base class produces
+ * and what a `--base` connector therefore has to reproduce by hand. A mismatch does not throw:
+ * identity silently falls back to a content hash, and every run re-inserts every row.
+ *
+ * The digest fallback exists because two key components here are free text set by whoever built a
+ * marketing link. `utm_campaign` and `utm_content` have no length limit, and a tracking template
+ * that stuffs a few hundred characters into one is not exotic. Truncating would be the worse answer:
+ * two distinct campaigns sharing a prefix would collapse into one row and silently merge their
+ * numbers, which is a wrong answer rather than a missing one. The digest is deterministic, so the
+ * same row keeps the same identity across runs, and the `ga4:` prefix makes an audit of the record
+ * map able to tell the two forms apart.
+ */
+export function buildExternalID(keyValues) {
+    const joined = keyValues.join('|');
+    if (joined.length <= MAX_EXTERNAL_ID_LENGTH)
+        return joined;
+    return `ga4:${createHash('sha256').update(joined, 'utf8').digest('hex')}`;
+}
+/**
+ * GA4's `date` dimension is `YYYYMMDD` with no separators. Returns null for anything else — including
+ * `(other)`, which GA4 can in principle substitute for any dimension.
+ */
+export function parseGA4Date(value) {
+    if (!/^\d{8}$/.test(value))
+        return null;
+    const iso = `${value.slice(0, 4)}-${value.slice(4, 6)}-${value.slice(6, 8)}`;
+    // Rejects 2026-02-31 and friends: Date.parse accepts them and rolls over, which would land a row
+    // under a date GA4 never reported.
+    const parsed = new Date(`${iso}T00:00:00Z`);
+    return Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== iso ? null : iso;
+}
+/**
+ * Parse a GA4 metric value.
+ *
+ * Every metric arrives as a string, including integers, and a metric that is genuinely absent for a
+ * row arrives as `''` rather than being omitted. Absent stays null (the column is nullable and "no
+ * data" is not the same claim as "zero"); anything present but unparseable becomes null too, rather
+ * than a 0 that would read as a measured value.
+ */
+export function parseMetric(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/** Positional read of a nullable-everything array, flattened to a plain string. */
+function valueAt(list, i) {
+    return list?.[i]?.value ?? '';
+}
+/**
+ * Project one report row.
+ *
+ * Returns null when the row cannot be keyed — in practice only when `date` is not a real date, which
+ * means GA4 substituted a sentinel for it. A row with no usable key cannot be upserted, and emitting
+ * it with a made-up key would create a row that is re-inserted on every run forever.
+ *
+ * `dimensionValues` and `metricValues` are aligned by POSITION to the request's `dimensions` and
+ * `metrics`, not by name — GA4 sends the names once in the headers and never again. The catalog's
+ * `Dimensions`/`Metrics` arrays are the request order, so they are also the read order, and that
+ * single fact is why those arrays live next to the field list rather than being derived from it.
+ */
+export function projectRow(obj, row, propertyId) {
+    const fields = {};
+    let isOtherRow = false;
+    for (let i = 0; i < obj.Dimensions.length; i++) {
+        const name = obj.Dimensions[i];
+        const raw = valueAt(row.dimensionValues, i);
+        if (raw === OTHER_ROW_SENTINEL)
+            isOtherRow = true;
+        if (name === 'date') {
+            const iso = parseGA4Date(raw);
+            if (iso === null)
+                return null;
+            fields.date = iso;
+        }
+        else {
+            fields[name] = raw;
+        }
+    }
+    for (let i = 0; i < obj.Metrics.length; i++) {
+        fields[obj.Metrics[i]] = parseMetric(valueAt(row.metricValues, i));
+    }
+    fields.propertyId = propertyId;
+    const keyValues = obj.Fields.filter((f) => f.IsPrimaryKey).map((f) => String(fields[f.Name] ?? ''));
+    return {
+        Record: {
+            ExternalID: buildExternalID(keyValues),
+            ObjectType: obj.Name,
+            Fields: fields,
+        },
+        IsOtherRow: isOtherRow,
+    };
+}
+//# sourceMappingURL=GA4Rows.js.map

package/dist/GA4Rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GA4Rows.js","sourceRoot":"","sources":["../src/GA4Rows.ts"],"names":[],"mappings":"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"}

package/dist/GA4ServiceAccount.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parsing and validation of the Google service-account key.
+ *
+ * Pure and dependency-free, because every interesting failure here happens at setup time on someone
+ * else's machine and the only way to make those failures cheap is to name them precisely. A service
+ * account that authenticates but cannot read the property, or a key whose newlines were eaten in
+ * transit, both surface as an opaque Google error several layers down; caught here they are one
+ * sentence each.
+ */
+/** The fields of a Google service-account JSON this connector actually uses. */
+export interface GA4ServiceAccount {
+    client_email: string;
+    private_key: string;
+    project_id?: string;
+    private_key_id?: string;
+}
+/**
+ * The shapes a credential can legitimately arrive in.
+ *
+ * `MJ: Credentials.Values` is a JSON document, and how an operator puts a service-account key into
+ * it varies: pasted as a nested object, pasted as an escaped string, or — because the downloaded
+ * file IS the whole credential — pasted as the service-account JSON itself with no wrapper. All
+ * three are accepted. Rejecting two of them would be pure ceremony: they are unambiguous, and the
+ * alternative is a support conversation about JSON nesting.
+ */
+export declare function parseServiceAccount(values: string | null | undefined): GA4ServiceAccount;
+/**
+ * Restore real newlines in a PEM key.
+ *
+ * A service-account key is a multi-line PEM stored inside a JSON string, so it legitimately contains
+ * `\n` escapes. Whether those survive as escapes or arrive already-unescaped depends on how many
+ * times the value has been through a JSON round-trip on its way here — via an env var, a shell
+ * variable, a form field, a copy-paste. Both forms are common and only one of them is a valid key,
+ * so the escaped form is converted rather than rejected. This is the single most common GA4
+ * credential failure and it otherwise surfaces as "error:1E08010C:DECODER routines::unsupported".
+ *
+ * The order matters: `\\n` (an escaped backslash followed by n, i.e. a literal backslash in the key)
+ * is left alone, and only a lone `\n` escape becomes a newline.
+ */
+export declare function normalizePrivateKey(key: string): string;

package/dist/GA4ServiceAccount.js

@@ -0,0 +1,96 @@
+/**
+ * Parsing and validation of the Google service-account key.
+ *
+ * Pure and dependency-free, because every interesting failure here happens at setup time on someone
+ * else's machine and the only way to make those failures cheap is to name them precisely. A service
+ * account that authenticates but cannot read the property, or a key whose newlines were eaten in
+ * transit, both surface as an opaque Google error several layers down; caught here they are one
+ * sentence each.
+ */
+/**
+ * The shapes a credential can legitimately arrive in.
+ *
+ * `MJ: Credentials.Values` is a JSON document, and how an operator puts a service-account key into
+ * it varies: pasted as a nested object, pasted as an escaped string, or — because the downloaded
+ * file IS the whole credential — pasted as the service-account JSON itself with no wrapper. All
+ * three are accepted. Rejecting two of them would be pure ceremony: they are unambiguous, and the
+ * alternative is a support conversation about JSON nesting.
+ */
+export function parseServiceAccount(values) {
+    if (!values || !values.trim()) {
+        throw new Error('GA4: no credential is linked. Set CompanyIntegration.CredentialID to an MJ: Credentials record whose Values hold the Google service-account JSON, e.g. {"serviceAccountJSON": { ... }}.');
+    }
+    const root = parseJSON(values, 'the credential Values');
+    // Wrapped under a key, or the service-account JSON at the top level.
+    const candidate = pickObject(root, 'serviceAccountJSON') ??
+        pickObject(root, 'ServiceAccountJSON') ??
+        pickObject(root, 'serviceAccountKey') ??
+        root;
+    const clientEmail = typeof candidate.client_email === 'string' ? candidate.client_email.trim() : '';
+    const privateKeyRaw = typeof candidate.private_key === 'string' ? candidate.private_key : '';
+    if (!clientEmail || !privateKeyRaw) {
+        throw new Error('GA4: the linked credential does not contain a Google service-account key. Expected client_email and private_key — either at the top level of Values, or under a "serviceAccountJSON" key. ' +
+            'Use the JSON file downloaded from Google Cloud Console → IAM & Admin → Service Accounts → Keys, verbatim.');
+    }
+    const privateKey = normalizePrivateKey(privateKeyRaw);
+    if (!privateKey.includes('BEGIN PRIVATE KEY')) {
+        throw new Error('GA4: the credential\'s private_key does not look like a PEM key (no "BEGIN PRIVATE KEY" header). It is likely truncated, or the private_key_id was pasted in its place.');
+    }
+    return {
+        client_email: clientEmail,
+        private_key: privateKey,
+        project_id: typeof candidate.project_id === 'string' ? candidate.project_id : undefined,
+        private_key_id: typeof candidate.private_key_id === 'string' ? candidate.private_key_id : undefined,
+    };
+}
+/**
+ * Restore real newlines in a PEM key.
+ *
+ * A service-account key is a multi-line PEM stored inside a JSON string, so it legitimately contains
+ * `\n` escapes. Whether those survive as escapes or arrive already-unescaped depends on how many
+ * times the value has been through a JSON round-trip on its way here — via an env var, a shell
+ * variable, a form field, a copy-paste. Both forms are common and only one of them is a valid key,
+ * so the escaped form is converted rather than rejected. This is the single most common GA4
+ * credential failure and it otherwise surfaces as "error:1E08010C:DECODER routines::unsupported".
+ *
+ * The order matters: `\\n` (an escaped backslash followed by n, i.e. a literal backslash in the key)
+ * is left alone, and only a lone `\n` escape becomes a newline.
+ */
+export function normalizePrivateKey(key) {
+    const unescaped = key.includes('\n') ? key : key.replace(/\\n/g, '\n');
+    // Windows line endings inside a PEM are tolerated by OpenSSL but not by every parser in the
+    // chain; normalizing costs nothing and removes a whole class of "works on my machine".
+    return unescaped.replace(/\r\n/g, '\n').trim();
+}
+function parseJSON(text, what) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`GA4: could not parse ${what} as JSON: ${e.message}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`GA4: ${what} must be a JSON object.`);
+    }
+    return parsed;
+}
+function pickObject(root, key) {
+    const v = root[key];
+    if (v !== null && typeof v === 'object' && !Array.isArray(v))
+        return v;
+    // Also accept the nested key stored as an escaped JSON string.
+    if (typeof v === 'string' && v.trim().startsWith('{')) {
+        try {
+            const inner = JSON.parse(v);
+            if (inner !== null && typeof inner === 'object' && !Array.isArray(inner)) {
+                return inner;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=GA4ServiceAccount.js.map

package/dist/GA4ServiceAccount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GA4ServiceAccount.js","sourceRoot":"","sources":["../src/GA4ServiceAccount.ts"],"names":[],"mappings":"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"}

package/dist/GA4Window.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Date-window arithmetic and the pagination cursor.
+ *
+ * A GA4 report is addressed by a date range plus an offset into the result, so those three values
+ * — `from`, `to`, `offset` — are the whole of this connector's position in its source. They travel
+ * in the cursor rather than being recomputed per call, and that is load-bearing: the range is derived
+ * from the watermark and the clock, the engine does not advance the watermark until a run ends, and
+ * so a run that happens to cross midnight would otherwise recompute a DIFFERENT range on its second
+ * page and resume an offset into it. Offsets are only meaningful against the range that produced
+ * them.
+ *
+ * The cursor therefore also carries the run's own `today`, pinning the clock for the whole run.
+ *
+ * Format: `<today>|<from>|<to>|<offset>`, all dates `YYYY-MM-DD`.
+ */
+import type { GA4Config } from './GA4Config.js';
+/** An inclusive date range, GA4's `dateRanges` semantics. */
+export interface GA4Window {
+    From: string;
+    To: string;
+}
+export interface GA4Cursor extends GA4Window {
+    /** The run's pinned clock. Every window in the run is derived from this, not from `new Date()`. */
+    Today: string;
+    /** Rows already consumed within `[From, To]`. */
+    Offset: number;
+}
+/** The UTC date of an instant, `YYYY-MM-DD`. */
+export declare function toISODate(d: Date): string;
+/** Shift an ISO date by whole days. Returns the input unchanged if it is not a valid ISO date. */
+export declare function addDays(iso: string, days: number): string;
+/**
+ * The first window of a run.
+ *
+ * With a watermark, the window opens `lookbackDays` BEFORE it — re-reading days that are already
+ * landed, because GA4 keeps revising recent days for up to 48 hours and a strictly-forward watermark
+ * would freeze each day at its least accurate value forever.
+ *
+ * Without one, the window opens at the configured `startDate`, or {@link DEFAULT_COLD_START_DAYS}
+ * back when there is none.
+ *
+ * The `startDate` floor is applied in BOTH branches on purpose: it is a statement about what this
+ * property is allowed to be read for, and the lookback must not be able to reach behind it.
+ */
+export declare function initialWindow(config: GA4Config, watermark: string | null, today: string): GA4Window;
+/**
+ * The window after this one, or null when the run has reached `today`.
+ *
+ * Advancing here rather than ending the run is what lets a cold backfill of a year finish in a single
+ * run: `maxWindowDays` bounds each REQUEST, not the run.
+ */
+export declare function nextWindow(current: GA4Window, config: GA4Config, today: string): GA4Window | null;
+export declare function formatCursor(c: GA4Cursor): string;
+/**
+ * Parse a cursor, or null when it is absent or malformed.
+ *
+ * Null means "start this object over from the watermark", which is always safe: identity is the
+ * declared key, so re-reading rows upserts them. Throwing instead would strand the object on a bad
+ * cursor with no way forward short of clearing it by hand.
+ */
+export declare function parseCursor(raw: string | null | undefined): GA4Cursor | null;

package/dist/GA4Window.js

@@ -0,0 +1,83 @@
+import { DEFAULT_COLD_START_DAYS } from './GA4Config.js';
+const SEP = '|';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const MS_PER_DAY = 86_400_000;
+/** The UTC date of an instant, `YYYY-MM-DD`. */
+export function toISODate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/** Shift an ISO date by whole days. Returns the input unchanged if it is not a valid ISO date. */
+export function addDays(iso, days) {
+    const base = Date.parse(`${iso}T00:00:00Z`);
+    if (Number.isNaN(base))
+        return iso;
+    return new Date(base + days * MS_PER_DAY).toISOString().slice(0, 10);
+}
+/** Lexicographic comparison is date comparison for `YYYY-MM-DD`, which is why this format is used throughout. */
+const minDate = (a, b) => (a < b ? a : b);
+const maxDate = (a, b) => (a > b ? a : b);
+/**
+ * The first window of a run.
+ *
+ * With a watermark, the window opens `lookbackDays` BEFORE it — re-reading days that are already
+ * landed, because GA4 keeps revising recent days for up to 48 hours and a strictly-forward watermark
+ * would freeze each day at its least accurate value forever.
+ *
+ * Without one, the window opens at the configured `startDate`, or {@link DEFAULT_COLD_START_DAYS}
+ * back when there is none.
+ *
+ * The `startDate` floor is applied in BOTH branches on purpose: it is a statement about what this
+ * property is allowed to be read for, and the lookback must not be able to reach behind it.
+ */
+export function initialWindow(config, watermark, today) {
+    const coldStart = config.startDate ?? addDays(today, -DEFAULT_COLD_START_DAYS);
+    let from = watermark && ISO_DATE.test(watermark.slice(0, 10))
+        ? addDays(watermark.slice(0, 10), -config.lookbackDays)
+        : coldStart;
+    if (config.startDate)
+        from = maxDate(from, config.startDate);
+    from = minDate(from, today);
+    return { From: from, To: windowEnd(from, config, today) };
+}
+/**
+ * The window after this one, or null when the run has reached `today`.
+ *
+ * Advancing here rather than ending the run is what lets a cold backfill of a year finish in a single
+ * run: `maxWindowDays` bounds each REQUEST, not the run.
+ */
+export function nextWindow(current, config, today) {
+    if (current.To >= today)
+        return null;
+    const from = addDays(current.To, 1);
+    return { From: from, To: windowEnd(from, config, today) };
+}
+function windowEnd(from, config, today) {
+    return minDate(addDays(from, config.maxWindowDays - 1), today);
+}
+export function formatCursor(c) {
+    return [c.Today, c.From, c.To, c.Offset].join(SEP);
+}
+/**
+ * Parse a cursor, or null when it is absent or malformed.
+ *
+ * Null means "start this object over from the watermark", which is always safe: identity is the
+ * declared key, so re-reading rows upserts them. Throwing instead would strand the object on a bad
+ * cursor with no way forward short of clearing it by hand.
+ */
+export function parseCursor(raw) {
+    if (!raw)
+        return null;
+    const parts = raw.split(SEP);
+    if (parts.length !== 4)
+        return null;
+    const [today, from, to, offsetRaw] = parts;
+    if (!ISO_DATE.test(today) || !ISO_DATE.test(from) || !ISO_DATE.test(to))
+        return null;
+    if (from > to)
+        return null;
+    const offset = Number(offsetRaw);
+    if (!Number.isInteger(offset) || offset < 0)
+        return null;
+    return { Today: today, From: from, To: to, Offset: offset };
+}
+//# sourceMappingURL=GA4Window.js.map

package/dist/GA4Window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GA4Window.js","sourceRoot":"","sources":["../src/GA4Window.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './GA4Connector.js';
+/** Open App bootstrap entry: importing this module ran the connector's @RegisterClass decorator;
+ *  this no-op satisfies the loader's required startupExport and forces the import at MJAPI boot. */
+export declare function registerConnector(): void;

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './GA4Connector.js';
+/** Open App bootstrap entry: importing this module ran the connector's @RegisterClass decorator;
+ *  this no-op satisfies the loader's required startupExport and forces the import at MJAPI boot. */
+export function registerConnector() { }
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAElC;oGACoG;AACpG,MAAM,UAAU,iBAAiB,KAAiD,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@memberjunction/connector-ga4",
+  "version": "0.2.0",
+  "description": "MemberJunction Google Analytics 4 connector (Data API v1beta).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "peerDependencies": {
+    "@memberjunction/core": ">=5.43.0 <6.0.0",
+    "@memberjunction/core-entities": ">=5.43.0 <6.0.0",
+    "@memberjunction/global": ">=5.43.0 <6.0.0",
+    "@memberjunction/integration-engine": ">=5.43.0 <6.0.0"
+  },
+  "dependencies": {
+    "@google-analytics/data": "^7.0.0",
+    "zod": "~3.24.4"
+  },
+  "devDependencies": {
+    "@memberjunction/core": "^5.43.0",
+    "@memberjunction/core-entities": "^5.43.0",
+    "@memberjunction/global": "^5.43.0",
+    "@memberjunction/integration-engine": "^5.43.0",
+    "@types/node": "24.10.11",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/Integrations"
+  }
+}