@useairfoil/producer-google-analytics 0.0.1 → 0.0.3

package/src/demo/index.ts

@@ -0,0 +1,44 @@
+import { ConnectorApp, Demo, RuntimeConfig } from "@useairfoil/connector-kit";
+import { Command } from "effect/cli";
+
+import {
+  DailyOverviewSchema,
+  DeviceSchema,
+  EcommerceItemSchema,
+  EventSchema,
+  LandingPageSchema,
+  LocationSchema,
+  PageSchema,
+  TrafficSourceSchema,
+  UserAcquisitionSchema,
+} from "../schemas/reports";
+import { dayRows } from "./reports";
+
+export const demo = Demo.define({
+  name: "producer-google-analytics",
+  setup: { tables: [], rows: () => ({}) },
+  group: {
+    tables: [
+      Demo.table({ name: "daily_overview", rowSchema: DailyOverviewSchema, version: "version" }),
+      Demo.table({ name: "traffic_sources", rowSchema: TrafficSourceSchema, version: "version" }),
+      Demo.table({
+        name: "user_acquisition",
+        rowSchema: UserAcquisitionSchema,
+        version: "version",
+      }),
+      Demo.table({ name: "pages", rowSchema: PageSchema, version: "version" }),
+      Demo.table({ name: "landing_pages", rowSchema: LandingPageSchema, version: "version" }),
+      Demo.table({ name: "events", rowSchema: EventSchema, version: "version" }),
+      Demo.table({ name: "locations", rowSchema: LocationSchema, version: "version" }),
+      Demo.table({ name: "devices", rowSchema: DeviceSchema, version: "version" }),
+      Demo.table({ name: "ecommerce_items", rowSchema: EcommerceItemSchema, version: "version" }),
+    ],
+    rows: dayRows,
+    // Two years of days, the same as the default GA_START_DATE.
+    count: 730,
+  },
+});
+
+export const demoCommand = ConnectorApp.makeDemoCommand(demo).pipe(
+  Command.provide(RuntimeConfig.layerHosted()),
+);

package/src/demo/reports.ts

