@memberjunction/connector-ga4 0.2.0

package/dist/GA4Objects.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The declared object/field catalog — the single source of truth for this connector's schema.
+ *
+ * WHY A TS CATALOG. This is a `--base` connector: the Data API has no "list my tables" surface to
+ * introspect. A GA4 report is a request you compose, not a resource you discover, so the objects
+ * below are *defined* reports — a chosen set of dimensions and metrics with a name — and
+ * `DiscoverObjects`/`DiscoverFields` answer from this table. It also has to work BEFORE the
+ * integration metadata is seeded, which is the state the connector is in at first setup.
+ *
+ * `scripts/gen-integration-metadata.mjs` projects this table into
+ * `metadata/integration/.ga4.integration.json`, so this file is the authority and that JSON is a
+ * build artifact. Maintaining both by hand is what makes the two drift silently: the created columns
+ * stop matching the emitted records and the sync lands nulls rather than failing.
+ *
+ * ── WHY THREE OBJECTS AND NOT ONE ────────────────────────────────────────────────────────────────
+ *
+ * The three differ only in their dimension list, and it is tempting to ship the finest grain alone
+ * and let consumers roll up. That would be wrong, and the reason is worth stating once here because
+ * it is the single most consequential design fact in this connector:
+ *
+ *   **GA4's user metrics are cardinalities, and cardinalities are not additive.**
+ *
+ * `totalUsers` and `activeUsers` are counts of DISTINCT users, de-duplicated by GA4 at exactly the
+ * grain you requested. One person who arrives twice in a day from two campaigns counts once in a
+ * campaign-less report and once in EACH campaign row of a campaign-scoped one. So summing the
+ * campaign rows does not give you the campaign-less answer — it gives you a number that is too big by
+ * however much your audiences overlap, and nothing in the data says by how much.
+ *
+ * `sessions`, `engagedSessions`, `screenPageViews`, `keyEvents` and `userEngagementDuration` ARE
+ * additive and could be rolled up. The user counts cannot be, ever. Since a rollup that is right for
+ * five columns and quietly wrong for two is worse than no rollup at all, each grain that anyone
+ * actually wants user counts at is asked of GA4 directly, as its own report.
+ *
+ * That is also why each object is its own `runReport` call rather than one call re-projected: the
+ * de-duplication has to happen inside GA4, at the grain requested.
+ *
+ * ── WHAT IS DELIBERATELY NOT HERE ────────────────────────────────────────────────────────────────
+ *
+ * No ratio metrics (`bounceRate`, `engagementRate`, `sessionKeyEventRate`, …). Every one is a
+ * quotient of two columns already present, so landing it adds a number that is correct only at the
+ * exact grain it was fetched at and silently wrong the moment anyone groups the table — the same
+ * non-additivity trap as above, but without the excuse of being un-derivable. Consumers divide.
+ *
+ * No `firstUser*` attribution dimensions. They attribute to the first touch EVER rather than to the
+ * touch that drove the session, so mixing them into the same row as session-scoped metrics produces
+ * a table where the dimensions and the numbers answer different questions.
+ */
+import type { IntegrationObjectInfo } from '@memberjunction/integration-engine';
+/**
+ * The complete set of type tokens the schema builder understands.
+ *
+ * `IntegrationObjectField.Type` is a plain `nvarchar(200)` with no check constraint, and an
+ * unrecognized token does not error — it falls through to `NVARCHAR(MAX)`. This union is the schema
+ * builder's TYPE_MAP key set, so an unsupported token is a compile error here instead of a silently
+ * unbounded column at deploy time.
+ */
+export type CatalogType = 'nvarchar' | 'string' | 'text' | 'integer' | 'bigint' | 'decimal' | 'boolean' | 'datetime' | 'date' | 'uuid' | 'json' | 'float' | 'time';
+/** One IntegrationObjectField, with the five attributes `IntegrationFieldInfo` cannot express. */
+export interface CatalogField {
+    Name: string;
+    DisplayName: string;
+    Description: string;
+    Type: CatalogType;
+    Length?: number;
+    Precision?: number;
+    Scale?: number;
+    IsPrimaryKey: boolean;
+    IsUniqueKey: boolean;
+    IsRequired: boolean;
+    IsReadOnly: boolean;
+    AllowsNull: boolean;
+}
+/** One IntegrationObject — here, one *defined report*. */
+export interface CatalogObject {
+    Name: string;
+    DisplayName: string;
+    Description: string;
+    /**
+     * `IntegrationObject.APIPath` is NOT NULL. Every object goes to the same `:runReport` endpoint
+     * and differs only in its request body, so the path carries the object name as a fragment to
+     * stay unique and to name what actually varies.
+     */
+    APIPath: string;
+    Category: string;
+    SupportsIncrementalSync: boolean;
+    IncrementalWatermarkField: string | null;
+    PaginationType: 'Cursor';
+    /** GA4 API dimension names, in request order. Positionally aligned to `dimensionValues`. */
+    Dimensions: string[];
+    /** GA4 API metric names, in request order. Positionally aligned to `metricValues`. */
+    Metrics: string[];
+    Fields: CatalogField[];
+}
+export declare const GA4_OBJECTS: CatalogObject[];
+/** Look an object up, or throw naming the ones that exist — the message worth getting. */
+export declare function catalogObject(name: string): CatalogObject;
+/** The key field names of an object, in declared order — the order `ExternalID` joins them in. */
+export declare function primaryKeyFields(o: CatalogObject): string[];
+/** Narrow a catalog object back to the framework type, which cannot carry the extra attributes. */
+export declare function toIntegrationObjectInfo(o: CatalogObject): IntegrationObjectInfo;

