@contractspec/example.analytics-dashboard 1.57.0 → 1.59.0

package/dist/browser/handlers/index.js

@@ -0,0 +1,571 @@
+// 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
+  };
+}
+
+// src/handlers/analytics.handlers.ts
+import { web } from "@contractspec/lib.runtime-sandbox";
+var { generateId } = web;
+function rowToDashboard(row) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    slug: row.slug,
+    description: row.description ?? undefined,
+    status: row.status,
+    refreshInterval: row.refreshInterval,
+    isPublic: row.isPublic === 1,
+    shareToken: row.shareToken ?? undefined,
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt)
+  };
+}
+function rowToWidget(row) {
+  return {
+    id: row.id,
+    dashboardId: row.dashboardId,
+    name: row.name,
+    type: row.type,
+    gridX: row.gridX,
+    gridY: row.gridY,
+    gridWidth: row.gridWidth,
+    gridHeight: row.gridHeight,
+    queryId: row.queryId ?? undefined,
+    config: row.config ? JSON.parse(row.config) : undefined,
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt)
+  };
+}
+function rowToQuery(row) {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    type: row.type,
+    definition: JSON.parse(row.definition),
+    sql: row.sql ?? undefined,
+    cacheTtlSeconds: row.cacheTtlSeconds,
+    isShared: row.isShared === 1,
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt)
+  };
+}
+function createAnalyticsHandlers(db) {
+  async function listDashboards(input) {
+    const { projectId, status, search, limit = 20, offset = 0 } = input;
+    let whereClause = "WHERE projectId = ?";
+    const params = [projectId];
+    if (status && status !== "all") {
+      whereClause += " AND status = ?";
+      params.push(status);
+    }
+    if (search) {
+      whereClause += " AND (name LIKE ? OR description LIKE ?)";
+      params.push(`%${search}%`, `%${search}%`);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM analytics_dashboard ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    const rows = (await db.query(`SELECT * FROM analytics_dashboard ${whereClause} ORDER BY updatedAt DESC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      dashboards: rows.map(rowToDashboard),
+      total
+    };
+  }
+  async function createDashboard(input, context) {
+    const id = generateId("dash");
+    const now = new Date().toISOString();
+    await db.execute(`INSERT INTO analytics_dashboard (id, projectId, organizationId, name, slug, description, status, refreshInterval, isPublic, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      context.projectId,
+      context.organizationId,
+      input.name,
+      input.slug,
+      input.description ?? null,
+      "DRAFT",
+      input.refreshInterval ?? "NONE",
+      0,
+      now,
+      now
+    ]);
+    const rows = (await db.query(`SELECT * FROM analytics_dashboard WHERE id = ?`, [id])).rows;
+    return rowToDashboard(rows[0]);
+  }
+  async function getDashboard(input) {
+    let whereClause = "";
+    const params = [];
+    if (input.dashboardId) {
+      whereClause = "WHERE id = ?";
+      params.push(input.dashboardId);
+    } else if (input.slug) {
+      whereClause = "WHERE slug = ?";
+      params.push(input.slug);
+    } else if (input.shareToken) {
+      whereClause = "WHERE shareToken = ?";
+      params.push(input.shareToken);
+    } else {
+      return null;
+    }
+    const rows = (await db.query(`SELECT * FROM analytics_dashboard ${whereClause}`, params)).rows;
+    return rows[0] ? rowToDashboard(rows[0]) : null;
+  }
+  async function updateDashboard(dashboardId, updates) {
+    const now = new Date().toISOString();
+    const setClauses = ["updatedAt = ?"];
+    const params = [now];
+    if (updates.name !== undefined) {
+      setClauses.push("name = ?");
+      params.push(updates.name);
+    }
+    if (updates.description !== undefined) {
+      setClauses.push("description = ?");
+      params.push(updates.description);
+    }
+    if (updates.status !== undefined) {
+      setClauses.push("status = ?");
+      params.push(updates.status);
+    }
+    if (updates.refreshInterval !== undefined) {
+      setClauses.push("refreshInterval = ?");
+      params.push(updates.refreshInterval);
+    }
+    if (updates.isPublic !== undefined) {
+      setClauses.push("isPublic = ?");
+      params.push(updates.isPublic ? 1 : 0);
+      if (updates.isPublic) {
+        setClauses.push("shareToken = ?");
+        params.push(generateId("share"));
+      } else {
+        setClauses.push("shareToken = NULL");
+      }
+    }
+    params.push(dashboardId);
+    await db.execute(`UPDATE analytics_dashboard SET ${setClauses.join(", ")} WHERE id = ?`, params);
+    const rows = (await db.query(`SELECT * FROM analytics_dashboard WHERE id = ?`, [
+      dashboardId
+    ])).rows;
+    return rowToDashboard(rows[0]);
+  }
+  async function getWidgets(dashboardId) {
+    const rows = (await db.query(`SELECT * FROM analytics_widget WHERE dashboardId = ? ORDER BY gridY, gridX`, [dashboardId])).rows;
+    return rows.map(rowToWidget);
+  }
+  async function addWidget(input) {
+    const id = generateId("widget");
+    const now = new Date().toISOString();
+    await db.execute(`INSERT INTO analytics_widget (id, dashboardId, name, type, gridX, gridY, gridWidth, gridHeight, queryId, config, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      input.dashboardId,
+      input.name,
+      input.type,
+      input.gridX ?? 0,
+      input.gridY ?? 0,
+      input.gridWidth ?? 6,
+      input.gridHeight ?? 4,
+      input.queryId ?? null,
+      input.config ? JSON.stringify(input.config) : null,
+      now,
+      now
+    ]);
+    const rows = (await db.query(`SELECT * FROM analytics_widget WHERE id = ?`, [id])).rows;
+    return rowToWidget(rows[0]);
+  }
+  async function updateWidget(widgetId, updates) {
+    const now = new Date().toISOString();
+    const setClauses = ["updatedAt = ?"];
+    const params = [now];
+    if (updates.name !== undefined) {
+      setClauses.push("name = ?");
+      params.push(updates.name);
+    }
+    if (updates.gridX !== undefined) {
+      setClauses.push("gridX = ?");
+      params.push(updates.gridX);
+    }
+    if (updates.gridY !== undefined) {
+      setClauses.push("gridY = ?");
+      params.push(updates.gridY);
+    }
+    if (updates.gridWidth !== undefined) {
+      setClauses.push("gridWidth = ?");
+      params.push(updates.gridWidth);
+    }
+    if (updates.gridHeight !== undefined) {
+      setClauses.push("gridHeight = ?");
+      params.push(updates.gridHeight);
+    }
+    if (updates.queryId !== undefined) {
+      setClauses.push("queryId = ?");
+      params.push(updates.queryId ?? null);
+    }
+    if (updates.config !== undefined) {
+      setClauses.push("config = ?");
+      params.push(updates.config ? JSON.stringify(updates.config) : null);
+    }
+    params.push(widgetId);
+    await db.execute(`UPDATE analytics_widget SET ${setClauses.join(", ")} WHERE id = ?`, params);
+    const rows = (await db.query(`SELECT * FROM analytics_widget WHERE id = ?`, [widgetId])).rows;
+    return rowToWidget(rows[0]);
+  }
+  async function deleteWidget(widgetId) {
+    await db.execute(`DELETE FROM analytics_widget WHERE id = ?`, [widgetId]);
+  }
+  async function listQueries(input) {
+    const { projectId, type, isShared, search, limit = 20, offset = 0 } = input;
+    let whereClause = "WHERE projectId = ?";
+    const params = [projectId];
+    if (type && type !== "all") {
+      whereClause += " AND type = ?";
+      params.push(type);
+    }
+    if (isShared !== undefined) {
+      whereClause += " AND isShared = ?";
+      params.push(isShared ? 1 : 0);
+    }
+    if (search) {
+      whereClause += " AND (name LIKE ? OR description LIKE ?)";
+      params.push(`%${search}%`, `%${search}%`);
+    }
+    const countResult = (await db.query(`SELECT COUNT(*) as count FROM analytics_query ${whereClause}`, params)).rows;
+    const total = countResult[0]?.count ?? 0;
+    const rows = (await db.query(`SELECT * FROM analytics_query ${whereClause} ORDER BY updatedAt DESC LIMIT ? OFFSET ?`, [...params, limit, offset])).rows;
+    return {
+      queries: rows.map(rowToQuery),
+      total
+    };
+  }
+  async function createQuery(input, context) {
+    const id = generateId("query");
+    const now = new Date().toISOString();
+    await db.execute(`INSERT INTO analytics_query (id, projectId, organizationId, name, description, type, definition, sql, cacheTtlSeconds, isShared, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      context.projectId,
+      context.organizationId,
+      input.name,
+      input.description ?? null,
+      input.type,
+      JSON.stringify(input.definition),
+      input.sql ?? null,
+      input.cacheTtlSeconds ?? 300,
+      input.isShared ? 1 : 0,
+      now,
+      now
+    ]);
+    const rows = (await db.query(`SELECT * FROM analytics_query WHERE id = ?`, [id])).rows;
+    return rowToQuery(rows[0]);
+  }
+  async function getQuery(queryId) {
+    const rows = (await db.query(`SELECT * FROM analytics_query WHERE id = ?`, [queryId])).rows;
+    return rows[0] ? rowToQuery(rows[0]) : null;
+  }
+  return {
+    listDashboards,
+    createDashboard,
+    getDashboard,
+    updateDashboard,
+    getWidgets,
+    addWidget,
+    updateWidget,
+    deleteWidget,
+    listQueries,
+    createQuery,
+    getQuery
+  };
+}
+
+// src/handlers/query.handlers.ts
+async function executePosthogQuery(input) {
+  const engine = createPosthogQueryEngine(input.reader);
+  return engine.execute(input.definition, input.params);
+}
+export {
+  executePosthogQuery,
+  createAnalyticsHandlers
+};