@contractspec/example.analytics-dashboard 1.56.1 → 1.58.0

package/dist/datasource/posthog-datasource.js

@@ -0,0 +1,290 @@
+// @bun
+// src/datasource/posthog-datasource.ts
+class PosthogQueryEngine {
+  reader;
+  defaultLimit;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.defaultLimit = options.defaultLimit ?? 100;
+  }
+  async execute(definition, params) {
+    const startTime = Date.now();
+    const validation = this.validateQuery(definition);
+    if (!validation.valid) {
+      return {
+        data: [],
+        columns: [],
+        rowCount: 0,
+        executionTimeMs: Date.now() - startTime,
+        cached: false,
+        error: validation.errors.join(", ")
+      };
+    }
+    if (!this.reader.queryHogQL) {
+      return {
+        data: [],
+        columns: [],
+        rowCount: 0,
+        executionTimeMs: Date.now() - startTime,
+        cached: false,
+        error: "Analytics reader does not support HogQL queries."
+      };
+    }
+    try {
+      const result = await this.executeHogQL(definition, params);
+      return {
+        data: result.data,
+        columns: result.columns,
+        rowCount: result.rowCount,
+        executionTimeMs: Date.now() - startTime,
+        cached: false
+      };
+    } catch (error) {
+      return {
+        data: [],
+        columns: [],
+        rowCount: 0,
+        executionTimeMs: Date.now() - startTime,
+        cached: false,
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  validateQuery(definition) {
+    const errors = [];
+    if (definition.type === "SQL" && !definition.sql) {
+      errors.push("SQL query is missing.");
+    }
+    if (definition.type === "AGGREGATION" && !definition.aggregation) {
+      errors.push("Aggregation definition is missing.");
+    }
+    if (definition.type === "METRIC" && !definition.metricIds?.length) {
+      errors.push("Metric IDs are missing.");
+    }
+    if (definition.type === "CUSTOM" && !definition.custom?.handler) {
+      errors.push("Custom handler is missing.");
+    }
+    return { valid: errors.length === 0, errors };
+  }
+  async executeHogQL(definition, params) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    if (definition.type === "SQL") {
+      const result = await this.reader.queryHogQL({
+        query: definition.sql ?? "",
+        values: params.parameters ?? {}
+      });
+      return mapHogqlResult(result);
+    }
+    if (definition.type === "AGGREGATION" && definition.aggregation) {
+      const { query, values } = buildAggregationQuery(definition.aggregation, params);
+      const result = await this.reader.queryHogQL({ query, values });
+      return mapHogqlResult(result);
+    }
+    if (definition.type === "METRIC" && definition.metricIds) {
+      const { query, values } = buildMetricQuery(definition.metricIds, params);
+      const result = await this.reader.queryHogQL({ query, values });
+      return mapHogqlResult(result);
+    }
+    throw new Error("Unsupported query type for PostHog datasource.");
+  }
+}
+function createPosthogQueryEngine(reader, options) {
+  return new PosthogQueryEngine(reader, options);
+}
+function buildMetricQuery(metricIds, params) {
+  const range = resolveDateRange(params);
+  const values = {
+    dateFrom: range?.from.toISOString(),
+    dateTo: range?.to.toISOString()
+  };
+  const metricClauses = metricIds.map((metricId, index) => {
+    values[`metric${index}`] = metricId;
+    return `event = {metric${index}}`;
+  });
+  const whereClauses = [
+    metricClauses.length ? `(${metricClauses.join(" or ")})` : "",
+    range ? "timestamp >= {dateFrom} and timestamp < {dateTo}" : ""
+  ].filter(Boolean).join(" and ");
+  return {
+    query: [
+      "select",
+      "  event as metric,",
+      "  count() as total",
+      "from events",
+      whereClauses ? `where ${whereClauses}` : "",
+      "group by metric"
+    ].filter(Boolean).join(`
+`),
+    values
+  };
+}
+function buildAggregationQuery(aggregation, params) {
+  const measures = aggregation.measures.map((measure) => ({
+    ...measure,
+    expression: buildMeasureExpression(measure.field, measure.aggregation)
+  }));
+  const dimensions = aggregation.dimensions.map((dimension) => ({
+    ...dimension,
+    expression: buildDimensionExpression(dimension.field, dimension.type, dimension.granularity)
+  }));
+  const selections = [
+    ...dimensions.map((dimension) => `${dimension.expression} as ${dimension.name}`),
+    ...measures.map((measure) => `${measure.expression} as ${measure.name}`)
+  ];
+  const values = {};
+  const filters = buildFilterClauses(aggregation, params, values);
+  const limit = aggregation.limit ?? 100;
+  const orderBy = aggregation.orderBy?.length ? `order by ${aggregation.orderBy.map((order) => `${order.field} ${order.direction}`).join(", ")}` : "";
+  return {
+    query: [
+      "select",
+      `  ${selections.join(`,
+  `)}`,
+      `from ${aggregation.source}`,
+      filters.length ? `where ${filters.join(" and ")}` : "",
+      dimensions.length ? `group by ${dimensions.map((d) => d.name).join(", ")}` : "",
+      orderBy,
+      `limit ${limit}`
+    ].filter(Boolean).join(`
+`),
+    values
+  };
+}
+function buildMeasureExpression(field, aggregation) {
+  switch (aggregation) {
+    case "COUNT":
+      return field === "*" ? "count()" : `count(${field})`;
+    case "COUNT_DISTINCT":
+      return `countDistinct(${field})`;
+    case "SUM":
+      return `sum(${field})`;
+    case "AVG":
+      return `avg(${field})`;
+    case "MIN":
+      return `min(${field})`;
+    case "MAX":
+      return `max(${field})`;
+    default:
+      return `count(${field})`;
+  }
+}
+function buildDimensionExpression(field, type, granularity) {
+  if (type === "TIME") {
+    switch (granularity) {
+      case "HOUR":
+        return `toStartOfHour(${field})`;
+      case "WEEK":
+        return `toStartOfWeek(${field})`;
+      case "MONTH":
+        return `toStartOfMonth(${field})`;
+      case "YEAR":
+        return `toStartOfYear(${field})`;
+      case "DAY":
+      default:
+        return `toStartOfDay(${field})`;
+    }
+  }
+  return field;
+}
+function buildFilterClauses(aggregation, params, values) {
+  const clauses = [];
+  const range = resolveDateRange(params);
+  if (range) {
+    values.dateFrom = range.from.toISOString();
+    values.dateTo = range.to.toISOString();
+    clauses.push(`timestamp >= {dateFrom} and timestamp < {dateTo}`);
+  }
+  aggregation.filters?.forEach((filter, index) => {
+    const key = `filter${index}`;
+    switch (filter.operator) {
+      case "eq":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} = {${key}}`);
+        break;
+      case "neq":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} != {${key}}`);
+        break;
+      case "gt":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} > {${key}}`);
+        break;
+      case "gte":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} >= {${key}}`);
+        break;
+      case "lt":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} < {${key}}`);
+        break;
+      case "lte":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} <= {${key}}`);
+        break;
+      case "contains":
+        values[key] = filter.value;
+        clauses.push(`${filter.field} LIKE '%' || {${key}} || '%'`);
+        break;
+      case "between": {
+        if (Array.isArray(filter.value) && filter.value.length >= 2) {
+          values[`${key}Start`] = filter.value[0];
+          values[`${key}End`] = filter.value[1];
+          clauses.push(`${filter.field} BETWEEN {${key}Start} AND {${key}End}`);
+        }
+        break;
+      }
+      case "in":
+      case "nin":
+        if (Array.isArray(filter.value)) {
+          const placeholders = [];
+          filter.value.forEach((value, valueIndex) => {
+            const valueKey = `${key}_${valueIndex}`;
+            values[valueKey] = value;
+            placeholders.push(`{${valueKey}}`);
+          });
+          if (placeholders.length) {
+            clauses.push(`${filter.field} ${filter.operator === "in" ? "IN" : "NOT IN"} (${placeholders.join(", ")})`);
+          }
+        }
+        break;
+      default:
+        break;
+    }
+  });
+  return clauses;
+}
+function resolveDateRange(params) {
+  const range = params.dateRange;
+  if (!range)
+    return null;
+  return { from: range.start, to: range.end };
+}
+function mapHogqlResult(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return { data: [], columns: [], rowCount: 0 };
+  }
+  const columns = result.columns.map((name) => ({
+    name,
+    type: "STRING"
+  }));
+  const data = result.results.map((row) => {
+    if (!Array.isArray(row))
+      return {};
+    const record = {};
+    result.columns?.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return record;
+  });
+  return {
+    data,
+    columns,
+    rowCount: data.length
+  };
+}
+export {
+  createPosthogQueryEngine,
+  PosthogQueryEngine
+};