package/dist/GA4Objects.js

@@ -0,0 +1,191 @@
+// ── Field constructors ────────────────────────────────────────────────────────
+// Everything here is read-only: a GA4 report is a computed answer, not a record you can write back.
+const dimField = (Name, Description, Length, pk) => ({
+    Name,
+    DisplayName: Name,
+    Description,
+    Type: 'nvarchar',
+    Length,
+    IsPrimaryKey: pk,
+    IsUniqueKey: false,
+    IsRequired: pk,
+    IsReadOnly: true,
+    // Never null in practice: GA4 substitutes its own sentinels — '(not set)', '(direct)', '(none)'
+    // — rather than omitting a dimension value. Declared NOT NULL for the key components so the
+    // constraint states that, and nullable elsewhere so a future dimension that CAN be absent does
+    // not need a schema change.
+    AllowsNull: !pk,
+});
+/** A whole-number metric. GA4 returns every metric as a string; these parse as integers. */
+const countField = (Name, Description) => ({
+    Name,
+    DisplayName: Name,
+    Description,
+    Type: 'bigint',
+    IsPrimaryKey: false,
+    IsUniqueKey: false,
+    IsRequired: false,
+    IsReadOnly: true,
+    AllowsNull: true,
+});
+/** A metric GA4 types as FLOAT. `keyEvents` is one — it is float-typed even though it counts. */
+const rateField = (Name, Description) => ({
+    Name,
+    DisplayName: Name,
+    Description,
+    Type: 'decimal',
+    Precision: 18,
+    Scale: 4,
+    IsPrimaryKey: false,
+    IsUniqueKey: false,
+    IsRequired: false,
+    IsReadOnly: true,
+    AllowsNull: true,
+});
+// ── Shared field groups ───────────────────────────────────────────────────────
+/**
+ * The reporting day, as a real date rather than GA4's `YYYYMMDD` string.
+ *
+ * It is the first key component of every object because it is what makes these rows *records* at
+ * all. A GA4 report aggregated over a range is a single answer that changes shape every time the
+ * range moves; adding `date` to the dimensions turns it into one stable row per day, which is the
+ * only form that can be upserted by key across runs.
+ */
+const DATE_FIELD = dimField('date', 'The reporting day in the property\'s configured reporting time zone. GA4 returns this as YYYYMMDD; it is normalized to a date here.', 10, true);
+/**
+ * Provenance, stamped by the connector rather than returned by GA4.
+ *
+ * Not part of the key: one CompanyIntegration row addresses exactly one property, so within a synced
+ * table it is constant. It is carried anyway because the table outlives the configuration that
+ * produced it, and "which property is this?" is otherwise unanswerable from the data.
+ */
+const PROPERTY_ID_FIELD = {
+    Name: 'propertyId',
+    DisplayName: 'propertyId',
+    Description: 'The numeric GA4 property this row was read from. Stamped by the connector from Configuration.propertyId; GA4 does not return it.',
+    Type: 'nvarchar',
+    Length: 32,
+    IsPrimaryKey: false,
+    IsUniqueKey: false,
+    IsRequired: false,
+    IsReadOnly: true,
+    AllowsNull: true,
+};
+/** The additive engagement counts, shared by all three reports. */
+const ENGAGEMENT_METRIC_FIELDS = [
+    countField('sessions', 'Sessions in this row\'s grain. Additive across rows.'),
+    countField('engagedSessions', 'Sessions that lasted 10+ seconds, had a key event, or had 2+ screen views. Additive across rows.'),
+    countField('userEngagementDuration', 'Total time the app or site was in the foreground, in SECONDS, summed over the row. Additive across rows. Divide by sessions or users for an average — the average itself is deliberately not landed, because an average cannot be re-aggregated.'),
+    countField('screenPageViews', 'Screen and page views, counting repeat views of the same page. Additive across rows.'),
+    rateField('keyEvents', 'Key events (what GA4 called "conversions" before the May 2024 rename). Float-typed by GA4 because a key event can be weighted. Additive across rows.'),
+];
+/**
+ * The two user cardinalities.
+ *
+ * Split out from the additive metrics and described as non-additive on every object, because this is
+ * the fact that gets a downstream rollup wrong, and the column description is the only place a
+ * consumer reading the landed table will encounter it.
+ */
+const USER_METRIC_FIELDS = [
+    countField('totalUsers', 'DISTINCT users in this row\'s grain. NOT ADDITIVE — GA4 de-duplicates users at the grain requested, so summing rows double-counts anyone who appears in more than one. Use the object whose grain you want.'),
+    countField('activeUsers', 'DISTINCT users who had an engaged session. NOT ADDITIVE, for the same reason as totalUsers.'),
+];
+/** The UTM dimensions, in GA4 request order. Session-scoped — see the object descriptions. */
+const CAMPAIGN_DIM_FIELDS = [
+    dimField('sessionCampaignName', 'utm_campaign for the session. GA4 returns \'(not set)\' / \'(direct)\' / \'(organic)\' verbatim rather than null; those sentinels are preserved.', 255, true),
+    dimField('sessionSource', 'utm_source for the session, e.g. google, newsletter, (direct).', 255, true),
+    dimField('sessionMedium', 'utm_medium for the session, e.g. cpc, email, organic, (none).', 255, true),
+];
+// ── The catalog ───────────────────────────────────────────────────────────────
+export const GA4_OBJECTS = [
+    {
+        Name: 'PagePerformance',
+        DisplayName: 'Page Performance',
+        Description: 'Daily traffic and engagement per page path. One row per (date, pagePath). The page-level report the legacy AIDP provider read, minus its slug-to-Blog join — this lands the raw dimensioned rows and the CRM join happens downstream.',
+        APIPath: '/v1beta/properties/{propertyId}:runReport#PagePerformance',
+        Category: 'Marketing',
+        SupportsIncrementalSync: true,
+        IncrementalWatermarkField: 'date',
+        PaginationType: 'Cursor',
+        Dimensions: ['date', 'pagePath'],
+        Metrics: ['screenPageViews', 'totalUsers', 'activeUsers', 'sessions', 'engagedSessions', 'userEngagementDuration', 'keyEvents'],
+        Fields: [
+            DATE_FIELD,
+            dimField('pagePath', 'Page path WITHOUT the query string (GA4 dimension pagePath, not pagePathPlusQueryString) — so /pricing?utm_source=x and /pricing are one row, which is what a page-performance report wants.', 512, true),
+            ...ENGAGEMENT_METRIC_FIELDS,
+            ...USER_METRIC_FIELDS,
+            PROPERTY_ID_FIELD,
+        ],
+    },
+    {
+        Name: 'UtmPerformance',
+        DisplayName: 'UTM Performance',
+        Description: 'Daily traffic per campaign / source / medium; one row per (date, campaign, source, medium). Session-scoped: a session is credited to the campaign that drove it. Read user counts at THIS grain — they are cardinalities and do not sum up from finer rows.',
+        APIPath: '/v1beta/properties/{propertyId}:runReport#UtmPerformance',
+        Category: 'Marketing',
+        SupportsIncrementalSync: true,
+        IncrementalWatermarkField: 'date',
+        PaginationType: 'Cursor',
+        Dimensions: ['date', 'sessionCampaignName', 'sessionSource', 'sessionMedium'],
+        Metrics: ['sessions', 'totalUsers', 'activeUsers', 'engagedSessions', 'userEngagementDuration', 'screenPageViews', 'keyEvents'],
+        Fields: [
+            DATE_FIELD,
+            ...CAMPAIGN_DIM_FIELDS,
+            ...ENGAGEMENT_METRIC_FIELDS,
+            ...USER_METRIC_FIELDS,
+            PROPERTY_ID_FIELD,
+        ],
+    },
+    {
+        Name: 'UtmContentPerformance',
+        DisplayName: 'UTM Content Performance',
+        Description: 'The daily campaign report split one level finer, by utm_content; one row per (date, campaign, source, medium, content). utm_content carries the variant tag, so an A/B comparison lives here. Additive metrics roll up to UtmPerformance; user counts do not.',
+        APIPath: '/v1beta/properties/{propertyId}:runReport#UtmContentPerformance',
+        Category: 'Marketing',
+        SupportsIncrementalSync: true,
+        IncrementalWatermarkField: 'date',
+        PaginationType: 'Cursor',
+        Dimensions: ['date', 'sessionCampaignName', 'sessionSource', 'sessionMedium', 'sessionManualAdContent'],
+        Metrics: ['sessions', 'totalUsers', 'activeUsers', 'engagedSessions', 'userEngagementDuration', 'screenPageViews', 'keyEvents'],
+        Fields: [
+            DATE_FIELD,
+            ...CAMPAIGN_DIM_FIELDS,
+            dimField('sessionManualAdContent', 'utm_content for the session (GA4 UI name "Session manual ad content"). Free text set by whoever built the link; \'(not set)\' when absent. Any variant convention encoded in it belongs to the tagger and is parsed downstream, not here.', 255, true),
+            ...ENGAGEMENT_METRIC_FIELDS,
+            ...USER_METRIC_FIELDS,
+            PROPERTY_ID_FIELD,
+        ],
+    },
+];
+const BY_NAME = new Map(GA4_OBJECTS.map((o) => [o.Name, o]));
+/** Look an object up, or throw naming the ones that exist — the message worth getting. */
+export function catalogObject(name) {
+    const found = BY_NAME.get(name);
+    if (!found) {
+        throw new Error(`GA4: unknown object '${name}'. This connector defines: ${GA4_OBJECTS.map((o) => o.Name).join(', ')}.`);
+    }
+    return found;
+}
+/** The key field names of an object, in declared order — the order `ExternalID` joins them in. */
+export function primaryKeyFields(o) {
+    return o.Fields.filter((f) => f.IsPrimaryKey).map((f) => f.Name);
+}
+/** Narrow a catalog object back to the framework type, which cannot carry the extra attributes. */
+export function toIntegrationObjectInfo(o) {
+    return {
+        Name: o.Name,
+        DisplayName: o.DisplayName,
+        Description: o.Description,
+        SupportsWrite: false,
+        Fields: o.Fields.map((f) => ({
+            Name: f.Name,
+            DisplayName: f.DisplayName,
+            Description: f.Description,
+            Type: f.Type,
+            IsRequired: f.IsRequired,
+            IsReadOnly: f.IsReadOnly,
+            IsPrimaryKey: f.IsPrimaryKey,
+        })),
+    };
+}
+//# sourceMappingURL=GA4Objects.js.map

