@coursebuilder/analytics 1.1.0

package/dist/engine.js

@@ -0,0 +1,350 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/catalog.ts
+var catalog = {
+  summary: {
+    name: "summary",
+    description: "Revenue overview: total, purchase count, AOV",
+    category: "revenue",
+    provider: "database",
+    fn: "getRevenueSummary"
+  },
+  "revenue/daily": {
+    name: "revenue/daily",
+    description: "Revenue and purchase count per day",
+    category: "revenue",
+    provider: "database",
+    fn: "getRevenueByDay"
+  },
+  "revenue/products": {
+    name: "revenue/products",
+    description: "Revenue grouped by product",
+    category: "revenue",
+    provider: "database",
+    fn: "getRevenueByProduct"
+  },
+  "revenue/countries": {
+    name: "revenue/countries",
+    description: "Revenue grouped by country",
+    category: "revenue",
+    provider: "database",
+    fn: "getRevenueByCountry"
+  },
+  "purchases/recent": {
+    name: "purchases/recent",
+    description: "Last N purchases",
+    category: "revenue",
+    provider: "database",
+    fn: "getRecentPurchases"
+  },
+  attribution: {
+    name: "attribution",
+    description: "Attribution event counts by type",
+    category: "attribution",
+    provider: "database",
+    fn: "getAttributionSummary"
+  },
+  "attribution/shortlinks": {
+    name: "attribution/shortlinks",
+    description: "Per-shortlink click performance",
+    category: "attribution",
+    provider: "database",
+    fn: "getShortlinkPerformance"
+  },
+  "attribution/sources": {
+    name: "attribution/sources",
+    description: "Revenue by first-touch source/medium/campaign",
+    category: "attribution",
+    provider: "database",
+    fn: "getRevenueBySource"
+  },
+  "attribution/funnel": {
+    name: "attribution/funnel",
+    description: "Signup \u2192 purchase conversion funnel",
+    category: "attribution",
+    provider: "database",
+    fn: "getConversionFunnel"
+  },
+  "attribution/content": {
+    name: "attribution/content",
+    description: "Content consumed by purchasers",
+    category: "attribution",
+    provider: "database",
+    fn: "getContentPurchaseCorrelation"
+  },
+  "attribution/coverage": {
+    name: "attribution/coverage",
+    description: "Attributed vs dark revenue",
+    category: "attribution",
+    provider: "database",
+    fn: "getAttributedRevenueSummary"
+  },
+  traffic: {
+    name: "traffic",
+    description: "GA4 traffic overview",
+    category: "traffic",
+    provider: "ga4",
+    fn: "getTrafficOverview"
+  },
+  "traffic/daily": {
+    name: "traffic/daily",
+    description: "GA4 daily sessions",
+    category: "traffic",
+    provider: "ga4",
+    fn: "getSessionsByDay"
+  },
+  "traffic/pages": {
+    name: "traffic/pages",
+    description: "Top pages by pageviews",
+    category: "traffic",
+    provider: "ga4",
+    fn: "getTopPages"
+  },
+  "traffic/sources": {
+    name: "traffic/sources",
+    description: "Traffic sources",
+    category: "traffic",
+    provider: "ga4",
+    fn: "getTrafficSources"
+  },
+  youtube: {
+    name: "youtube",
+    description: "Channel overview (\u224848h lag)",
+    category: "youtube",
+    provider: "youtube",
+    fn: "getChannelOverview",
+    unavailableFix: "Complete OAuth at /api/analytics/youtube-auth"
+  },
+  "youtube/videos": {
+    name: "youtube/videos",
+    description: "Per-video performance (\u224848h lag)",
+    category: "youtube",
+    provider: "youtube",
+    fn: "getVideoPerformance",
+    unavailableFix: "Complete OAuth at /api/analytics/youtube-auth"
+  },
+  "youtube/daily": {
+    name: "youtube/daily",
+    description: "Daily views + watch minutes (\u224848h lag)",
+    category: "youtube",
+    provider: "youtube",
+    fn: "getChannelTimeseries",
+    unavailableFix: "Complete OAuth at /api/analytics/youtube-auth"
+  },
+  "youtube/sources": {
+    name: "youtube/sources",
+    description: "YouTube traffic sources (\u224848h lag)",
+    category: "youtube",
+    provider: "youtube",
+    fn: "getYouTubeTrafficSources",
+    unavailableFix: "Complete OAuth at /api/analytics/youtube-auth"
+  },
+  "correlation/traffic-revenue": {
+    name: "correlation/traffic-revenue",
+    description: "GA4 sessions + revenue by day",
+    category: "correlation",
+    provider: "derived",
+    fn: "getTrafficRevenueCorrelation"
+  },
+  "correlation/youtube-revenue": {
+    name: "correlation/youtube-revenue",
+    description: "YouTube (\u224848h lag) + GA4 + revenue overlay",
+    category: "correlation",
+    provider: "derived",
+    fn: "getYouTubeRevenueCorrelation"
+  },
+  surveys: {
+    name: "surveys",
+    description: "Survey overview: total surveys, responses, respondents",
+    category: "survey",
+    provider: "survey",
+    fn: "getSurveySummary"
+  },
+  "surveys/list": {
+    name: "surveys/list",
+    description: "All surveys with response counts",
+    category: "survey",
+    provider: "survey",
+    fn: "getSurveyList"
+  },
+  "surveys/daily": {
+    name: "surveys/daily",
+    description: "Daily survey response volume",
+    category: "survey",
+    provider: "survey",
+    fn: "getSurveyResponsesByDay"
+  },
+  "surveys/questions": {
+    name: "surveys/questions",
+    description: "Top questions by response count with answer distribution",
+    category: "survey",
+    provider: "survey",
+    fn: "getSurveyQuestionBreakdown"
+  },
+  "surveys/responses": {
+    name: "surveys/responses",
+    description: "Individual survey responses as flat rows (multi-choice and open-ended)",
+    category: "survey",
+    provider: "survey",
+    fn: "getSurveyResponses"
+  },
+  "attribution/email-campaigns": {
+    name: "attribution/email-campaigns",
+    description: "Kit email broadcasts \u2192 shortlink clicks \u2192 signups \u2192 purchases \u2192 revenue per campaign",
+    category: "attribution",
+    provider: "newsletter",
+    fn: "getEmailCampaignAttribution"
+  },
+  "correlation/survey-revenue": {
+    name: "correlation/survey-revenue",
+    description: "Survey respondents \u2192 purchase conversion by question/answer",
+    category: "correlation",
+    provider: "derived",
+    fn: "getSurveyRevenueCorrelation"
+  }
+};
+
+// src/engine.ts
+function toGA4Range(range) {
+  if (range === "all")
+    return "90d";
+  return range;
+}
+__name(toGA4Range, "toGA4Range");
+function toYouTubeRange(range) {
+  if (range === "all")
+    return "90d";
+  return range;
+}
+__name(toYouTubeRange, "toYouTubeRange");
+async function invokeSurface(providers, surface, range, limit) {
+  const entry = catalog[surface];
+  const provider = providers[entry.provider];
+  if (!provider) {
+    return null;
+  }
+  if (typeof provider[entry.fn] !== "function") {
+    return null;
+  }
+  switch (surface) {
+    case "purchases/recent": {
+      const fn = provider[entry.fn];
+      return fn(limit);
+    }
+    case "youtube": {
+      const fn = provider[entry.fn];
+      return fn();
+    }
+    case "youtube/videos":
+    case "youtube/daily":
+    case "youtube/sources": {
+      const fn = provider[entry.fn];
+      if (surface === "youtube/videos") {
+        return fn(toYouTubeRange(range), limit);
+      }
+      return fn(toYouTubeRange(range));
+    }
+    case "traffic":
+    case "traffic/daily":
+    case "traffic/pages":
+    case "traffic/sources": {
+      const fn = provider[entry.fn];
+      if (surface === "traffic/pages" || surface === "traffic/sources") {
+        return fn(toGA4Range(range), limit);
+      }
+      return fn(toGA4Range(range));
+    }
+    case "surveys":
+    case "surveys/list":
+    case "surveys/daily": {
+      const fn = provider[entry.fn];
+      return fn(range);
+    }
+    case "attribution/email-campaigns": {
+      const fn = provider[entry.fn];
+      return fn(range, limit);
+    }
+    case "surveys/questions":
+    case "surveys/responses": {
+      const fn = provider[entry.fn];
+      return fn(range, limit);
+    }
+    default: {
+      const fn = provider[entry.fn];
+      if (surface === "attribution/content" || surface === "correlation/survey-revenue") {
+        return fn(range, limit);
+      }
+      return fn(range);
+    }
+  }
+}
+__name(invokeSurface, "invokeSurface");
+function createAnalyticsEngine(providers) {
+  async function query(surface, options) {
+    const range = options?.range ?? "30d";
+    const limit = options?.limit ?? 20;
+    const entry = catalog[surface];
+    const startMs = Date.now();
+    try {
+      const data = await invokeSurface(providers, surface, range, limit);
+      if (data === null) {
+        return {
+          ok: false,
+          surface,
+          error: {
+            message: `${entry.provider} is not available`,
+            code: `${entry.provider.toUpperCase()}_UNAVAILABLE`
+          },
+          fix: entry.unavailableFix ?? "Check provider configuration"
+        };
+      }
+      return {
+        ok: true,
+        surface,
+        range,
+        data,
+        meta: {
+          queryTimeMs: Date.now() - startMs,
+          truncated: Array.isArray(data) && data.length >= limit
+        }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        surface,
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          code: "QUERY_FAILED"
+        },
+        fix: `The ${surface} query failed. Try a different range or check server logs.`
+      };
+    }
+  }
+  __name(query, "query");
+  async function queryMany(surfaces, options) {
+    const results = await Promise.all(surfaces.map(async (surface) => [
+      surface,
+      await query(surface, options)
+    ]));
+    return Object.fromEntries(results);
+  }
+  __name(queryMany, "queryMany");
+  function getCatalog() {
+    return Object.values(catalog).filter((entry) => {
+      const provider = providers[entry.provider];
+      return provider && typeof provider[entry.fn] === "function";
+    });
+  }
+  __name(getCatalog, "getCatalog");
+  return {
+    query,
+    queryMany,
+    getCatalog
+  };
+}
+__name(createAnalyticsEngine, "createAnalyticsEngine");
+export {
+  createAnalyticsEngine
+};
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/catalog.ts","../src/engine.ts"],"sourcesContent":["import type { SurfaceName } from './types'\n\nexport interface SurfaceEntry {\n\tname: SurfaceName\n\tdescription: string\n\tcategory:\n\t\t| 'revenue'\n\t\t| 'attribution'\n\t\t| 'traffic'\n\t\t| 'youtube'\n\t\t| 'correlation'\n\t\t| 'survey'\n\tprovider: 'database' | 'ga4' | 'youtube' | 'derived' | 'newsletter' | 'survey'\n\tfn: string\n\tunavailableFix?: string\n}\n\nexport const catalog: Record<SurfaceName, SurfaceEntry> = {\n\tsummary: {\n\t\tname: 'summary',\n\t\tdescription: 'Revenue overview: total, purchase count, AOV',\n\t\tcategory: 'revenue',\n\t\tprovider: 'database',\n\t\tfn: 'getRevenueSummary',\n\t},\n\t'revenue/daily': {\n\t\tname: 'revenue/daily',\n\t\tdescription: 'Revenue and purchase count per day',\n\t\tcategory: 'revenue',\n\t\tprovider: 'database',\n\t\tfn: 'getRevenueByDay',\n\t},\n\t'revenue/products': {\n\t\tname: 'revenue/products',\n\t\tdescription: 'Revenue grouped by product',\n\t\tcategory: 'revenue',\n\t\tprovider: 'database',\n\t\tfn: 'getRevenueByProduct',\n\t},\n\t'revenue/countries': {\n\t\tname: 'revenue/countries',\n\t\tdescription: 'Revenue grouped by country',\n\t\tcategory: 'revenue',\n\t\tprovider: 'database',\n\t\tfn: 'getRevenueByCountry',\n\t},\n\t'purchases/recent': {\n\t\tname: 'purchases/recent',\n\t\tdescription: 'Last N purchases',\n\t\tcategory: 'revenue',\n\t\tprovider: 'database',\n\t\tfn: 'getRecentPurchases',\n\t},\n\tattribution: {\n\t\tname: 'attribution',\n\t\tdescription: 'Attribution event counts by type',\n\t\tcategory: 'attribution',\n\t\tprovider: 'database',\n\t\tfn: 'getAttributionSummary',\n\t},\n\t'attribution/shortlinks': {\n\t\tname: 'attribution/shortlinks',\n\t\tdescription: 'Per-shortlink click performance',\n\t\tcategory: 'attribution',\n\t\tprovider: 'database',\n\t\tfn: 'getShortlinkPerformance',\n\t},\n\t'attribution/sources': {\n\t\tname: 'attribution/sources',\n\t\tdescription: 'Revenue by first-touch source/medium/campaign',\n\t\tcategory: 'attribution',\n\t\tprovider: 'database',\n\t\tfn: 'getRevenueBySource',\n\t},\n\t'attribution/funnel': {\n\t\tname: 'attribution/funnel',\n\t\tdescription: 'Signup → purchase conversion funnel',\n\t\tcategory: 'attribution',\n\t\tprovider: 'database',\n\t\tfn: 'getConversionFunnel',\n\t},\n\t'attribution/content': {\n\t\tname: 'attribution/content',\n\t\tdescription: 'Content consumed by purchasers',\n\t\tcategory: 'attribution',\n\t\tprovider: 'database',\n\t\tfn: 'getContentPurchaseCorrelation',\n\t},\n\t'attribution/coverage': {\n\t\tname: 'attribution/coverage',\n\t\tdescription: 'Attributed vs dark revenue',\n\t\tcategory: 'attribution',\n\t\tprovider: 'database',\n\t\tfn: 'getAttributedRevenueSummary',\n\t},\n\ttraffic: {\n\t\tname: 'traffic',\n\t\tdescription: 'GA4 traffic overview',\n\t\tcategory: 'traffic',\n\t\tprovider: 'ga4',\n\t\tfn: 'getTrafficOverview',\n\t},\n\t'traffic/daily': {\n\t\tname: 'traffic/daily',\n\t\tdescription: 'GA4 daily sessions',\n\t\tcategory: 'traffic',\n\t\tprovider: 'ga4',\n\t\tfn: 'getSessionsByDay',\n\t},\n\t'traffic/pages': {\n\t\tname: 'traffic/pages',\n\t\tdescription: 'Top pages by pageviews',\n\t\tcategory: 'traffic',\n\t\tprovider: 'ga4',\n\t\tfn: 'getTopPages',\n\t},\n\t'traffic/sources': {\n\t\tname: 'traffic/sources',\n\t\tdescription: 'Traffic sources',\n\t\tcategory: 'traffic',\n\t\tprovider: 'ga4',\n\t\tfn: 'getTrafficSources',\n\t},\n\tyoutube: {\n\t\tname: 'youtube',\n\t\tdescription: 'Channel overview (≈48h lag)',\n\t\tcategory: 'youtube',\n\t\tprovider: 'youtube',\n\t\tfn: 'getChannelOverview',\n\t\tunavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',\n\t},\n\t'youtube/videos': {\n\t\tname: 'youtube/videos',\n\t\tdescription: 'Per-video performance (≈48h lag)',\n\t\tcategory: 'youtube',\n\t\tprovider: 'youtube',\n\t\tfn: 'getVideoPerformance',\n\t\tunavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',\n\t},\n\t'youtube/daily': {\n\t\tname: 'youtube/daily',\n\t\tdescription: 'Daily views + watch minutes (≈48h lag)',\n\t\tcategory: 'youtube',\n\t\tprovider: 'youtube',\n\t\tfn: 'getChannelTimeseries',\n\t\tunavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',\n\t},\n\t'youtube/sources': {\n\t\tname: 'youtube/sources',\n\t\tdescription: 'YouTube traffic sources (≈48h lag)',\n\t\tcategory: 'youtube',\n\t\tprovider: 'youtube',\n\t\tfn: 'getYouTubeTrafficSources',\n\t\tunavailableFix: 'Complete OAuth at /api/analytics/youtube-auth',\n\t},\n\t'correlation/traffic-revenue': {\n\t\tname: 'correlation/traffic-revenue',\n\t\tdescription: 'GA4 sessions + revenue by day',\n\t\tcategory: 'correlation',\n\t\tprovider: 'derived',\n\t\tfn: 'getTrafficRevenueCorrelation',\n\t},\n\t'correlation/youtube-revenue': {\n\t\tname: 'correlation/youtube-revenue',\n\t\tdescription: 'YouTube (≈48h lag) + GA4 + revenue overlay',\n\t\tcategory: 'correlation',\n\t\tprovider: 'derived',\n\t\tfn: 'getYouTubeRevenueCorrelation',\n\t},\n\tsurveys: {\n\t\tname: 'surveys',\n\t\tdescription: 'Survey overview: total surveys, responses, respondents',\n\t\tcategory: 'survey',\n\t\tprovider: 'survey',\n\t\tfn: 'getSurveySummary',\n\t},\n\t'surveys/list': {\n\t\tname: 'surveys/list',\n\t\tdescription: 'All surveys with response counts',\n\t\tcategory: 'survey',\n\t\tprovider: 'survey',\n\t\tfn: 'getSurveyList',\n\t},\n\t'surveys/daily': {\n\t\tname: 'surveys/daily',\n\t\tdescription: 'Daily survey response volume',\n\t\tcategory: 'survey',\n\t\tprovider: 'survey',\n\t\tfn: 'getSurveyResponsesByDay',\n\t},\n\t'surveys/questions': {\n\t\tname: 'surveys/questions',\n\t\tdescription: 'Top questions by response count with answer distribution',\n\t\tcategory: 'survey',\n\t\tprovider: 'survey',\n\t\tfn: 'getSurveyQuestionBreakdown',\n\t},\n\t'surveys/responses': {\n\t\tname: 'surveys/responses',\n\t\tdescription:\n\t\t\t'Individual survey responses as flat rows (multi-choice and open-ended)',\n\t\tcategory: 'survey',\n\t\tprovider: 'survey',\n\t\tfn: 'getSurveyResponses',\n\t},\n\t'attribution/email-campaigns': {\n\t\tname: 'attribution/email-campaigns',\n\t\tdescription:\n\t\t\t'Kit email broadcasts → shortlink clicks → signups → purchases → revenue per campaign',\n\t\tcategory: 'attribution',\n\t\tprovider: 'newsletter',\n\t\tfn: 'getEmailCampaignAttribution',\n\t},\n\t'correlation/survey-revenue': {\n\t\tname: 'correlation/survey-revenue',\n\t\tdescription: 'Survey respondents → purchase conversion by question/answer',\n\t\tcategory: 'correlation',\n\t\tprovider: 'derived',\n\t\tfn: 'getSurveyRevenueCorrelation',\n\t},\n} as const satisfies Record<SurfaceName, SurfaceEntry>\n\nexport const ANALYTICS_CATALOG = catalog\n","import { catalog, type SurfaceEntry } from './catalog'\nimport type {\n\tAnalyticsRange,\n\tQueryOptions,\n\tQueryResult,\n\tSurfaceMap,\n\tSurfaceName,\n} from './types'\n\nexport type AnalyticsProvider = Record<\n\tstring,\n\t((...args: any[]) => Promise<any>) | unknown\n>\n\nexport type ProviderMap = Record<string, AnalyticsProvider>\n\nfunction toGA4Range(range: AnalyticsRange): '24h' | '7d' | '30d' | '90d' {\n\tif (range === 'all') return '90d'\n\treturn range\n}\n\nfunction toYouTubeRange(range: AnalyticsRange): '24h' | '7d' | '30d' | '90d' {\n\tif (range === 'all') return '90d'\n\treturn range\n}\n\nasync function invokeSurface<S extends SurfaceName>(\n\tproviders: ProviderMap,\n\tsurface: S,\n\trange: AnalyticsRange,\n\tlimit: number,\n): Promise<SurfaceMap[S] | null> {\n\tconst entry = catalog[surface]\n\tconst provider = providers[entry.provider]\n\n\tif (!provider) {\n\t\treturn null\n\t}\n\n\t// Check that the provider actually exposes the expected function.\n\t// A provider may exist but not support every surface in the catalog\n\t// (e.g. CWA's derived provider omits YouTube correlation).\n\tif (typeof provider[entry.fn] !== 'function') {\n\t\treturn null\n\t}\n\n\tswitch (surface) {\n\t\tcase 'purchases/recent': {\n\t\t\tconst fn = provider[entry.fn] as (limit: number) => Promise<SurfaceMap[S]>\n\t\t\treturn fn(limit)\n\t\t}\n\t\tcase 'youtube': {\n\t\t\tconst fn = provider[entry.fn] as () => Promise<SurfaceMap[S] | null>\n\t\t\treturn fn()\n\t\t}\n\t\tcase 'youtube/videos':\n\t\tcase 'youtube/daily':\n\t\tcase 'youtube/sources': {\n\t\t\tconst fn = provider[entry.fn] as (\n\t\t\t\trange: '24h' | '7d' | '30d' | '90d',\n\t\t\t\tlimit?: number,\n\t\t\t) => Promise<SurfaceMap[S] | null>\n\t\t\tif (surface === 'youtube/videos') {\n\t\t\t\treturn fn(toYouTubeRange(range), limit)\n\t\t\t}\n\t\t\treturn fn(toYouTubeRange(range))\n\t\t}\n\t\tcase 'traffic':\n\t\tcase 'traffic/daily':\n\t\tcase 'traffic/pages':\n\t\tcase 'traffic/sources': {\n\t\t\tconst fn = provider[entry.fn] as (\n\t\t\t\trange: '24h' | '7d' | '30d' | '90d',\n\t\t\t\tlimit?: number,\n\t\t\t) => Promise<SurfaceMap[S]>\n\t\t\tif (surface === 'traffic/pages' || surface === 'traffic/sources') {\n\t\t\t\treturn fn(toGA4Range(range), limit)\n\t\t\t}\n\t\t\treturn fn(toGA4Range(range))\n\t\t}\n\t\tcase 'surveys':\n\t\tcase 'surveys/list':\n\t\tcase 'surveys/daily': {\n\t\t\tconst fn = provider[entry.fn] as (\n\t\t\t\trange: AnalyticsRange,\n\t\t\t) => Promise<SurfaceMap[S]>\n\t\t\treturn fn(range)\n\t\t}\n\t\tcase 'attribution/email-campaigns': {\n\t\t\tconst fn = provider[entry.fn] as (\n\t\t\t\trange: AnalyticsRange,\n\t\t\t\tlimit?: number,\n\t\t\t) => Promise<SurfaceMap[S]>\n\t\t\treturn fn(range, limit)\n\t\t}\n\t\tcase 'surveys/questions':\n\t\tcase 'surveys/responses': {\n\t\t\tconst fn = provider[entry.fn] as (\n\t\t\t\trange: AnalyticsRange,\n\t\t\t\tlimit: number,\n\t\t\t) => Promise<SurfaceMap[S]>\n\t\t\treturn fn(range, limit)\n\t\t}\n\t\tdefault: {\n\t\t\tconst fn = provider[entry.fn] as (\n\t\t\t\trange: AnalyticsRange,\n\t\t\t\tlimit?: number,\n\t\t\t) => Promise<SurfaceMap[S] | null>\n\t\t\tif (\n\t\t\t\tsurface === 'attribution/content' ||\n\t\t\t\tsurface === 'correlation/survey-revenue'\n\t\t\t) {\n\t\t\t\treturn fn(range, limit)\n\t\t\t}\n\t\t\treturn fn(range)\n\t\t}\n\t}\n}\n\n/**\n * Creates an analytics engine bound to the given provider map.\n *\n * @param providers - A map of provider name → provider implementation. Keys\n *   must match the `provider` field values used in the catalog\n *   ('database', 'ga4', 'youtube', 'derived', 'newsletter', 'survey').\n * @returns An object with `query`, `queryMany`, and `getCatalog` methods.\n */\nexport function createAnalyticsEngine(providers: ProviderMap) {\n\tasync function query<S extends SurfaceName>(\n\t\tsurface: S,\n\t\toptions?: QueryOptions,\n\t): Promise<QueryResult<S>> {\n\t\tconst range = options?.range ?? '30d'\n\t\tconst limit = options?.limit ?? 20\n\t\tconst entry = catalog[surface]\n\t\tconst startMs = Date.now()\n\n\t\ttry {\n\t\t\tconst data = await invokeSurface(providers, surface, range, limit)\n\n\t\t\tif (data === null) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\tsurface,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tmessage: `${entry.provider} is not available`,\n\t\t\t\t\t\tcode: `${entry.provider.toUpperCase()}_UNAVAILABLE`,\n\t\t\t\t\t},\n\t\t\t\t\tfix: entry.unavailableFix ?? 'Check provider configuration',\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tok: true,\n\t\t\t\tsurface,\n\t\t\t\trange,\n\t\t\t\tdata,\n\t\t\t\tmeta: {\n\t\t\t\t\tqueryTimeMs: Date.now() - startMs,\n\t\t\t\t\ttruncated: Array.isArray(data) && data.length >= limit,\n\t\t\t\t},\n\t\t\t}\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\tsurface,\n\t\t\t\terror: {\n\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\tcode: 'QUERY_FAILED',\n\t\t\t\t},\n\t\t\t\tfix: `The ${surface} query failed. Try a different range or check server logs.`,\n\t\t\t}\n\t\t}\n\t}\n\n\tasync function queryMany<S extends SurfaceName>(\n\t\tsurfaces: S[],\n\t\toptions?: QueryOptions,\n\t): Promise<{ [K in S]: QueryResult<K> }> {\n\t\tconst results = await Promise.all(\n\t\t\tsurfaces.map(\n\t\t\t\tasync (surface) => [surface, await query(surface, options)] as const,\n\t\t\t),\n\t\t)\n\n\t\treturn Object.fromEntries(results) as { [K in S]: QueryResult<K> }\n\t}\n\n\t/**\n\t * Returns catalog entries filtered to only surfaces that this engine\n\t * can actually serve (provider present and function exported).\n\t */\n\tfunction getCatalog(): SurfaceEntry[] {\n\t\treturn Object.values(catalog).filter((entry) => {\n\t\t\tconst provider = providers[entry.provider]\n\t\t\treturn provider && typeof provider[entry.fn] === 'function'\n\t\t})\n\t}\n\n\treturn { query, queryMany, getCatalog }\n}\n"],"mappings":"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","names":["catalog","summary","name","description","category","provider","fn","attribution","traffic","youtube","unavailableFix","surveys","toGA4Range","range","toYouTubeRange","invokeSurface","providers","surface","limit","entry","catalog","provider","fn","createAnalyticsEngine","query","options","startMs","Date","now","data","ok","error","message","code","toUpperCase","fix","unavailableFix","meta","queryTimeMs","truncated","Array","isArray","length","Error","String","queryMany","surfaces","results","Promise","all","map","Object","fromEntries","getCatalog","values","filter"]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AnalyticsRange, AttributionCount, AttributionCoverage, ContentCorrelation, ConversionFunnel, Count, EmailCampaignFunnel, EmailCampaignKitLink, EmailCampaignShortlink, EmailRevenueOverview, Minutes, Percentage, QueryOptions, QueryResult, RecentPurchase, RevenueByCountry, RevenueByProduct, RevenueBySource, RevenueDaily, RevenueSummary, Seconds, ShortlinkPerformance, SurfaceMap, SurfaceName, SurveyConversionByQuestion, SurveyListItem, SurveyQuestionBreakdown, SurveyResponseRow, SurveyResponsesDaily, SurveyRevenueCorrelation, SurveySummary, TopPage, TrafficDaily, TrafficOverview, TrafficRevenueCorrelation, TrafficSource, USD, YouTubeChannelOverview, YouTubeDaily, YouTubeRevenueCorrelation, YouTubeTrafficSource, YouTubeVideoPerformance } from './types.js';
+export { ANALYTICS_CATALOG, SurfaceEntry, catalog } from './catalog.js';
+export { AnalyticsProvider, ProviderMap, createAnalyticsEngine } from './engine.js';