@@ -0,0 +1,251 @@
+import type { Demo } from "@useairfoil/connector-kit";
+
+import { DateTime } from "effect";
+
+import {
+  currency,
+  day,
+  devices,
+  host,
+  items,
+  locations,
+  money,
+  pages,
+  propertyId,
+  type Rows,
+  sources,
+  split,
+} from "./shared";
+
+/** One group is one day of reports, counting back from yesterday. */
+export const dayRows = (index: number, { faker, now }: Demo.DemoContext): Rows => {
+  const date = DateTime.formatIsoDateUtc(
+    DateTime.fromDateUnsafe(new Date(now.getTime() - (index + 1) * day)),
+  );
+
+  const id = (...dimensions: ReadonlyArray<string>) =>
+    JSON.stringify([propertyId, date, ...dimensions]);
+
+  const base = { version: now, property_id: propertyId, date };
+
+  // Traffic grows over time and dips at the weekend.
+  const weekday = new Date(`${date}T00:00:00Z`).getUTCDay();
+  const weekend = weekday === 0 || weekday === 6 ? 0.75 : 1;
+  const growth = Math.max(0.4, 1 - index / 900);
+
+  const sessions = Math.round(
+    4200 * weekend * growth * faker.number.float({ min: 0.85, max: 1.15 }),
+  );
+
+  const engaged = Math.round(sessions * faker.number.float({ min: 0.55, max: 0.68 }));
+  const activeUsers = Math.round(sessions * 0.78);
+  const newUsers = Math.round(activeUsers * faker.number.float({ min: 0.42, max: 0.55 }));
+  const views = Math.round(sessions * faker.number.float({ min: 3.2, max: 4.4 }));
+  const purchases = Math.round(sessions * faker.number.float({ min: 0.018, max: 0.028 }));
+  const revenue = money(purchases * faker.number.float({ min: 58, max: 74 }));
+  const engagement = money(engaged * faker.number.float({ min: 95, max: 140 }));
+
+  const bySource = split(
+    sessions,
+    sources.map((source) => source[4]),
+  );
+
+  const byNewSource = split(
+    newUsers,
+    sources.map((source) => source[4]),
+  );
+
+  const purchasesBySource = split(
+    purchases,
+    sources.map((source) => source[4]),
+  );
+
+  const share = (part: number, whole: number) => (whole === 0 ? 0 : part / whole);
+
+  const eventCounts: ReadonlyArray<readonly [string, number, number]> = [
+    ["page_view", views, activeUsers],
+    ["session_start", sessions, activeUsers],
+    ["first_visit", newUsers, newUsers],
+    ["user_engagement", engaged * 3, Math.round(activeUsers * 0.7)],
+    ["scroll", Math.round(views * 0.45), Math.round(activeUsers * 0.5)],
+    ["view_item", Math.round(views * 0.3), Math.round(activeUsers * 0.4)],
+    ["add_to_cart", Math.round(sessions * 0.08), Math.round(activeUsers * 0.07)],
+    ["begin_checkout", Math.round(sessions * 0.04), Math.round(activeUsers * 0.035)],
+    ["purchase", purchases, purchases],
+  ];
+
+  // Cheaper items sell more units.
+  const itemUnits = split(
+    purchases + Math.round(purchases * 0.4),
+    items.map((item) => 10 - item[3] / 10),
+  );
+
+  const viewsByPage = split(
+    views,
+    pages.map((page) => page[2]),
+  );
+
+  const sessionsByLanding = split(sessions, [42, 16, 14, 10, 10, 8]);
+
+  const sessionsByLocation = split(
+    sessions,
+    locations.map((location) => location[3]),
+  );
+
+  const sessionsByDevice = split(
+    sessions,
+    devices.map((device) => device[4]),
+  );
+
+  return {
+    daily_overview: [
+      {
+        id: id(),
+        ...base,
+        active_users: BigInt(activeUsers),
+        new_users: BigInt(newUsers),
+        total_users: BigInt(Math.round(activeUsers * 1.08)),
+        sessions: BigInt(sessions),
+        engaged_sessions: BigInt(engaged),
+        screen_page_views: BigInt(views),
+        event_count: BigInt(eventCounts.reduce((sum, [, count]) => sum + count, 0)),
+        key_events: purchases,
+        total_revenue: revenue,
+        user_engagement_duration: engagement,
+        currency_code: currency,
+      },
+    ],
+    traffic_sources: sources.map(([source, medium, campaign, channel], s) => {
+      const part = bySource[s] ?? 0;
+
+      return {
+        id: id(source, medium, campaign, channel),
+        ...base,
+        session_source: source,
+        session_medium: medium,
+        session_campaign_name: campaign,
+        session_default_channel_group: channel,
+        sessions: BigInt(part),
+        engaged_sessions: BigInt(Math.round(part * share(engaged, sessions))),
+        active_users: BigInt(Math.round(part * share(activeUsers, sessions))),
+        new_users: BigInt(Math.round(part * share(newUsers, sessions))),
+        screen_page_views: BigInt(Math.round(part * share(views, sessions))),
+        event_count: BigInt(Math.round(part * share(views, sessions) * 2.6)),
+        key_events: purchasesBySource[s] ?? 0,
+        total_revenue: money(revenue * share(purchasesBySource[s] ?? 0, purchases)),
+        user_engagement_duration: money(engagement * share(part, sessions)),
+        currency_code: currency,
+      };
+    }),
+    user_acquisition: sources.map(([source, medium, campaign, channel], s) => ({
+      id: id(source, medium, campaign, channel),
+      ...base,
+      first_user_source: source,
+      first_user_medium: medium,
+      first_user_campaign_name: campaign,
+      first_user_default_channel_group: channel,
+      new_users: BigInt(byNewSource[s] ?? 0),
+      active_users: BigInt(Math.round((byNewSource[s] ?? 0) * 1.6)),
+      sessions: BigInt(Math.round((byNewSource[s] ?? 0) * 1.9)),
+      engaged_sessions: BigInt(Math.round((byNewSource[s] ?? 0) * 1.1)),
+      key_events: Math.round((purchasesBySource[s] ?? 0) * 0.4),
+      total_revenue: money(revenue * 0.4 * share(purchasesBySource[s] ?? 0, purchases)),
+      currency_code: currency,
+    })),
+    pages: pages.map(([path, title, weight], p) => {
+      const part = viewsByPage[p] ?? 0;
+
+      return {
+        id: id(host, path, title),
+        ...base,
+        host_name: host,
+        page_path: path,
+        page_title: title,
+        screen_page_views: BigInt(part),
+        active_users: BigInt(Math.round(part * 0.62)),
+        event_count: BigInt(Math.round(part * 2.4)),
+        key_events: path === "/checkout" ? purchases : 0,
+        user_engagement_duration: money(engagement * (weight / 100)),
+      };
+    }),
+    landing_pages: pages.slice(0, 6).map(([path], l) => {
+      const part = sessionsByLanding[l] ?? 0;
+
+      return {
+        id: id(path),
+        ...base,
+        landing_page: path,
+        sessions: BigInt(part),
+        engaged_sessions: BigInt(Math.round(part * share(engaged, sessions))),
+        active_users: BigInt(Math.round(part * 0.8)),
+        new_users: BigInt(Math.round(part * share(newUsers, sessions))),
+        key_events: Math.round(purchases * share(part, sessions)),
+        total_revenue: money(revenue * share(part, sessions)),
+        currency_code: currency,
+      };
+    }),
+    events: eventCounts.map(([name, count, users]) => ({
+      id: id(name),
+      ...base,
+      event_name: name,
+      event_count: BigInt(count),
+      total_users: BigInt(users),
+      event_value: name === "purchase" ? revenue : 0,
+      key_events: name === "purchase" ? purchases : 0,
+    })),
+    locations: locations.map(([country, region, city], l) => {
+      const part = sessionsByLocation[l] ?? 0;
+
+      return {
+        id: id(country, region, city),
+        ...base,
+        country,
+        region,
+        city,
+        active_users: BigInt(Math.round(part * 0.78)),
+        new_users: BigInt(Math.round(part * share(newUsers, sessions))),
+        sessions: BigInt(part),
+        engaged_sessions: BigInt(Math.round(part * share(engaged, sessions))),
+        key_events: Math.round(purchases * share(part, sessions)),
+        total_revenue: money(revenue * share(part, sessions)),
+        currency_code: currency,
+      };
+    }),
+    devices: devices.map(([category, platform, os, browser], d) => {
+      const part = sessionsByDevice[d] ?? 0;
+
+      return {
+        id: id(category, platform, os, browser),
+        ...base,
+        device_category: category,
+        platform,
+        operating_system: os,
+        browser,
+        active_users: BigInt(Math.round(part * 0.78)),
+        new_users: BigInt(Math.round(part * share(newUsers, sessions))),
+        sessions: BigInt(part),
+        engaged_sessions: BigInt(Math.round(part * share(engaged, sessions))),
+        screen_page_views: BigInt(Math.round(part * share(views, sessions))),
+        key_events: Math.round(purchases * share(part, sessions)),
+      };
+    }),
+    ecommerce_items: items.map(([itemId, name, category, price], i) => {
+      const bought = itemUnits[i] ?? 0;
+      const added = Math.round(bought * faker.number.float({ min: 3, max: 5 }));
+
+      return {
+        id: id(itemId, name, "Acme", category),
+        ...base,
+        item_id: itemId,
+        item_name: name,
+        item_brand: "Acme",
+        item_category: category,
+        items_viewed: BigInt(Math.round(added * faker.number.float({ min: 6, max: 9 }))),
+        items_added_to_cart: BigInt(added),
+        items_purchased: BigInt(bought),
+        item_revenue: money(bought * price),
+        currency_code: currency,
+      };
+    }),
+  };
+};