package/dist/docs/analytics-dashboard.docblock.d.ts

@@ -1 +1,2 @@
-export { };
+export {};
+//# sourceMappingURL=analytics-dashboard.docblock.d.ts.map

package/dist/docs/analytics-dashboard.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-dashboard.docblock.d.ts","sourceRoot":"","sources":["../../src/docs/analytics-dashboard.docblock.ts"],"names":[],"mappings":""}

package/dist/docs/analytics-dashboard.docblock.js

@@ -1,21 +1,16 @@
+// @bun
+// src/docs/analytics-dashboard.docblock.ts
 import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
-
-//#region src/docs/analytics-dashboard.docblock.ts
-registerDocBlocks([
-	{
-		id: "docs.examples.analytics-dashboard",
-		title: "Analytics Dashboard",
-		summary: "Multi-tenant analytics with dashboards, widgets, query builder, and scheduled reports built on the Event Bus.",
-		kind: "reference",
-		visibility: "public",
-		route: "/docs/examples/analytics-dashboard",
-		tags: [
-			"analytics",
-			"dashboards",
-			"bi",
-			"queries"
-		],
-		body: `## Entities
+var analyticsDashboardDocBlocks = [
+  {
+    id: "docs.examples.analytics-dashboard",
+    title: "Analytics Dashboard",
+    summary: "Multi-tenant analytics with dashboards, widgets, query builder, and scheduled reports built on the Event Bus.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/analytics-dashboard",
+    tags: ["analytics", "dashboards", "bi", "queries"],
+    body: `## Entities
 
 - Dashboard, Widget, Query, Report.
 - Widget/query configs stay declarative for regeneration.
@@ -39,17 +34,18 @@ registerDocBlocks([
 
 - Enforce org scoping for multi-tenant isolation.
 - Use Feature Flags for beta widgets; Metering to track query volume.
+- PostHog datasource can back query execution via HogQL for dashboard widgets.
 `
-	},
-	{
-		id: "docs.examples.analytics-dashboard.goal",
-		title: "Analytics Dashboard — Goal",
-		summary: "Why this template matters and what success looks like.",
-		kind: "goal",
-		visibility: "public",
-		route: "/docs/examples/analytics-dashboard/goal",
-		tags: ["analytics", "goal"],
-		body: `## Why it matters
+  },
+  {
+    id: "docs.examples.analytics-dashboard.goal",
+    title: "Analytics Dashboard \u2014 Goal",
+    summary: "Why this template matters and what success looks like.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/analytics-dashboard/goal",
+    tags: ["analytics", "goal"],
+    body: `## Why it matters
 - Give teams a regenerable analytics workspace that stays in sync with Event Bus, Usage/Metering, and presentations.
 - Avoid dashboard drift by keeping schema-first widgets/queries.
 
@@ -60,16 +56,16 @@ registerDocBlocks([
 ## Success criteria
 - Dashboards can be regenerated safely from spec changes.
 - Queries/widgets have enforced validation; PII is redacted per policy.`
-	},
-	{
-		id: "docs.examples.analytics-dashboard.usage",
-		title: "Analytics Dashboard — Usage",
-		summary: "How to seed, extend, and safely regenerate dashboards.",
-		kind: "usage",
-		visibility: "public",
-		route: "/docs/examples/analytics-dashboard/usage",
-		tags: ["analytics", "usage"],
-		body: `## Setup
+  },
+  {
+    id: "docs.examples.analytics-dashboard.usage",
+    title: "Analytics Dashboard \u2014 Usage",
+    summary: "How to seed, extend, and safely regenerate dashboards.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/analytics-dashboard/usage",
+    tags: ["analytics", "usage"],
+    body: `## Setup
 1) Seed dashboards/widgets (via template registry) to preload sample queries.
 2) Configure org/tenant scope and attach Usage/Metering for cost/sampling controls.
 
@@ -81,20 +77,16 @@ registerDocBlocks([
 ## Guardrails
 - Keep all query inputs validated; mark PII paths in policy.
 - Use Audit Trail for report deliveries; Notifications for scheduled sends.`
-	},
-	{
-		id: "docs.examples.analytics-dashboard.constraints",
-		title: "Analytics Dashboard — Constraints & Safety",
-		summary: "Internal guardrails for queries, widgets, and regeneration.",
-		kind: "reference",
-		visibility: "internal",
-		route: "/docs/examples/analytics-dashboard/constraints",
-		tags: [
-			"analytics",
-			"constraints",
-			"internal"
-		],
-		body: `## Constraints
+  },
+  {
+    id: "docs.examples.analytics-dashboard.constraints",
+    title: "Analytics Dashboard \u2014 Constraints & Safety",
+    summary: "Internal guardrails for queries, widgets, and regeneration.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/analytics-dashboard/constraints",
+    tags: ["analytics", "constraints", "internal"],
+    body: `## Constraints
 - Queries and widgets must declare inputs/validation in spec; no ad-hoc query strings.
 - Regeneration must preserve sampling/windowing semantics; document changes explicitly.
 - Events/usage metrics should remain consistent with Metering/Audit wiring.
@@ -107,8 +99,6 @@ registerDocBlocks([
 - Add fixtures for widget/query schema changes and scheduled reports.
 - Run regeneration diff when adjusting query builders; ensure UI/markdown targets updated.
 - Confirm feature-flagged widgets default to safe/off for new tenants.`
-	}
-]);
-
-//#endregion
-//# sourceMappingURL=analytics-dashboard.docblock.js.map
+  }
+];
+registerDocBlocks(analyticsDashboardDocBlocks);

