@coursebuilder/analytics 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Skill Recordings Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/api/index.d.ts

@@ -0,0 +1,158 @@
+import { QueryOptions, QueryResult, SurfaceName, SurfaceMap, AnalyticsRange as AnalyticsRange$1, RevenueSummary, ConversionFunnel, AttributionCoverage, TrafficOverview, YouTubeChannelOverview, TrafficRevenueCorrelation, TrafficDaily, RevenueDaily, YouTubeRevenueCorrelation, YouTubeDaily, SurveySummary, EmailRevenueOverview, SurveyRevenueCorrelation, RevenueByProduct, RevenueByCountry, RecentPurchase, AttributionCount, ShortlinkPerformance, RevenueBySource, ContentCorrelation, TopPage, TrafficSource, YouTubeVideoPerformance, YouTubeTrafficSource, SurveyListItem, SurveyResponsesDaily, SurveyQuestionBreakdown, SurveyResponseRow } from '../types.js';
+import { NextRequest, NextResponse } from 'next/server';
+import { SurfaceEntry } from '../catalog.js';
+
+type AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all';
+interface CatalogHandlerDeps {
+    engine: {
+        query: (surface: string, options?: QueryOptions) => Promise<QueryResult<SurfaceName>>;
+        getCatalog: () => SurfaceEntry[];
+    };
+    checkAccess: (request: Request) => Promise<{
+        authorized: boolean;
+        user?: Record<string, unknown> | null;
+        authMethod?: string;
+    }>;
+    logger?: {
+        info: (message: string, data?: Record<string, unknown>) => unknown;
+        warn: (message: string, data?: Record<string, unknown>) => unknown;
+        error: (message: string, data?: Record<string, unknown>) => unknown;
+    };
+    appName?: string;
+    baseUrl?: string;
+}
+
+/**
+ * Creates a Next.js App Router GET handler that serves a HATEOAS-style
+ * analytics catalog and surface query API.
+ *
+ * @param deps - Handler dependencies including engine, access check, and
+ *   optional logger and app metadata
+ * @returns An object with `GET` and `OPTIONS` Next.js route handlers
+ */
+declare function createAnalyticsCatalogHandler(deps: CatalogHandlerDeps): {
+    GET: (request: NextRequest) => Promise<NextResponse<{
+        ok: boolean;
+        endpoint: string;
+        error: {
+            message: string;
+            code: string;
+        };
+        fix: string;
+        next_actions: {
+            command: string;
+            description: string;
+        }[];
+    }> | NextResponse<{
+        ok: boolean;
+        endpoint: string;
+        description: string;
+        notes: string[];
+        surfaces: SurfaceEntry[];
+        _links: {
+            self: {
+                href: string;
+            };
+        };
+        next_actions: {
+            command: string;
+            description: string;
+            params: {
+                surface: {
+                    required: boolean;
+                    enum: (keyof SurfaceMap)[];
+                    description: string;
+                };
+                range: {
+                    default: string;
+                    enum: AnalyticsRange[];
+                    description: string;
+                };
+                limit: {
+                    default: string;
+                    description: string;
+                };
+            };
+        }[];
+    }> | NextResponse<{
+        ok: boolean;
+        endpoint: string;
+        surface: string;
+        range: AnalyticsRange$1;
+        description: string;
+        data: RevenueSummary | ConversionFunnel | AttributionCoverage | TrafficOverview | YouTubeChannelOverview | TrafficRevenueCorrelation | TrafficDaily[] | RevenueDaily[] | YouTubeRevenueCorrelation | YouTubeDaily[] | SurveySummary | EmailRevenueOverview | SurveyRevenueCorrelation | RevenueByProduct[] | RevenueByCountry[] | RecentPurchase[] | AttributionCount[] | ShortlinkPerformance[] | RevenueBySource[] | ContentCorrelation[] | TopPage[] | TrafficSource[] | YouTubeVideoPerformance[] | YouTubeTrafficSource[] | SurveyListItem[] | SurveyResponsesDaily[] | SurveyQuestionBreakdown[] | SurveyResponseRow[];
+        meta: {
+            totalRows: number;
+            truncated: boolean;
+            queryTimeMs: number;
+        };
+        _links: {
+            self: {
+                href: string;
+            };
+            catalog: {
+                href: string;
+            };
+        };
+        next_actions: {
+            command: string;
+            description: string;
+            params: {
+                range: {
+                    value: AnalyticsRange;
+                    enum: AnalyticsRange[];
+                };
+            };
+        }[];
+    }>>;
+    OPTIONS: () => NextResponse<{}>;
+};
+
+interface TokenHandlerDeps {
+    db: {
+        insert: (table: any) => {
+            values: (data: any) => Promise<any>;
+        };
+    };
+    deviceAccessToken: unknown;
+    checkAccess: (request: Request) => Promise<{
+        authorized: boolean;
+        userId?: string;
+        user?: {
+            email?: string;
+            [key: string]: unknown;
+        } | null;
+    }>;
+    ttlHours?: number;
+    logger?: {
+        info: (message: string, data?: Record<string, unknown>) => unknown;
+        warn: (message: string, data?: Record<string, unknown>) => unknown;
+        error: (message: string, data?: Record<string, unknown>) => unknown;
+    };
+}
+
+/**
+ * Creates a Next.js App Router POST handler that generates short-lived
+ * device access tokens for analytics API authentication.
+ *
+ * Tokens are stored with only `token` and `userId`. Expiry is **not**
+ * stored in the database — it is enforced at lookup time by comparing
+ * the row's `createdAt` timestamp against the configured TTL. Each
+ * app's `getUserAbilityForRequest` must enforce this check.
+ *
+ * @param deps - Handler dependencies including db, deviceAccessToken schema
+ *   table, an access-check function, and optional TTL and logger overrides
+ * @returns An object with a `POST` Next.js route handler
+ */
+declare function createTokenHandler(deps: TokenHandlerDeps): {
+    POST: (request: NextRequest) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        token: string;
+        ttl: string;
+        ttlLabel: string;
+        expiresAt: string;
+    }>>;
+};
+
+export { type CatalogHandlerDeps, type TokenHandlerDeps, createAnalyticsCatalogHandler, createTokenHandler };

