@agentmark-ai/api-types 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export { createVerifiedAppId, isTenantContext } from './tenant-context';
+export type { TenantContext } from './tenant-context';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTenantContext = exports.createVerifiedAppId = void 0;
+__exportStar(require("./types"), exports);
+var tenant_context_1 = require("./tenant-context");
+Object.defineProperty(exports, "createVerifiedAppId", { enumerable: true, get: function () { return tenant_context_1.createVerifiedAppId; } });
+Object.defineProperty(exports, "isTenantContext", { enumerable: true, get: function () { return tenant_context_1.isTenantContext; } });

package/dist/tenant-context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tenant Context Types
+ * Feature: 007-analytics-architecture-evaluation
+ *
+ * Provides type-safe tenant context for multi-tenant data access.
+ * Uses branded types to ensure appId can only come from verification.
+ *
+ * NOTE: The verifyAppAccess() function is NOT included here because it
+ * depends on `server-only` and Supabase. It remains in the dashboard app.
+ * This module exports only the types and type guard.
+ */
+import type { VerifiedAppId } from './types';
+/**
+ * Immutable tenant context created after verification.
+ *
+ * All analytics data access methods require this context,
+ * ensuring tenant isolation is enforced at the type level.
+ */
+export interface TenantContext {
+    /** User ID from authentication */
+    readonly userId: string;
+    /** Tenant ID from JWT app_metadata */
+    readonly tenantId: string;
+    /** Verified app ID - guaranteed to belong to tenantId */
+    readonly appId: VerifiedAppId;
+    /** Data retention window in days (-1 = unlimited) */
+    readonly dataRetentionDays: number;
+}
+/**
+ * Creates a VerifiedAppId from a string that has been verified externally
+ * (e.g., by Unkey API key validation or Supabase RLS).
+ *
+ * Performs a runtime check that the value is a non-empty string.
+ * This is the sanctioned way to create a VerifiedAppId in the gateway,
+ * where verification happens via API key middleware rather than verifyAppAccess().
+ *
+ * @throws {Error} if the value is empty or not a string
+ */
+export declare function createVerifiedAppId(appId: string): VerifiedAppId;
+/**
+ * Type guard to check if a value is a valid TenantContext.
+ *
+ * Useful for runtime validation in edge cases.
+ */
+export declare function isTenantContext(value: unknown): value is TenantContext;

package/dist/tenant-context.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Tenant Context Types
+ * Feature: 007-analytics-architecture-evaluation
+ *
+ * Provides type-safe tenant context for multi-tenant data access.
+ * Uses branded types to ensure appId can only come from verification.
+ *
+ * NOTE: The verifyAppAccess() function is NOT included here because it
+ * depends on `server-only` and Supabase. It remains in the dashboard app.
+ * This module exports only the types and type guard.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVerifiedAppId = createVerifiedAppId;
+exports.isTenantContext = isTenantContext;
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Creates a VerifiedAppId from a string that has been verified externally
+ * (e.g., by Unkey API key validation or Supabase RLS).
+ *
+ * Performs a runtime check that the value is a non-empty string.
+ * This is the sanctioned way to create a VerifiedAppId in the gateway,
+ * where verification happens via API key middleware rather than verifyAppAccess().
+ *
+ * @throws {Error} if the value is empty or not a string
+ */
+function createVerifiedAppId(appId) {
+    if (typeof appId !== 'string' || appId.length === 0) {
+        throw new Error('createVerifiedAppId: appId must be a non-empty string');
+    }
+    return appId;
+}
+// ============================================================================
+// Type Guards and Utilities
+// ============================================================================
+/**
+ * Type guard to check if a value is a valid TenantContext.
+ *
+ * Useful for runtime validation in edge cases.
+ */
+function isTenantContext(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.userId === 'string' &&
+        typeof obj.tenantId === 'string' &&
+        typeof obj.appId === 'string' &&
+        typeof obj.dataRetentionDays === 'number' &&
+        obj.userId.length > 0 &&
+        obj.tenantId.length > 0 &&
+        obj.appId.length > 0);
+}

package/dist/types.d.ts