package/dist/docs/index.d.ts

@@ -1 +1,2 @@
-export { };
+import './analytics-dashboard.docblock';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,gCAAgC,CAAC"}

package/dist/docs/index.js

@@ -1 +1,104 @@
-import "./analytics-dashboard.docblock.js";
+// @bun
+// src/docs/analytics-dashboard.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var analyticsDashboardDocBlocks = [
+  {
+    id: "docs.examples.analytics-dashboard",
+    title: "Analytics Dashboard",
+    summary: "Multi-tenant analytics with dashboards, widgets, query builder, and scheduled reports built on the Event Bus.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/analytics-dashboard",
+    tags: ["analytics", "dashboards", "bi", "queries"],
+    body: `## Entities
+
+- Dashboard, Widget, Query, Report.
+- Widget/query configs stay declarative for regeneration.
+
+## Contracts
+
+- \`analytics.dashboard.create\`, \`analytics.widget.add\`, \`analytics.query.execute\`, \`analytics.dashboard.get\`.
+- Metrics can source from Event Bus schemas and Usage/Metering module.
+
+## Events
+
+- dashboard.created/updated, widget.added, report.scheduled/sent.
+- Emitted for audit + notification hooks.
+
+## UI / Presentations
+
+- Dashboard list, dashboard view, query builder, widget gallery.
+- Registered under \`analytics-dashboard\` template in Template Registry.
+
+## Notes
+
+- Enforce org scoping for multi-tenant isolation.
+- Use Feature Flags for beta widgets; Metering to track query volume.
+- PostHog datasource can back query execution via HogQL for dashboard widgets.
+`
+  },
+  {
+    id: "docs.examples.analytics-dashboard.goal",
+    title: "Analytics Dashboard \u2014 Goal",
+    summary: "Why this template matters and what success looks like.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/analytics-dashboard/goal",
+    tags: ["analytics", "goal"],
+    body: `## Why it matters
+- Give teams a regenerable analytics workspace that stays in sync with Event Bus, Usage/Metering, and presentations.
+- Avoid dashboard drift by keeping schema-first widgets/queries.
+
+## Business/Product goal
+- Deliver tenant-scoped dashboards, governed queries, and scheduled reports with clear ownership and auditability.
+- Enable feature-flagged rollout of new widgets and sampling for cost control.
+
+## Success criteria
+- Dashboards can be regenerated safely from spec changes.
+- Queries/widgets have enforced validation; PII is redacted per policy.`
+  },
+  {
+    id: "docs.examples.analytics-dashboard.usage",
+    title: "Analytics Dashboard \u2014 Usage",
+    summary: "How to seed, extend, and safely regenerate dashboards.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/analytics-dashboard/usage",
+    tags: ["analytics", "usage"],
+    body: `## Setup
+1) Seed dashboards/widgets (via template registry) to preload sample queries.
+2) Configure org/tenant scope and attach Usage/Metering for cost/sampling controls.
+
+## Extend & regenerate
+1) Add or modify widget/query schemas in the spec (inputs, validation, PII paths).
+2) Regenerate to update UI + API + events; review presentations for redaction.
+3) Use Feature Flags to roll out new widgets or sampling knobs gradually.
+
+## Guardrails
+- Keep all query inputs validated; mark PII paths in policy.
+- Use Audit Trail for report deliveries; Notifications for scheduled sends.`
+  },
+  {
+    id: "docs.examples.analytics-dashboard.constraints",
+    title: "Analytics Dashboard \u2014 Constraints & Safety",
+    summary: "Internal guardrails for queries, widgets, and regeneration.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/analytics-dashboard/constraints",
+    tags: ["analytics", "constraints", "internal"],
+    body: `## Constraints
+- Queries and widgets must declare inputs/validation in spec; no ad-hoc query strings.
+- Regeneration must preserve sampling/windowing semantics; document changes explicitly.
+- Events/usage metrics should remain consistent with Metering/Audit wiring.
+
+## PII & Data
+- Mark PII paths (user ids, emails) in presentations for redaction.
+- Avoid exposing raw query payloads in MCP/web without policy checks.
+
+## Verification
+- Add fixtures for widget/query schema changes and scheduled reports.
+- Run regeneration diff when adjusting query builders; ensure UI/markdown targets updated.
+- Confirm feature-flagged widgets default to safe/off for new tenants.`
+  }
+];
+registerDocBlocks(analyticsDashboardDocBlocks);