package/src/demo/shared.ts

@@ -0,0 +1,98 @@
+import { Duration } from "effect";
+
+import type {
+  DailyOverview,
+  Device,
+  EcommerceItem,
+  Event,
+  LandingPage,
+  Location,
+  Page,
+  TrafficSource,
+  UserAcquisition,
+} from "../schemas/reports";
+
+export const day = Duration.toMillis(Duration.days(1));
+export const propertyId = "123456789";
+export const host = "shop.acme.example.com";
+export const currency = "USD";
+
+// [source, medium, campaign, channel group, share of sessions]
+export const sources = [
+  ["google", "organic", "(organic)", "Organic Search", 34],
+  ["(direct)", "(none)", "(direct)", "Direct", 22],
+  ["google", "cpc", "brand_search", "Paid Search", 14],
+  ["facebook", "paid_social", "fall_sale", "Paid Social", 9],
+  ["newsletter", "email", "weekly_digest", "Email", 8],
+  ["bing", "organic", "(organic)", "Organic Search", 5],
+  ["instagram.com", "referral", "(referral)", "Organic Social", 5],
+  ["partner.example.com", "referral", "(referral)", "Referral", 3],
+] as const;
+
+export const pages = [
+  ["/", "Acme - Everyday goods", 30],
+  ["/collections/new", "New arrivals - Acme", 14],
+  ["/collections/sale", "Sale - Acme", 12],
+  ["/products/classic-tee", "Classic Tee - Acme", 9],
+  ["/products/everyday-hoodie", "Everyday Hoodie - Acme", 8],
+  ["/products/water-bottle", "Insulated Water Bottle - Acme", 6],
+  ["/cart", "Your cart - Acme", 8],
+  ["/checkout", "Checkout - Acme", 5],
+  ["/blog/how-we-source-cotton", "How we source our cotton - Acme", 4],
+  ["/pages/shipping", "Shipping - Acme", 4],
+] as const;
+
+export const locations = [
+  ["United States", "California", "Los Angeles", 14],
+  ["United States", "New York", "New York", 12],
+  ["United States", "Texas", "Austin", 7],
+  ["United States", "Illinois", "Chicago", 6],
+  ["United Kingdom", "England", "London", 9],
+  ["Canada", "Ontario", "Toronto", 6],
+  ["Germany", "Berlin", "Berlin", 5],
+  ["Australia", "New South Wales", "Sydney", 4],
+  ["United States", "(not set)", "(not set)", 3],
+] as const;
+
+export const devices = [
+  ["mobile", "web", "iOS", "Safari", 30],
+  ["mobile", "web", "Android", "Chrome", 22],
+  ["desktop", "web", "Windows", "Chrome", 18],
+  ["desktop", "web", "Macintosh", "Chrome", 12],
+  ["desktop", "web", "Macintosh", "Safari", 10],
+  ["tablet", "web", "iOS", "Safari", 5],
+  ["desktop", "web", "Windows", "Edge", 3],
+] as const;
+
+export const items = [
+  ["SKU-TEE", "Classic Cotton Tee", "Apparel", 28],
+  ["SKU-HOODIE", "Everyday Hoodie", "Apparel", 64],
+  ["SKU-SHIRT", "Linen Button Shirt", "Apparel", 72],
+  ["SKU-BEANIE", "Wool Beanie", "Accessories", 26],
+  ["SKU-TOTE", "Canvas Tote Bag", "Accessories", 22],
+  ["SKU-MUG", "Stoneware Mug", "Home", 18],
+  ["SKU-BOTTLE", "Insulated Water Bottle", "Home", 32],
+] as const;
+
+/** Splits a total by weights into whole numbers that add up to it. */
+export const split = (total: number, weights: ReadonlyArray<number>) => {
+  const sum = weights.reduce((a, b) => a + b, 0);
+  const parts = weights.map((weight) => Math.floor((total * weight) / sum));
+  parts[0] = (parts[0] ?? 0) + total - parts.reduce((a, b) => a + b, 0);
+
+  return parts;
+};
+
+export const money = (value: number) => Math.round(value * 100) / 100;
+
+export type Rows = {
+  readonly daily_overview: Array<DailyOverview>;
+  readonly traffic_sources: Array<TrafficSource>;
+  readonly user_acquisition: Array<UserAcquisition>;
+  readonly pages: Array<Page>;
+  readonly landing_pages: Array<LandingPage>;
+  readonly events: Array<Event>;
+  readonly locations: Array<Location>;
+  readonly devices: Array<Device>;
+  readonly ecommerce_items: Array<EcommerceItem>;
+};