package/dist/GA4Objects.js.map

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

package/dist/GA4Report.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The seam between this connector and Google.
+ *
+ * Everything that talks to the network lives behind {@link GA4ReportPort}, which has exactly one
+ * method. That is not indirection for its own sake: it is what lets the whole fetch loop — window
+ * arithmetic, cursor advance, `(other)`-row detection, record projection, watermark — be exercised
+ * against canned responses with no credential, which is the only verification available to this
+ * connector before a live property exists to point it at.
+ *
+ * The types below are the subset of the v1beta `runReport` request/response this connector uses,
+ * declared locally rather than imported from the Google client. Two reasons: the generated protobuf
+ * types make everything optional and nullable, which pushes a `?? ''` onto every field access at the
+ * call site; and a test fake should not have to construct a protobuf.
+ */
+/** A `runReport` request. Field names match the REST/JSON API exactly. */
+export interface GA4RunReportRequest {
+    /** `properties/<numeric id>`. */
+    property: string;
+    dateRanges: Array<{
+        startDate: string;
+        endDate: string;
+    }>;
+    dimensions: Array<{
+        name: string;
+    }>;
+    metrics: Array<{
+        name: string;
+    }>;
+    limit: number;
+    offset: number;
+    /** Ask GA4 to report remaining quota alongside the data, so exhaustion is visible before it bites. */
+    returnPropertyQuota?: boolean;
+}
+export interface GA4Row {
+    dimensionValues?: Array<{
+        value?: string | null;
+    } | null> | null;
+    metricValues?: Array<{
+        value?: string | null;
+    } | null> | null;
+}
+export interface GA4QuotaBucket {
+    consumed?: number | null;
+    remaining?: number | null;
+}
+export interface GA4RunReportResponse {
+    rows?: GA4Row[] | null;
+    /** Total rows matching the query, across all pages. GA4 returns this on every page. */
+    rowCount?: number | null;
+    dimensionHeaders?: Array<{
+        name?: string | null;
+    } | null> | null;
+    metricHeaders?: Array<{
+        name?: string | null;
+    } | null> | null;
+    metadata?: {
+        /** True when cardinality limits forced some rows into an aggregate `(other)` row. */
+        dataLossFromOtherRow?: boolean | null;
+        /** True when results were withheld or thresholded for privacy (small audiences). */
+        subjectToThresholding?: boolean | null;
+        timeZone?: string | null;
+        currencyCode?: string | null;
+    } | null;
+    propertyQuota?: {
+        tokensPerDay?: GA4QuotaBucket | null;
+        tokensPerHour?: GA4QuotaBucket | null;
+        concurrentRequests?: GA4QuotaBucket | null;
+        potentiallyThresholdedRequestsPerHour?: GA4QuotaBucket | null;
+    } | null;
+}
+/** The one operation this connector performs against Google. */
+export interface GA4ReportPort {
+    RunReport(request: GA4RunReportRequest): Promise<GA4RunReportResponse>;
+}
+/**
+ * The live port, over `@google-analytics/data`'s `BetaAnalyticsDataClient`.
+ *
+ * The client is imported lazily and constructed once per port instance. Lazy because the Google
+ * client drags in `google-gax` and its gRPC stack — a substantial import that a test run, a
+ * `TestConnection` against a misconfigured credential, or an MJAPI boot that never syncs GA4 should
+ * not pay for. Once per instance because the client caches its OAuth token: rebuilding it per request
+ * would mint a fresh JWT and round-trip Google's token endpoint on every page of every window.
+ */
+export declare class DefaultGA4ReportPort implements GA4ReportPort {
+    private readonly clientEmail;
+    private readonly privateKey;
+    private client;
+    constructor(clientEmail: string, privateKey: string);
+    RunReport(request: GA4RunReportRequest): Promise<GA4RunReportResponse>;
+    private Client;
+}
+/**
+ * Is this error Google's rate limiter?
+ *
+ * GA4 meters by "analytics tokens" against per-hour and per-day buckets, and a report over a wide
+ * date range costs more tokens than a narrow one. Exhaustion arrives as gRPC code 8
+ * (RESOURCE_EXHAUSTED) or HTTP 429 depending on the transport, and it is transient — the hourly
+ * bucket refills on the hour — so it is worth telling apart from a permission failure, which is not.
+ */
+export declare function isQuotaError(error: unknown): boolean;
+/**
+ * Is this error Google saying the service account cannot see the property?
+ *
+ * The single most common GA4 setup failure, and the one whose raw message is least helpful: creating
+ * the service account and enabling the Data API are not enough — the service account's email must
+ * ALSO be added as a user on the GA4 property itself, which happens in the Analytics UI rather than
+ * in Cloud Console. Detected so `TestConnection` can say that instead of "PERMISSION_DENIED".
+ */
+export declare function isPermissionError(error: unknown): boolean;