package/dist/api/index.js

@@ -0,0 +1,317 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/api/catalog-handler.ts
+import { NextResponse } from "next/server";
+var VALID_RANGES = /* @__PURE__ */ new Set([
+  "24h",
+  "7d",
+  "30d",
+  "90d",
+  "all"
+]);
+var RANGE_OPTIONS = [
+  "24h",
+  "7d",
+  "30d",
+  "90d",
+  "all"
+];
+var CATEGORY_SUGGESTIONS = {
+  revenue: [
+    "revenue/daily",
+    "revenue/products",
+    "attribution/sources",
+    "correlation/traffic-revenue"
+  ],
+  attribution: [
+    "attribution/funnel",
+    "attribution/sources",
+    "attribution/coverage",
+    "correlation/traffic-revenue"
+  ],
+  traffic: [
+    "traffic/daily",
+    "traffic/sources",
+    "correlation/traffic-revenue",
+    "correlation/youtube-revenue"
+  ],
+  youtube: [
+    "youtube/videos",
+    "youtube/daily",
+    "youtube/sources",
+    "correlation/youtube-revenue"
+  ],
+  correlation: [
+    "summary",
+    "attribution/funnel",
+    "youtube",
+    "correlation/survey-revenue"
+  ],
+  survey: [
+    "surveys",
+    "surveys/list",
+    "surveys/daily",
+    "surveys/questions",
+    "surveys/responses"
+  ]
+};
+var corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization"
+};
+function parseRange(raw) {
+  if (raw && VALID_RANGES.has(raw)) {
+    return raw;
+  }
+  return "30d";
+}
+__name(parseRange, "parseRange");
+function getMeta(data, queryTimeMs, truncated) {
+  return {
+    totalRows: Array.isArray(data) ? data.length : 1,
+    truncated,
+    queryTimeMs
+  };
+}
+__name(getMeta, "getMeta");
+function createAnalyticsCatalogHandler(deps) {
+  const { engine, checkAccess, logger, appName, baseUrl } = deps;
+  const catalog = engine.getCatalog();
+  const catalogByName = Object.fromEntries(catalog.map((entry) => [
+    entry.name,
+    entry
+  ]));
+  function buildContextualNextActions(surface, range, endpointPath) {
+    const entry = catalogByName[surface];
+    if (!entry)
+      return [];
+    const suggestions = CATEGORY_SUGGESTIONS[entry.category] ?? [];
+    return suggestions.filter((name) => name !== surface).slice(0, 4).map((name) => ({
+      command: `GET ${endpointPath}?surface=${name}&range=<range>`,
+      description: catalogByName[name]?.description ?? name,
+      params: {
+        range: {
+          value: range,
+          enum: RANGE_OPTIONS
+        }
+      }
+    }));
+  }
+  __name(buildContextualNextActions, "buildContextualNextActions");
+  const OPTIONS = /* @__PURE__ */ __name(() => NextResponse.json({}, {
+    headers: corsHeaders
+  }), "OPTIONS");
+  const GET = /* @__PURE__ */ __name(async (request) => {
+    const requestUrl = new URL(request.url);
+    const resolvedBase = baseUrl ?? `${requestUrl.protocol}//${requestUrl.host}`;
+    const endpointPath = `${requestUrl.pathname}`;
+    const appLabel = appName ?? "Analytics";
+    const access = await checkAccess(request);
+    if (!access.authorized) {
+      if (logger) {
+        void logger.warn("api.analytics.access-denied", {
+          userId: access.user?.id ?? null,
+          email: access.user?.email ?? null,
+          authMethod: access.authMethod ?? "unknown",
+          hasAuthorization: false
+        });
+      }
+      return NextResponse.json({
+        ok: false,
+        endpoint: endpointPath,
+        error: {
+          message: "Unauthorized",
+          code: "AUTH_REQUIRED"
+        },
+        fix: "Authenticate with an admin device token or an admin session cookie.",
+        next_actions: [
+          {
+            command: "GET /api/coursebuilder/devices",
+            description: "Start device verification flow to obtain a Bearer token"
+          },
+          {
+            command: "GET /login",
+            description: "Log in as an admin to use session-based auth"
+          }
+        ]
+      }, {
+        status: 401,
+        headers: corsHeaders
+      });
+    }
+    const { searchParams } = requestUrl;
+    const rawSurface = searchParams.get("surface");
+    if (!rawSurface) {
+      return NextResponse.json({
+        ok: true,
+        endpoint: endpointPath,
+        description: `${appLabel} analytics \u2014 revenue, attribution, traffic, YouTube, and content correlation`,
+        notes: [
+          "YouTube surfaces are useful for correlation/content analysis but lag by about 48 hours."
+        ],
+        surfaces: catalog,
+        _links: {
+          self: {
+            href: `${resolvedBase}${endpointPath}`
+          }
+        },
+        next_actions: [
+          {
+            command: `GET ${endpointPath}?surface=<surface>&range=<range>&limit=<limit>`,
+            description: "Query a specific analytics surface",
+            params: {
+              surface: {
+                required: true,
+                enum: catalog.map((entry) => entry.name),
+                description: "Analytics surface to query"
+              },
+              range: {
+                default: "30d",
+                enum: RANGE_OPTIONS,
+                description: "Time range"
+              },
+              limit: {
+                default: "20",
+                description: "Max rows for surfaces that support it (max 100)"
+              }
+            }
+          }
+        ]
+      }, {
+        headers: corsHeaders
+      });
+    }
+    if (!(rawSurface in catalogByName)) {
+      return NextResponse.json({
+        ok: false,
+        endpoint: endpointPath,
+        error: {
+          message: `Unknown surface: ${rawSurface}`,
+          code: "INVALID_SURFACE"
+        },
+        fix: `Hit GET ${endpointPath} with no params for the full surface catalog.`,
+        next_actions: [
+          {
+            command: `GET ${endpointPath}`,
+            description: "Browse the full analytics surface catalog"
+          }
+        ]
+      }, {
+        status: 400,
+        headers: corsHeaders
+      });
+    }
+    const surface = rawSurface;
+    const range = parseRange(searchParams.get("range"));
+    const limit = Math.min(Number(searchParams.get("limit") ?? 20), 100);
+    if (logger) {
+      logger.info("api.analytics.query", {
+        userId: access.user?.id ?? null,
+        email: access.user?.email ?? null,
+        authMethod: access.authMethod ?? "unknown",
+        surface,
+        range,
+        limit
+      });
+    }
+    const result = await engine.query(surface, {
+      range,
+      limit
+    });
+    if (!result.ok) {
+      if (logger) {
+        logger.error("api.analytics.error", {
+          userId: access.user?.id ?? null,
+          surface,
+          range,
+          code: result.error.code,
+          error: result.error.message
+        });
+      }
+      return NextResponse.json({
+        ok: false,
+        endpoint: endpointPath,
+        surface,
+        error: result.error,
+        fix: result.fix,
+        next_actions: buildContextualNextActions(surface, range, endpointPath)
+      }, {
+        status: result.error.code.endsWith("_UNAVAILABLE") ? 503 : 500,
+        headers: corsHeaders
+      });
+    }
+    return NextResponse.json({
+      ok: true,
+      endpoint: endpointPath,
+      surface,
+      range: result.range,
+      description: catalogByName[surface]?.description,
+      data: result.data,
+      meta: getMeta(result.data, result.meta.queryTimeMs, result.meta.truncated),
+      _links: {
+        self: {
+          href: `${resolvedBase}${endpointPath}?surface=${surface}&range=${range}`
+        },
+        catalog: {
+          href: `${resolvedBase}${endpointPath}`
+        }
+      },
+      next_actions: buildContextualNextActions(surface, range, endpointPath)
+    }, {
+      headers: corsHeaders
+    });
+  }, "GET");
+  return {
+    GET,
+    OPTIONS
+  };
+}
+__name(createAnalyticsCatalogHandler, "createAnalyticsCatalogHandler");
+
+// src/api/token-handler.ts
+import { NextResponse as NextResponse2 } from "next/server";
+function createTokenHandler(deps) {
+  const { db, deviceAccessToken, checkAccess, logger } = deps;
+  const ttlHours = deps.ttlHours ?? 24;
+  const ttlLabel = `${ttlHours} hours`;
+  const POST = /* @__PURE__ */ __name(async (request) => {
+    const access = await checkAccess(request);
+    if (!access.authorized || !access.userId) {
+      return NextResponse2.json({
+        error: "Unauthorized"
+      }, {
+        status: 401
+      });
+    }
+    const userId = access.userId;
+    const token = crypto.randomUUID();
+    await db.insert(deviceAccessToken).values({
+      token,
+      userId
+    });
+    if (logger) {
+      void logger.info("api.analytics.token-generated", {
+        userId,
+        email: access.user?.email ?? null,
+        ttlHours
+      });
+    }
+    return NextResponse2.json({
+      token,
+      ttl: `${ttlHours}h`,
+      ttlLabel,
+      expiresAt: new Date(Date.now() + ttlHours * 60 * 60 * 1e3).toISOString()
+    });
+  }, "POST");
+  return {
+    POST
+  };
+}
+__name(createTokenHandler, "createTokenHandler");
+export {
+  createAnalyticsCatalogHandler,
+  createTokenHandler
+};
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/api/catalog-handler.ts","../../src/api/token-handler.ts"],"sourcesContent":["import { NextRequest, NextResponse } from 'next/server'\n\nimport type { SurfaceEntry } from '../catalog'\nimport type { QueryOptions, QueryResult, SurfaceName } from '../types'\n\ntype AnalyticsRange = '24h' | '7d' | '30d' | '90d' | 'all'\n\ninterface CatalogHandlerDeps {\n\tengine: {\n\t\tquery: (\n\t\t\tsurface: string,\n\t\t\toptions?: QueryOptions,\n\t\t) => Promise<QueryResult<SurfaceName>>\n\t\tgetCatalog: () => SurfaceEntry[]\n\t}\n\tcheckAccess: (request: Request) => Promise<{\n\t\tauthorized: boolean\n\t\tuser?: Record<string, unknown> | null\n\t\tauthMethod?: string\n\t}>\n\tlogger?: {\n\t\tinfo: (message: string, data?: Record<string, unknown>) => unknown\n\t\twarn: (message: string, data?: Record<string, unknown>) => unknown\n\t\terror: (message: string, data?: Record<string, unknown>) => unknown\n\t}\n\tappName?: string\n\tbaseUrl?: string\n}\n\nexport type { CatalogHandlerDeps }\n\nconst VALID_RANGES = new Set<AnalyticsRange>(['24h', '7d', '30d', '90d', 'all'])\nconst RANGE_OPTIONS: AnalyticsRange[] = ['24h', '7d', '30d', '90d', 'all']\n\nconst CATEGORY_SUGGESTIONS: Record<string, string[]> = {\n\trevenue: [\n\t\t'revenue/daily',\n\t\t'revenue/products',\n\t\t'attribution/sources',\n\t\t'correlation/traffic-revenue',\n\t],\n\tattribution: [\n\t\t'attribution/funnel',\n\t\t'attribution/sources',\n\t\t'attribution/coverage',\n\t\t'correlation/traffic-revenue',\n\t],\n\ttraffic: [\n\t\t'traffic/daily',\n\t\t'traffic/sources',\n\t\t'correlation/traffic-revenue',\n\t\t'correlation/youtube-revenue',\n\t],\n\tyoutube: [\n\t\t'youtube/videos',\n\t\t'youtube/daily',\n\t\t'youtube/sources',\n\t\t'correlation/youtube-revenue',\n\t],\n\tcorrelation: [\n\t\t'summary',\n\t\t'attribution/funnel',\n\t\t'youtube',\n\t\t'correlation/survey-revenue',\n\t],\n\tsurvey: [\n\t\t'surveys',\n\t\t'surveys/list',\n\t\t'surveys/daily',\n\t\t'surveys/questions',\n\t\t'surveys/responses',\n\t],\n}\n\nconst corsHeaders = {\n\t'Access-Control-Allow-Origin': '*',\n\t'Access-Control-Allow-Methods': 'GET, OPTIONS',\n\t'Access-Control-Allow-Headers': 'Content-Type, Authorization',\n}\n\nfunction parseRange(raw?: string | null): AnalyticsRange {\n\tif (raw && VALID_RANGES.has(raw as AnalyticsRange)) {\n\t\treturn raw as AnalyticsRange\n\t}\n\n\treturn '30d'\n}\n\nfunction getMeta(data: unknown, queryTimeMs: number, truncated: boolean) {\n\treturn {\n\t\ttotalRows: Array.isArray(data) ? data.length : 1,\n\t\ttruncated,\n\t\tqueryTimeMs,\n\t}\n}\n\n/**\n * Creates a Next.js App Router GET handler that serves a HATEOAS-style\n * analytics catalog and surface query API.\n *\n * @param deps - Handler dependencies including engine, access check, and\n *   optional logger and app metadata\n * @returns An object with `GET` and `OPTIONS` Next.js route handlers\n */\nexport function createAnalyticsCatalogHandler(deps: CatalogHandlerDeps) {\n\tconst { engine, checkAccess, logger, appName, baseUrl } = deps\n\n\tconst catalog = engine.getCatalog()\n\tconst catalogByName = Object.fromEntries(\n\t\tcatalog.map((entry) => [entry.name, entry]),\n\t) as Record<string, SurfaceEntry>\n\n\tfunction buildContextualNextActions(\n\t\tsurface: string,\n\t\trange: AnalyticsRange,\n\t\tendpointPath: string,\n\t) {\n\t\tconst entry = catalogByName[surface]\n\t\tif (!entry) return []\n\t\tconst suggestions = CATEGORY_SUGGESTIONS[entry.category] ?? []\n\n\t\treturn suggestions\n\t\t\t.filter((name) => name !== surface)\n\t\t\t.slice(0, 4)\n\t\t\t.map((name) => ({\n\t\t\t\tcommand: `GET ${endpointPath}?surface=${name}&range=<range>`,\n\t\t\t\tdescription: catalogByName[name]?.description ?? name,\n\t\t\t\tparams: {\n\t\t\t\t\trange: {\n\t\t\t\t\t\tvalue: range,\n\t\t\t\t\t\tenum: RANGE_OPTIONS,\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t}))\n\t}\n\n\tconst OPTIONS = () => NextResponse.json({}, { headers: corsHeaders })\n\n\tconst GET = async (request: NextRequest) => {\n\t\tconst requestUrl = new URL(request.url)\n\t\tconst resolvedBase = baseUrl ?? `${requestUrl.protocol}//${requestUrl.host}`\n\t\tconst endpointPath = `${requestUrl.pathname}`\n\t\tconst appLabel = appName ?? 'Analytics'\n\n\t\tconst access = await checkAccess(request)\n\n\t\tif (!access.authorized) {\n\t\t\tif (logger) {\n\t\t\t\tvoid logger.warn('api.analytics.access-denied', {\n\t\t\t\t\tuserId: access.user?.id ?? null,\n\t\t\t\t\temail: access.user?.email ?? null,\n\t\t\t\t\tauthMethod: access.authMethod ?? 'unknown',\n\t\t\t\t\thasAuthorization: false,\n\t\t\t\t})\n\t\t\t}\n\n\t\t\treturn NextResponse.json(\n\t\t\t\t{\n\t\t\t\t\tok: false,\n\t\t\t\t\tendpoint: endpointPath,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tmessage: 'Unauthorized',\n\t\t\t\t\t\tcode: 'AUTH_REQUIRED',\n\t\t\t\t\t},\n\t\t\t\t\tfix: 'Authenticate with an admin device token or an admin session cookie.',\n\t\t\t\t\tnext_actions: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcommand: 'GET /api/coursebuilder/devices',\n\t\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\t'Start device verification flow to obtain a Bearer token',\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcommand: 'GET /login',\n\t\t\t\t\t\t\tdescription: 'Log in as an admin to use session-based auth',\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t\t{ status: 401, headers: corsHeaders },\n\t\t\t)\n\t\t}\n\n\t\tconst { searchParams } = requestUrl\n\t\tconst rawSurface = searchParams.get('surface')\n\n\t\tif (!rawSurface) {\n\t\t\treturn NextResponse.json(\n\t\t\t\t{\n\t\t\t\t\tok: true,\n\t\t\t\t\tendpoint: endpointPath,\n\t\t\t\t\tdescription: `${appLabel} analytics — revenue, attribution, traffic, YouTube, and content correlation`,\n\t\t\t\t\tnotes: [\n\t\t\t\t\t\t'YouTube surfaces are useful for correlation/content analysis but lag by about 48 hours.',\n\t\t\t\t\t],\n\t\t\t\t\tsurfaces: catalog,\n\t\t\t\t\t_links: {\n\t\t\t\t\t\tself: { href: `${resolvedBase}${endpointPath}` },\n\t\t\t\t\t},\n\t\t\t\t\tnext_actions: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcommand: `GET ${endpointPath}?surface=<surface>&range=<range>&limit=<limit>`,\n\t\t\t\t\t\t\tdescription: 'Query a specific analytics surface',\n\t\t\t\t\t\t\tparams: {\n\t\t\t\t\t\t\t\tsurface: {\n\t\t\t\t\t\t\t\t\trequired: true,\n\t\t\t\t\t\t\t\t\tenum: catalog.map((entry) => entry.name),\n\t\t\t\t\t\t\t\t\tdescription: 'Analytics surface to query',\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\trange: {\n\t\t\t\t\t\t\t\t\tdefault: '30d',\n\t\t\t\t\t\t\t\t\tenum: RANGE_OPTIONS,\n\t\t\t\t\t\t\t\t\tdescription: 'Time range',\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\tlimit: {\n\t\t\t\t\t\t\t\t\tdefault: '20',\n\t\t\t\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\t\t\t'Max rows for surfaces that support it (max 100)',\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t\t{ headers: corsHeaders },\n\t\t\t)\n\t\t}\n\n\t\tif (!(rawSurface in catalogByName)) {\n\t\t\treturn NextResponse.json(\n\t\t\t\t{\n\t\t\t\t\tok: false,\n\t\t\t\t\tendpoint: endpointPath,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tmessage: `Unknown surface: ${rawSurface}`,\n\t\t\t\t\t\tcode: 'INVALID_SURFACE',\n\t\t\t\t\t},\n\t\t\t\t\tfix: `Hit GET ${endpointPath} with no params for the full surface catalog.`,\n\t\t\t\t\tnext_actions: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tcommand: `GET ${endpointPath}`,\n\t\t\t\t\t\t\tdescription: 'Browse the full analytics surface catalog',\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t\t{ status: 400, headers: corsHeaders },\n\t\t\t)\n\t\t}\n\n\t\tconst surface = rawSurface\n\t\tconst range = parseRange(searchParams.get('range'))\n\t\tconst limit = Math.min(Number(searchParams.get('limit') ?? 20), 100)\n\n\t\tif (logger) {\n\t\t\tlogger.info('api.analytics.query', {\n\t\t\t\tuserId: access.user?.id ?? null,\n\t\t\t\temail: access.user?.email ?? null,\n\t\t\t\tauthMethod: access.authMethod ?? 'unknown',\n\t\t\t\tsurface,\n\t\t\t\trange,\n\t\t\t\tlimit,\n\t\t\t})\n\t\t}\n\n\t\tconst result = await engine.query(surface, { range, limit })\n\n\t\tif (!result.ok) {\n\t\t\tif (logger) {\n\t\t\t\tlogger.error('api.analytics.error', {\n\t\t\t\t\tuserId: access.user?.id ?? null,\n\t\t\t\t\tsurface,\n\t\t\t\t\trange,\n\t\t\t\t\tcode: result.error.code,\n\t\t\t\t\terror: result.error.message,\n\t\t\t\t})\n\t\t\t}\n\n\t\t\treturn NextResponse.json(\n\t\t\t\t{\n\t\t\t\t\tok: false,\n\t\t\t\t\tendpoint: endpointPath,\n\t\t\t\t\tsurface,\n\t\t\t\t\terror: result.error,\n\t\t\t\t\tfix: result.fix,\n\t\t\t\t\tnext_actions: buildContextualNextActions(\n\t\t\t\t\t\tsurface,\n\t\t\t\t\t\trange,\n\t\t\t\t\t\tendpointPath,\n\t\t\t\t\t),\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tstatus: result.error.code.endsWith('_UNAVAILABLE') ? 503 : 500,\n\t\t\t\t\theaders: corsHeaders,\n\t\t\t\t},\n\t\t\t)\n\t\t}\n\n\t\treturn NextResponse.json(\n\t\t\t{\n\t\t\t\tok: true,\n\t\t\t\tendpoint: endpointPath,\n\t\t\t\tsurface,\n\t\t\t\trange: result.range,\n\t\t\t\tdescription: catalogByName[surface]?.description,\n\t\t\t\tdata: result.data,\n\t\t\t\tmeta: getMeta(\n\t\t\t\t\tresult.data,\n\t\t\t\t\tresult.meta.queryTimeMs,\n\t\t\t\t\tresult.meta.truncated,\n\t\t\t\t),\n\t\t\t\t_links: {\n\t\t\t\t\tself: {\n\t\t\t\t\t\thref: `${resolvedBase}${endpointPath}?surface=${surface}&range=${range}`,\n\t\t\t\t\t},\n\t\t\t\t\tcatalog: { href: `${resolvedBase}${endpointPath}` },\n\t\t\t\t},\n\t\t\t\tnext_actions: buildContextualNextActions(surface, range, endpointPath),\n\t\t\t},\n\t\t\t{ headers: corsHeaders },\n\t\t)\n\t}\n\n\treturn { GET, OPTIONS }\n}\n","import { NextRequest, NextResponse } from 'next/server'\n\ninterface TokenHandlerDeps {\n\tdb: { insert: (table: any) => { values: (data: any) => Promise<any> } }\n\tdeviceAccessToken: unknown\n\tcheckAccess: (request: Request) => Promise<{\n\t\tauthorized: boolean\n\t\tuserId?: string\n\t\tuser?: { email?: string; [key: string]: unknown } | null\n\t}>\n\tttlHours?: number\n\tlogger?: {\n\t\tinfo: (message: string, data?: Record<string, unknown>) => unknown\n\t\twarn: (message: string, data?: Record<string, unknown>) => unknown\n\t\terror: (message: string, data?: Record<string, unknown>) => unknown\n\t}\n}\n\nexport type { TokenHandlerDeps }\n\n/**\n * Creates a Next.js App Router POST handler that generates short-lived\n * device access tokens for analytics API authentication.\n *\n * Tokens are stored with only `token` and `userId`. Expiry is **not**\n * stored in the database — it is enforced at lookup time by comparing\n * the row's `createdAt` timestamp against the configured TTL. Each\n * app's `getUserAbilityForRequest` must enforce this check.\n *\n * @param deps - Handler dependencies including db, deviceAccessToken schema\n *   table, an access-check function, and optional TTL and logger overrides\n * @returns An object with a `POST` Next.js route handler\n */\nexport function createTokenHandler(deps: TokenHandlerDeps) {\n\tconst { db, deviceAccessToken, checkAccess, logger } = deps\n\tconst ttlHours = deps.ttlHours ?? 24\n\tconst ttlLabel = `${ttlHours} hours`\n\n\tconst POST = async (request: NextRequest) => {\n\t\tconst access = await checkAccess(request)\n\n\t\tif (!access.authorized || !access.userId) {\n\t\t\treturn NextResponse.json({ error: 'Unauthorized' }, { status: 401 })\n\t\t}\n\n\t\tconst userId = access.userId\n\t\tconst token = crypto.randomUUID()\n\n\t\tawait db.insert(deviceAccessToken).values({\n\t\t\ttoken,\n\t\t\tuserId,\n\t\t})\n\n\t\tif (logger) {\n\t\t\tvoid logger.info('api.analytics.token-generated', {\n\t\t\t\tuserId,\n\t\t\t\temail: access.user?.email ?? null,\n\t\t\t\tttlHours,\n\t\t\t})\n\t\t}\n\n\t\treturn NextResponse.json({\n\t\t\ttoken,\n\t\t\tttl: `${ttlHours}h`,\n\t\t\tttlLabel,\n\t\t\texpiresAt: new Date(Date.now() + ttlHours * 60 * 60 * 1000).toISOString(),\n\t\t})\n\t}\n\n\treturn { POST }\n}\n"],"mappings":"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","names":["NextResponse","VALID_RANGES","Set","RANGE_OPTIONS","CATEGORY_SUGGESTIONS","revenue","attribution","traffic","youtube","correlation","survey","corsHeaders","parseRange","raw","has","getMeta","data","queryTimeMs","truncated","totalRows","Array","isArray","length","createAnalyticsCatalogHandler","deps","engine","checkAccess","logger","appName","baseUrl","catalog","getCatalog","catalogByName","Object","fromEntries","map","entry","name","buildContextualNextActions","surface","range","endpointPath","suggestions","category","filter","slice","command","description","params","value","enum","OPTIONS","NextResponse","json","headers","GET","request","requestUrl","URL","url","resolvedBase","protocol","host","pathname","appLabel","access","authorized","warn","userId","user","id","email","authMethod","hasAuthorization","ok","endpoint","error","message","code","fix","next_actions","status","searchParams","rawSurface","get","notes","surfaces","_links","self","href","required","default","limit","Math","min","Number","info","result","query","endsWith","meta","NextResponse","createTokenHandler","deps","db","deviceAccessToken","checkAccess","logger","ttlHours","ttlLabel","POST","request","access","authorized","userId","NextResponse","json","error","status","token","crypto","randomUUID","insert","values","info","email","user","ttl","expiresAt","Date","now","toISOString"]}

package/dist/catalog.d.ts

@@ -0,0 +1,14 @@
+import { SurfaceMap, SurfaceName } from './types.js';
+
+interface SurfaceEntry {
+    name: SurfaceName;
+    description: string;
+    category: 'revenue' | 'attribution' | 'traffic' | 'youtube' | 'correlation' | 'survey';
+    provider: 'database' | 'ga4' | 'youtube' | 'derived' | 'newsletter' | 'survey';
+    fn: string;
+    unavailableFix?: string;
+}
+declare const catalog: Record<SurfaceName, SurfaceEntry>;
+declare const ANALYTICS_CATALOG: Record<keyof SurfaceMap, SurfaceEntry>;
+
+export { ANALYTICS_CATALOG, type SurfaceEntry, catalog };