package/src/index.ts

@@ -0,0 +1,26 @@
+export * as GoogleAnalyticsAuth from "./client/auth";
+export * as GoogleAnalyticsClient from "./client/client";
+export * as GoogleAnalyticsConnector from "./connector";
+export { manifest } from "./manifest";
+export type {
+  DailyOverview,
+  Device,
+  EcommerceItem,
+  Event,
+  LandingPage,
+  Location,
+  Page,
+  TrafficSource,
+  UserAcquisition,
+} from "./schemas/reports";
+export {
+  DailyOverviewSchema,
+  DeviceSchema,
+  EcommerceItemSchema,
+  EventSchema,
+  LandingPageSchema,
+  LocationSchema,
+  PageSchema,
+  TrafficSourceSchema,
+  UserAcquisitionSchema,
+} from "./schemas/reports";

package/src/main.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import { Command } from "effect/cli";
+import { FetchHttpClient } from "effect/http";
+
+import packageJson from "../package.json";
+import { createTableCommand, setupCommand } from "./create-table";
+import { demoCommand } from "./demo";
+import { sandboxCommand } from "./sandbox";
+import { startCommand } from "./start";
+
+const BootstrapLayer = Layer.mergeAll(FetchHttpClient.layer, NodeServices.layer);
+
+const program = Command.make("producer-google-analytics", {}, () => Effect.void).pipe(
+  Command.withSubcommands([
+    setupCommand,
+    startCommand,
+    sandboxCommand,
+    createTableCommand,
+    demoCommand,
+  ]),
+);
+
+const cli = Command.run(program, { version: packageJson.version });
+
+NodeRuntime.runMain(cli.pipe(Effect.provide(BootstrapLayer), Effect.scoped));