@@ -0,0 +1,847 @@
+/**
+ * Analytics Service Types
+ * Feature: 007-analytics-architecture-evaluation
+ *
+ * These types define the contract for the analytics service layer,
+ * including API request/response shapes and internal data structures.
+ */
+declare const __brand: unique symbol;
+export type VerifiedAppId = string & {
+    readonly [__brand]: 'VerifiedAppId';
+};
+import type { TenantContext } from './tenant-context';
+/**
+ * Date range for analytics queries.
+ * Supports preset ranges or custom date selection.
+ *
+ * App-internal camelCase shape — distinct from api-schemas's wire-format
+ * `DateRangeParamsSchema` (snake_case `start_date` / `end_date`, both
+ * optional). Kept here because no Zod schema describes this exact shape.
+ */
+export interface DateRange {
+    start: string;
+    end: string;
+}
+/**
+ * Preset date range values for quick selection.
+ *
+ * App-internal narrower union — api-schemas's `DateRangePreset` adds
+ * a `'yesterday'` value not used by this surface. Kept local to avoid
+ * loosening consumer expectations.
+ */
+export type DateRangePreset = 'today' | '7d' | '30d' | '90d' | 'custom';
+/**
+ * Standard pagination parameters.
+ *
+ * Sourced from api-schemas's `PaginationParamsSchema` (z.infer<>) —
+ * both packages agree on `{ limit: number; offset: number }`, so the
+ * canonical shape lives in api-schemas and this file re-exports it
+ * to stay in lockstep with the wire contract.
+ */
+import type { PaginationParams as _PaginationParams } from '@agentmark-ai/api-schemas';
+export type PaginationParams = _PaginationParams;
+/**
+ * Summary metrics for the dashboard header.
+ * Aggregated from dashboard_hourly_mv materialized view.
+ */
+export interface MetricsSummary {
+    totalRequests: number;
+    successCount: number;
+    errorCount: number;
+    totalCost: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    avgLatencyMs: number;
+    uniqueUsers: number;
+}
+/**
+ * Time series data point for dashboard charts.
+ * Hourly granularity from dashboard_hourly_mv.
+ */
+export interface TimeSeriesPoint {
+    date: string;
+    hour: number;
+    requests: number;
+    successes: number;
+    errors: number;
+    cost: number;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    avgLatencyMs: number;
+    uniqueUsers: number;
+}
+/**
+ * Complete metrics response including summary and time series.
+ */
+export interface MetricsResponse {
+    summary: MetricsSummary;
+    timeSeries: TimeSeriesPoint[];
+}
+/**
+ * Statistics for a single model.
+ * Aggregated from model_stats_mv materialized view.
+ */
+export interface ModelStats {
+    model: string;
+    requests: number;
+    cost: number;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    avgLatencyMs: number;
+    successRate: number;
+}
+/**
+ * Response for top models query.
+ */
+export interface ModelStatsResponse {
+    models: ModelStats[];
+}
+/**
+ * A single ranking item for dimension-grouped queries.
+ * Used by getRankingData to return data grouped by any dimension
+ * (model, user_id, metadata fields).
+ */
+export interface RankingDataItem {
+    dimensionValue: string;
+    requests: number;
+    cost: number;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    avgLatencyMs: number;
+    successRate: number;
+}
+/**
+ * Response for dimension-grouped ranking queries.
+ */
+export interface RankingDataResponse {
+    items: RankingDataItem[];
+}
+/**
+ * V1 saved filter config — search-only. Retained for backward compat.
+ */
+export interface SavedFilterConfigV1 {
+    search?: string;
+    searchField?: string;
+}
+/**
+ * V2 saved filter config — supports all filter dimensions.
+ */
+export interface SavedFilterConfig {
+    version: 2;
+    filters?: AnalyticsFilter[];
+    userId?: string;
+    dateRange?: {
+        preset?: string;
+        start?: string;
+        end?: string;
+    };
+    sortBy?: {
+        field: string;
+        order: 'asc' | 'desc';
+    };
+}
+/**
+ * Type guard for v2 saved filter configs.
+ */
+export declare function isFilterConfigV2(config: SavedFilterConfigV1 | SavedFilterConfig | SavedViewConfig): config is SavedFilterConfig;
+/**
+ * Display mode for the requests page.
+ */
+export type RequestsDisplayMode = 'list' | 'aggregate';
+/**
+ * V3 saved view config — supports display mode, groupBy, and column visibility.
+ * Used by the Requests page saved views system.
+ */
+export interface SavedViewConfig {
+    version: 3;
+    displayMode: RequestsDisplayMode;
+    groupBy?: string;
+    filters?: AnalyticsFilter[];
+    dateRange?: {
+        preset?: string;
+        start?: string;
+        end?: string;
+    };
+    sortBy?: {
+        field: string;
+        order: 'asc' | 'desc';
+    };
+    columns?: Array<{
+        field: string;
+        visible: boolean;
+    }>;
+}
+/**
+ * Type guard for v3 saved view configs.
+ */
+export declare function isViewConfigV3(config: SavedFilterConfigV1 | SavedFilterConfig | SavedViewConfig): config is SavedViewConfig;
+/**
+ * A single row in the aggregate requests table.
+ * Groups requests by a dimension (model, user_id, metadata key).
+ */
+export interface AggregateRequestsRow {
+    dimensionValue: string;
+    requests: number;
+    cost: number;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    avgLatencyMs: number;
+    successRate: number;
+}
+/**
+ * Paginated response for aggregate requests.
+ */
+export interface AggregateRequestsResponse {
+    items: AggregateRequestsRow[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Parameters for aggregate requests query.
+ */
+export interface AggregateRequestsParams extends PaginationParams {
+    dimension: string;
+    sortField?: string;
+    sortOrder?: 'asc' | 'desc';
+    filters?: AnalyticsFilter[];
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * Parameters for listing traces.
+ */
+export interface TracesParams extends PaginationParams {
+    model?: string;
+    userId?: string;
+    status?: 'OK' | 'ERROR';
+    startDate?: string;
+    endDate?: string;
+    datasetRunId?: string;
+    sessionId?: string;
+    name?: string;
+    tags?: string[];
+    commitSha?: string;
+    filters?: AnalyticsFilter[];
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Summary of a trace for list views.
+ */
+export interface TraceSummary {
+    id: string;
+    name: string;
+    status: string;
+    start: string;
+    end: string;
+    latencyMs: number;
+    cost: number;
+    tokens: number;
+    spanCount: number;
+    tags?: string[];
+}
+/**
+ * Paginated response for trace listing.
+ */
+export interface TracesResponse {
+    traces: TraceSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Individual span within a trace.
+ * Includes all available fields from ClickHouse for trace inspection.
+ */
+export interface Span {
+    id: string;
+    traceId: string;
+    parentId: string | null;
+    name: string;
+    status: string;
+    statusMessage: string;
+    durationMs: number;
+    timestamp: string;
+    type: 'SPAN' | 'GENERATION' | 'EVENT';
+    model: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    tokens: number;
+    cost: number;
+    input: string;
+    output: string;
+    outputObject: string | null;
+    toolCalls: string | null;
+    finishReason: string | null;
+    settings: string | null;
+    reasoningTokens: number;
+    metadata: Record<string, string>;
+    props: string | null;
+    spanKind: string;
+    serviceName: string;
+    promptName: string | null;
+}
+/**
+ * I/O payload for a single span, fetched on demand.
+ */
+export interface SpanIO {
+    input: string;
+    output: string;
+    outputObject: string | null;
+    toolCalls: string | null;
+}
+/**
+ * Complete trace detail with all spans.
+ * spanScores is a map from span ID -> scores for that span,
+ * populated by a parallel batch query against the scores table.
+ */
+export interface TraceDetail {
+    id: string;
+    name: string;
+    status: string;
+    start: string;
+    end: string;
+    latencyMs: number;
+    cost: number;
+    tokens: number;
+    input?: string;
+    output?: string;
+    spans: Span[];
+    /** Eval scores keyed by span ID, batch-fetched in parallel with spans. */
+    spanScores?: Record<string, Score[]>;
+    /** True when the span scores query failed; scores will be empty in that case. */
+    spanScoresError?: boolean;
+}
+/**
+ * Parameters for listing sessions.
+ */
+export interface SessionsParams extends PaginationParams {
+    startDate?: string;
+    endDate?: string;
+    filters?: AnalyticsFilter[];
+    search?: string;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Summary of a session for list views.
+ */
+export interface SessionSummary {
+    id: string;
+    name: string;
+    start: string;
+    end: string;
+    traceCount: number;
+    totalCost: number;
+    totalTokens: number;
+    latencyMs: number;
+    tags?: string[];
+}
+/**
+ * Paginated response for session listing.
+ */
+export interface SessionsResponse {
+    sessions: SessionSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Supported metrics for percentile calculations.
+ *
+ * Sourced from api-schemas's `PERCENTILE_METRICS` const tuple — exact
+ * match for the literal union, so api-types re-exports the canonical
+ * type to keep the two packages in lockstep.
+ */
+import type { PercentileMetric as _PercentileMetric } from '@agentmark-ai/api-schemas';
+export type PercentileMetric = _PercentileMetric;
+/**
+ * Parameters for percentiles query.
+ */
+export interface PercentilesParams {
+    range: DateRangePreset;
+    startDate?: string;
+    endDate?: string;
+    metric: PercentileMetric;
+}
+/**
+ * Percentile data point for time series.
+ */
+export interface PercentilePoint {
+    timestamp: string;
+    p75: number;
+    p90: number;
+    p95: number;
+    p99: number;
+}
+/**
+ * Response for percentiles query.
+ */
+export interface PercentilesResponse {
+    metric: PercentileMetric;
+    data: PercentilePoint[];
+}
+/**
+ * Status of a dependency.
+ */
+export type DependencyStatus = 'up' | 'down';
+/**
+ * Health status of the analytics service.
+ */
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+/**
+ * Health check response.
+ */
+export interface HealthResponse {
+    status: HealthStatus;
+    timestamp: string;
+    dependencies: {
+        clickhouse: {
+            status: DependencyStatus;
+            latencyMs?: number;
+            error?: string;
+        };
+    };
+}
+/**
+ * Summary of a dataset run for list views.
+ * Aggregates data from traces that are part of a dataset evaluation.
+ */
+export interface DatasetRunSummary {
+    id: string;
+    name: string;
+    datasetPath: string;
+    commitSha: string;
+    start: string;
+    end: string;
+    itemCount: number;
+    totalCost: number;
+    totalTokens: number;
+    avgLatencyMs: number;
+    avgScore: number | null;
+}
+/**
+ * Parameters for listing dataset runs.
+ */
+export interface DatasetRunParams extends Partial<PaginationParams> {
+    startDate?: string;
+    endDate?: string;
+    datasetPath?: string;
+}
+/**
+ * Paginated response for dataset runs listing.
+ */
+export interface DatasetRunsResponse {
+    runs: DatasetRunSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Summary of a single item within a dataset run.
+ */
+export interface DatasetItemSummary {
+    id: string;
+    traceId: string;
+    name: string;
+    expectedOutput: string;
+    latencyMs: number;
+    cost: number;
+    tokens: number;
+    score: number | null;
+    status: string;
+}
+/**
+ * Complete dataset run detail with all items.
+ */
+export interface DatasetRunDetail extends DatasetRunSummary {
+    items: DatasetItemSummary[];
+}
+import type { ExperimentItemScore as _ExperimentItemScore, ExperimentSummary as _ExperimentSummary, ExperimentItemSummary as _ExperimentItemSummary, ExperimentDetail as _ExperimentDetail } from '@agentmark-ai/api-schemas';
+export type ExperimentItemScore = _ExperimentItemScore;
+export type ExperimentSummary = _ExperimentSummary;
+export type ExperimentItemSummary = _ExperimentItemSummary;
+export type ExperimentDetail = _ExperimentDetail;
+/**
+ * Parameters for listing experiments.
+ */
+export interface ExperimentParams extends Partial<PaginationParams> {
+    startDate?: string;
+    endDate?: string;
+    promptName?: string;
+    datasetPath?: string;
+}
+/**
+ * Paginated response for experiments listing.
+ */
+export interface ExperimentsResponse {
+    experiments: ExperimentSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+    filterOptions?: {
+        promptNames: string[];
+        datasetPaths: string[];
+    };
+}
+/**
+ * Score record from the scores table.
+ * Scores can be attached to either traces or spans.
+ */
+export interface Score {
+    id: string;
+    resourceId: string;
+    name: string;
+    score: number;
+    label: string;
+    reason: string;
+    source: 'eval' | 'annotation';
+    userId?: string;
+    createdAt: string;
+}
+/**
+ * Parameters for querying scores.
+ */
+export interface ScoresParams extends Partial<PaginationParams> {
+    resourceId?: string;
+    resourceType?: 'trace' | 'span';
+    name?: string;
+    source?: 'eval' | 'annotation';
+    sessionId?: string;
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * Paginated response for scores listing.
+ */
+export interface ScoresResponse {
+    scores: Score[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Aggregated statistics for a score name.
+ */
+export interface ScoreAggregation {
+    name: string;
+    avgScore: number;
+    count: number;
+    minScore: number;
+    maxScore: number;
+}
+/**
+ * Response for score aggregations query.
+ */
+export interface ScoreAggregationsResponse {
+    aggregations: ScoreAggregation[];
+}
+/**
+ * Response for distinct score names query.
+ */
+export interface ScoreNamesResponse {
+    names: string[];
+}
+/**
+ * Detected score type based on data analysis.
+ * - 'numeric': scores with varying float values, no labels
+ * - 'categorical': scores with non-empty string labels (not just true/false)
+ * - 'boolean': scores with labels 'true' and/or 'false' only
+ */
+export type ScoreType = 'numeric' | 'categorical' | 'boolean';
+/**
+ * A single histogram bucket for numeric score distribution.
+ */
+export interface ScoreHistogramBucket {
+    bucket: number;
+    count: number;
+}
+/**
+ * A single category count for categorical/boolean score distribution.
+ */
+export interface ScoreCategoryCount {
+    label: string;
+    count: number;
+}
+/**
+ * Response for score histogram/distribution query.
+ */
+export interface ScoreHistogramResponse {
+    name: string;
+    type: ScoreType;
+    buckets: ScoreHistogramBucket[];
+    categories: ScoreCategoryCount[];
+}
+/**
+ * A single data point in a score trend time series.
+ */
+export interface ScoreTrendPoint {
+    timestamp: string;
+    avgScore: number;
+    count: number;
+}
+/**
+ * Valid trend interval values.
+ *
+ * Sourced from api-schemas's `SCORE_TREND_INTERVALS` const tuple — exact
+ * match for the literal union, so api-types re-exports the canonical
+ * type to keep the two packages in lockstep.
+ */
+import type { ScoreTrendInterval as _ScoreTrendInterval } from '@agentmark-ai/api-schemas';
+export type ScoreTrendInterval = _ScoreTrendInterval;
+/**
+ * Response for score trend query.
+ */
+export interface ScoreTrendResponse {
+    name: string;
+    interval: ScoreTrendInterval;
+    points: ScoreTrendPoint[];
+}
+/**
+ * A cell in the confusion matrix for score comparison.
+ */
+export interface ScoreComparisonCell {
+    labelA: string;
+    labelB: string;
+    count: number;
+}
+/**
+ * Response for score comparison (confusion matrix) query.
+ */
+export interface ScoreComparisonResponse {
+    nameA: string;
+    nameB: string;
+    type: ScoreType;
+    matrix: ScoreComparisonCell[];
+    totalMatched: number;
+    totalA: number;
+    totalB: number;
+}
+/**
+ * A single point in the scatter plot (paired numeric scores).
+ */
+export interface ScoreScatterPoint {
+    scoreA: number;
+    scoreB: number;
+}
+/**
+ * Response for numeric score scatter plot query.
+ */
+export interface ScoreScatterResponse {
+    nameA: string;
+    nameB: string;
+    points: ScoreScatterPoint[];
+    totalMatched: number;
+    totalA: number;
+    totalB: number;
+}
+/**
+ * Filter for analytics queries from the dashboard.
+ * Matches the format used by the filter context.
+ */
+export interface AnalyticsFilter {
+    field: string;
+    operator: string;
+    value: string | string[];
+}
+/**
+ * Supported filter fields for metrics queries.
+ */
+export type MetricsFilterField = 'model' | 'user_id' | 'status';
+/**
+ * Validated filter for metrics queries.
+ * Ensures only supported fields are used.
+ */
+export interface ValidatedMetricsFilter {
+    field: MetricsFilterField;
+    operator: 'equals' | 'notEquals' | 'contains';
+    value: string;
+}
+/**
+ * String comparison operators for filtering.
+ */
+export type StringFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith';
+/**
+ * Number comparison operators for filtering.
+ */
+export type NumberFilterOperator = 'equals' | 'notEquals' | 'lt' | 'lte' | 'gt' | 'gte';
+/**
+ * Combined filter operator type.
+ */
+export type FilterOperator = StringFilterOperator | NumberFilterOperator;
+/**
+ * Filter condition for a string field.
+ */
+export interface StringFilter {
+    operator: StringFilterOperator;
+    value: string;
+}
+/**
+ * Filter condition for a number field.
+ */
+export interface NumberFilter {
+    operator: NumberFilterOperator;
+    value: number;
+}
+/**
+ * Extended trace parameters with advanced filtering support.
+ */
+export interface AdvancedTracesParams extends TracesParams {
+    modelFilter?: StringFilter;
+    userIdFilter?: StringFilter;
+    latencyFilter?: NumberFilter;
+    costFilter?: NumberFilter;
+}
+/**
+ * Extended metrics summary with per-request averages.
+ * Provides additional computed metrics for dashboard display.
+ */
+export interface ExtendedMetricsSummary extends MetricsSummary {
+    avgCostPerRequest: number;
+    avgInputTokensPerRequest: number;
+    avgOutputTokensPerRequest: number;
+    avgTotalTokensPerRequest: number;
+    modelCount: number;
+}
+/**
+ * Extended metrics response with per-request averages.
+ */
+export interface ExtendedMetricsResponse {
+    summary: ExtendedMetricsSummary;
+    timeSeries: TimeSeriesPoint[];
+}
+/**
+ * Filter column definition for the filter popover UI.
+ */
+export interface FilterColumn {
+    field: string;
+    label: string;
+    type: 'string' | 'number' | 'enum';
+    operators: string[];
+    enumValues?: string[];
+}
+/**
+ * Sort configuration.
+ */
+export interface SortConfig {
+    field: string;
+    order: 'asc' | 'desc';
+}
+/**
+ * Date range configuration for saved views.
+ */
+export interface DateRangeConfig {
+    preset: 'today' | '7d' | '30d' | '90d' | 'custom';
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * V4 saved view config — supports traces and sessions pages.
+ * Used by the Traces/Sessions page saved views system.
+ */
+export interface TraceFilterConfig {
+    version: 4;
+    filters?: AnalyticsFilter[];
+    dateRange?: DateRangeConfig;
+    sortBy?: SortConfig;
+    search?: string;
+}
+/**
+ * Analytics service interface.
+ * Defines the contract for analytics data access.
+ *
+ * SECURITY: All methods require TenantContext to ensure both tenantId
+ * and appId are provided, enforcing tenant isolation at compile time.
+ */
+export interface IAnalyticsService {
+    checkConnectivity(): Promise<boolean>;
+    getMetrics(ctx: TenantContext, dateRange: DateRange, filters?: AnalyticsFilter[]): Promise<MetricsResponse>;
+    getExtendedMetrics(ctx: TenantContext, dateRange: DateRange): Promise<ExtendedMetricsResponse>;
+    getModelStats(ctx: TenantContext, dateRange: DateRange, limit?: number, filters?: AnalyticsFilter[]): Promise<ModelStatsResponse>;
+    getTraces(ctx: TenantContext, params: TracesParams): Promise<TracesResponse>;
+    getTraceDetail(ctx: TenantContext, traceId: string): Promise<TraceDetail | null>;
+    getTraceDetailLightweight(ctx: TenantContext, traceId: string): Promise<TraceDetail | null>;
+    getSpanIO(ctx: TenantContext, traceId: string, spanId: string): Promise<SpanIO | null>;
+    getSessions(ctx: TenantContext, params: SessionsParams): Promise<SessionsResponse>;
+    getSessionTraces(ctx: TenantContext, sessionId: string): Promise<TraceDetail[]>;
+    getPercentiles(ctx: TenantContext, params: PercentilesParams, filters?: AnalyticsFilter[]): Promise<PercentilesResponse>;
+    getDatasetRuns(ctx: TenantContext, params: DatasetRunParams): Promise<DatasetRunsResponse>;
+    getDatasetRunDetail(ctx: TenantContext, runId: string): Promise<DatasetRunDetail | null>;
+    getExperiments(ctx: TenantContext, params: ExperimentParams): Promise<ExperimentsResponse>;
+    getExperimentDetail(ctx: TenantContext, experimentId: string): Promise<ExperimentDetail | null>;
+    getScores(ctx: TenantContext, params: ScoresParams): Promise<ScoresResponse>;
+    getScoresBySpanIds(ctx: TenantContext, spanIds: string[]): Promise<Record<string, Score[]>>;
+    getScoreAggregations(ctx: TenantContext, dateRange: DateRange): Promise<ScoreAggregationsResponse>;
+    getDistinctScoreNames(ctx: TenantContext): Promise<ScoreNamesResponse>;
+    detectScoreType(ctx: TenantContext, name: string): Promise<ScoreType>;
+    getScoreHistogram(ctx: TenantContext, name: string, dateRange: DateRange, source?: string): Promise<ScoreHistogramResponse>;
+    getScoreTrend(ctx: TenantContext, name: string, interval: ScoreTrendInterval, dateRange: DateRange, source?: string): Promise<ScoreTrendResponse>;
+    getScoreComparison(ctx: TenantContext, nameA: string, nameB: string, dateRange: DateRange, source?: string): Promise<ScoreComparisonResponse>;
+    getScoreScatter(ctx: TenantContext, nameA: string, nameB: string, dateRange: DateRange, source?: string): Promise<ScoreScatterResponse>;
+    getDistinctMetadataKeys(ctx: TenantContext): Promise<string[]>;
+    getPromptLogs(ctx: TenantContext, params: PromptLogsParams): Promise<PromptLogsResponse>;
+    getRankingData(ctx: TenantContext, dateRange: DateRange, dimension: string, limit?: number, filters?: AnalyticsFilter[]): Promise<RankingDataResponse>;
+    getAggregateRequests(ctx: TenantContext, params: AggregateRequestsParams): Promise<AggregateRequestsResponse>;
+    getSpanKindBreakdown(ctx: TenantContext, dateRange: {
+        startDate: string;
+        endDate: string;
+    }): Promise<SpanKindBreakdownRecord[]>;
+}
+export interface SpanKindBreakdownRecord {
+    kind: string;
+    count: number;
+    avgLatencyMs: number;
+    totalCost: number;
+    totalTokens: number;
+}
+/**
+ * Parameters for listing prompt logs.
+ */
+export interface PromptLogsParams extends PaginationParams {
+    startDate?: string;
+    endDate?: string;
+    model?: string;
+    userId?: string;
+    status?: 'OK' | 'ERROR';
+    sortField?: string;
+    sortOrder?: 'asc' | 'desc';
+    filters?: AnalyticsFilter[];
+}
+/**
+ * Prompt log record (GENERATION type trace with input/output).
+ */
+export interface PromptLogRecord {
+    id: string;
+    tenantId: string;
+    appId: string;
+    cost: number;
+    promptTokens: number;
+    completionTokens: number;
+    latencyMs: number;
+    modelUsed: string;
+    status: string;
+    input: string;
+    output: string | null;
+    ts: string;
+    userId: string;
+    promptName: string;
+    traceId: string;
+    statusMessage: string;
+    props: string;
+}
+/**
+ * Paginated response for prompt logs listing.
+ */
+export interface PromptLogsResponse {
+    logs: PromptLogRecord[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Analytics Service Types
+ * Feature: 007-analytics-architecture-evaluation
+ *
+ * These types define the contract for the analytics service layer,
+ * including API request/response shapes and internal data structures.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFilterConfigV2 = isFilterConfigV2;
+exports.isViewConfigV3 = isViewConfigV3;
+/**
+ * Type guard for v2 saved filter configs.
+ */
+function isFilterConfigV2(config) {
+    return 'version' in config && config.version === 2;
+}
+/**
+ * Type guard for v3 saved view configs.
+ */
+function isViewConfigV3(config) {
+    return 'version' in config && config.version === 3;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@agentmark-ai/api-types",
+  "version": "0.1.0",
+  "description": "Shared API contract types for AgentMark services",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@agentmark-ai/api-schemas": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.3"
+  }
+}