package/dist/GA4Report.js

@@ -0,0 +1,77 @@
+/**
+ * The seam between this connector and Google.
+ *
+ * Everything that talks to the network lives behind {@link GA4ReportPort}, which has exactly one
+ * method. That is not indirection for its own sake: it is what lets the whole fetch loop — window
+ * arithmetic, cursor advance, `(other)`-row detection, record projection, watermark — be exercised
+ * against canned responses with no credential, which is the only verification available to this
+ * connector before a live property exists to point it at.
+ *
+ * The types below are the subset of the v1beta `runReport` request/response this connector uses,
+ * declared locally rather than imported from the Google client. Two reasons: the generated protobuf
+ * types make everything optional and nullable, which pushes a `?? ''` onto every field access at the
+ * call site; and a test fake should not have to construct a protobuf.
+ */
+/**
+ * The live port, over `@google-analytics/data`'s `BetaAnalyticsDataClient`.
+ *
+ * The client is imported lazily and constructed once per port instance. Lazy because the Google
+ * client drags in `google-gax` and its gRPC stack — a substantial import that a test run, a
+ * `TestConnection` against a misconfigured credential, or an MJAPI boot that never syncs GA4 should
+ * not pay for. Once per instance because the client caches its OAuth token: rebuilding it per request
+ * would mint a fresh JWT and round-trip Google's token endpoint on every page of every window.
+ */
+export class DefaultGA4ReportPort {
+    constructor(clientEmail, privateKey) {
+        this.clientEmail = clientEmail;
+        this.privateKey = privateKey;
+        this.client = null;
+    }
+    async RunReport(request) {
+        const client = await this.Client();
+        const result = await client.runReport(request);
+        // The Google client returns [response, request, callOptions]; only the first is data.
+        return (result[0] ?? {});
+    }
+    async Client() {
+        if (this.client)
+            return this.client;
+        const mod = await import('@google-analytics/data');
+        const Ctor = mod.BetaAnalyticsDataClient;
+        this.client = new Ctor({
+            credentials: { client_email: this.clientEmail, private_key: this.privateKey },
+        });
+        return this.client;
+    }
+}
+/**
+ * Is this error Google's rate limiter?
+ *
+ * GA4 meters by "analytics tokens" against per-hour and per-day buckets, and a report over a wide
+ * date range costs more tokens than a narrow one. Exhaustion arrives as gRPC code 8
+ * (RESOURCE_EXHAUSTED) or HTTP 429 depending on the transport, and it is transient — the hourly
+ * bucket refills on the hour — so it is worth telling apart from a permission failure, which is not.
+ */
+export function isQuotaError(error) {
+    const code = error?.code;
+    if (code === 8 || code === 429)
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /RESOURCE_EXHAUSTED|quota|rate limit|429/i.test(message);
+}
+/**
+ * Is this error Google saying the service account cannot see the property?
+ *
+ * The single most common GA4 setup failure, and the one whose raw message is least helpful: creating
+ * the service account and enabling the Data API are not enough — the service account's email must
+ * ALSO be added as a user on the GA4 property itself, which happens in the Analytics UI rather than
+ * in Cloud Console. Detected so `TestConnection` can say that instead of "PERMISSION_DENIED".
+ */
+export function isPermissionError(error) {
+    const code = error?.code;
+    if (code === 7 || code === 403)
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /PERMISSION_DENIED|403|caller does not have permission|User does not have sufficient permissions/i.test(message);
+}
+//# sourceMappingURL=GA4Report.js.map