package/src/manifest.ts

@@ -0,0 +1,50 @@
+import * as Manifest from "@useairfoil/connector-kit/manifest";
+
+export const GoogleAnalyticsConfigDef = Manifest.defineConfig({
+  propertyId: Manifest.string({
+    runtimeKey: "GA_PROPERTY_ID",
+    description: "Numeric ID of the GA4 property, from Admin > Property details.",
+  }),
+  clientEmail: Manifest.string({
+    runtimeKey: "GA_CLIENT_EMAIL",
+    description: "`client_email` from the service account's JSON key.",
+  }),
+  privateKey: Manifest.secret({
+    runtimeKey: "GA_PRIVATE_KEY",
+    description: "`private_key` from the service account's JSON key.",
+  }),
+  startDate: Manifest.optional(
+    Manifest.string({
+      runtimeKey: "GA_START_DATE",
+      description: "First day to backfill, as YYYY-MM-DD. Defaults to 2 years back.",
+    }),
+  ),
+  lookbackDays: Manifest.number({
+    runtimeKey: "GA_LOOKBACK_DAYS",
+    description: "Days read again on each run, since Google keeps updating recent data.",
+    integer: true,
+    minimum: 1,
+    default: 14,
+  }),
+});
+
+export type GoogleAnalyticsConfig = Manifest.ConfigValuesOf<typeof GoogleAnalyticsConfigDef>;
+
+const capabilities = ["backfill", "changes"] as const;
+
+export const manifest = Manifest.define({
+  name: "producer-google-analytics",
+  title: "Google Analytics",
+  config: GoogleAnalyticsConfigDef.spec,
+  resources: [
+    { name: "daily_overview", capabilities },
+    { name: "traffic_sources", capabilities },
+    { name: "user_acquisition", capabilities },
+    { name: "pages", capabilities },
+    { name: "landing_pages", capabilities },
+    { name: "events", capabilities },
+    { name: "locations", capabilities },
+    { name: "devices", capabilities },
+    { name: "ecommerce_items", capabilities },
+  ],
+});

package/src/resources/reports/read.ts

@@ -0,0 +1,104 @@
+import { ConnectorError } from "@useairfoil/connector-kit";
+import { DateTime, Effect, Option, Schema } from "effect";
+
+import type { GoogleAnalyticsClientService } from "../../client/client";
+import type { RunReportResponse } from "../../schemas/api";
+import type { ReportSpec } from "./spec";
+
+import { isoDay } from "../../schemas/shared";
+
+// The API returns at most 250,000 rows a request. Smaller pages keep memory low.
+const pageSize = 100_000;
+
+export type ReportPage<Row> = {
+  readonly rows: ReadonlyArray<Row>;
+  /** Offset of the next page of the same day. */
+  readonly next: Option.Option<number>;
+};
+
+type ReportRow = NonNullable<RunReportResponse["rows"]>[number];
+
+/** `[column, apiName]` pairs, in request order. */
+const pairs = (columns: Readonly<Record<string, string | undefined>>) =>
+  Object.entries(columns).flatMap(([column, name]) =>
+    name === undefined ? [] : [[column, name] as const],
+  );
+
+const valuesByName = (
+  headers: ReadonlyArray<{ readonly name: string }>,
+  values: ReadonlyArray<{ readonly value: string }>,
+) => new Map(headers.map((header, index) => [header.name, values[index]?.value]));
+
+/** Logs the response flags that mean some data is hidden or estimated. */
+const warnDataLoss = (name: string, day: string, metadata: RunReportResponse["metadata"]) => {
+  const flags = {
+    otherRow: metadata.dataLossFromOtherRow === true,
+    thresholded: metadata.subjectToThresholding === true,
+    sampled: (metadata.samplingMetadatas?.length ?? 0) > 0,
+    truncated: (metadata.dataTruncationReasons?.length ?? 0) > 0,
+  };
+  return Object.values(flags).some(Boolean)
+    ? Effect.logWarning("Google Analytics report is incomplete").pipe(
+        Effect.annotateLogs({ report: name, day, ...flags }),
+      )
+    : Effect.void;
+};
+
+export const readDay = <Row extends object>(
+  client: GoogleAnalyticsClientService,
+  propertyId: string,
+  spec: ReportSpec<Row>,
+  options: { readonly day: string; readonly offset: number; readonly limit?: number },
+): Effect.Effect<ReportPage<Row>, ConnectorError> =>
+  Effect.gen(function* () {
+    const dimensions = pairs(spec.dimensions);
+    const metrics = pairs(spec.metrics);
+    const columns = [...dimensions, ...metrics];
+    const response = yield* client.runReport(spec.name, {
+      dimensions: ["date", ...dimensions.map(([, name]) => name)],
+      metrics: metrics.map(([, name]) => name),
+      startDate: options.day,
+      endDate: options.day,
+      limit: options.limit ?? pageSize,
+      offset: options.offset,
+    });
+    yield* warnDataLoss(spec.name, options.day, response.metadata);
+    const version = yield* DateTime.nowAsDate;
+    const decodeRow = Schema.decodeUnknownEffect(spec.rowSchema);
+
+    const toRow = (row: ReportRow) => {
+      const values = new Map([
+        ...valuesByName(response.dimensionHeaders, row.dimensionValues),
+        ...valuesByName(response.metricHeaders, row.metricValues),
+      ]);
+      const date = values.get("date") ?? "";
+      return decodeRow({
+        id: JSON.stringify([
+          propertyId,
+          isoDay(date),
+          ...dimensions.map(([, name]) => values.get(name)),
+        ]),
+        version,
+        property_id: propertyId,
+        date,
+        // Tables without revenue leave it out.
+        currency_code: response.metadata.currencyCode,
+        ...Object.fromEntries(columns.map(([column, name]) => [column, values.get(name)])),
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ConnectorError({
+              message: `Unexpected Google Analytics row in ${spec.name} for ${options.day}`,
+              cause,
+            }),
+        ),
+      );
+    };
+
+    const rows = yield* Effect.forEach(response.rows ?? [], toRow);
+    const read = options.offset + rows.length;
+    return {
+      rows,
+      next: rows.length > 0 && read < (response.rowCount ?? 0) ? Option.some(read) : Option.none(),
+    };
+  });

package/src/resources/reports/resource.ts

@@ -0,0 +1,31 @@
+import type { ConnectorError, Identified } from "@useairfoil/connector-kit";
+import type { Effect, Schema } from "effect";
+
+import type { GoogleAnalyticsClientService } from "../../client/client";
+import type { GoogleAnalyticsConfig } from "../../manifest";
+import type { ReportSpec } from "./spec";
+
+import { reportBackfill, reportChanges, reportCheck } from "./sources";
+
+/** What `Resource.entity` takes for a report. */
+export type ReportEntity<Row extends object> = {
+  readonly name: string;
+  readonly rowSchema: Schema.Decoder<Row> & Identified<"id">;
+  readonly version: "version";
+  readonly check: Effect.Effect<void, ConnectorError>;
+  readonly backfill: ReturnType<typeof reportBackfill<Row>>;
+  readonly changes: ReturnType<typeof reportChanges<Row>>;
+};
+
+export const reportEntity = <Row extends object>(
+  client: GoogleAnalyticsClientService,
+  config: GoogleAnalyticsConfig,
+  spec: ReportSpec<Row>,
+): ReportEntity<Row> => ({
+  name: spec.name,
+  rowSchema: spec.rowSchema,
+  version: "version",
+  check: reportCheck(client, config, spec),
+  backfill: reportBackfill(client, config, spec),
+  changes: reportChanges(client, config, spec),
+});