package/dist/GA4Report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GA4Report.js","sourceRoot":"","sources":["../src/GA4Report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoDH;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAoB;IAG7B,YACqB,WAAmB,EACnB,UAAkB;QADlB,gBAAW,GAAX,WAAW,CAAQ;QACnB,eAAU,GAAV,UAAU,CAAQ;QAJ/B,WAAM,GAA+D,IAAI,CAAC;IAK/E,CAAC;IAEG,KAAK,CAAC,SAAS,CAAC,OAA4B;QAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC/C,sFAAsF;QACtF,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAyB,CAAC;IACrD,CAAC;IAEO,KAAK,CAAC,MAAM;QAChB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QACpC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,GAAG,CAAC,uBAAuB,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,IAAI,CAAC;YACnB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE;SAChF,CAAmE,CAAC;QACrE,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;CACJ;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACvC,MAAM,IAAI,GAAI,KAA4B,EAAE,IAAI,CAAC;IACjD,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,0CAA0C,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC5C,MAAM,IAAI,GAAI,KAA4B,EAAE,IAAI,CAAC;IACjD,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,kGAAkG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC5H,CAAC"}

package/dist/GA4Rows.d.ts

@@ -0,0 +1,63 @@
+import type { ExternalRecord } from '@memberjunction/integration-engine';
+import type { CatalogObject } from './GA4Objects.js';
+import type { GA4Row } from './GA4Report.js';
+/**
+ * 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 declare const MAX_EXTERNAL_ID_LENGTH = 700;
+/** GA4's sentinel for rows collapsed together once a dimension exceeds its cardinality limit. */
+export declare 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 declare function buildExternalID(keyValues: string[]): string;
+/**
+ * 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 declare function parseGA4Date(value: string): string | null;
+/**
+ * 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 declare function parseMetric(value: string | null | undefined): number | null;
+export interface ProjectedRow {
+    Record: ExternalRecord;
+    /** True when any dimension of this row is GA4's `(other)` aggregate. */
+    IsOtherRow: boolean;
+}
+/**
+ * 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 declare function projectRow(obj: CatalogObject, row: GA4Row, propertyId: string): ProjectedRow | null;