@vertesia/common 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260806.125520Z

package/src/api-schemas/cost-analytics.contract.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+    CostAnalyticsQuery,
+    CostAnalyticsResponse,
+    CostRunPriceQuery,
+    ModelPriceComparisonResponse,
+} from '../cost-analytics.js';
+import type {
+    CostAnalyticsQuerySchema,
+    CostAnalyticsResponseSchema,
+    CostRunPriceQuerySchema,
+    ModelPriceComparisonResponseSchema,
+} from './cost-analytics.js';
+import { ApiSchemaComponents, validateApiRequest, validateApiResponse } from './registry.js';
+
+describe('cost analytics API contracts', () => {
+    it('derives the public types from the runtime schemas', () => {
+        expectTypeOf<CostAnalyticsQuery>().toEqualTypeOf<import('zod').z.infer<typeof CostAnalyticsQuerySchema>>();
+        expectTypeOf<CostAnalyticsResponse>().toEqualTypeOf<
+            import('zod').z.infer<typeof CostAnalyticsResponseSchema>
+        >();
+        expectTypeOf<CostRunPriceQuery>().toEqualTypeOf<import('zod').z.infer<typeof CostRunPriceQuerySchema>>();
+        expectTypeOf<ModelPriceComparisonResponse>().toEqualTypeOf<
+            import('zod').z.infer<typeof ModelPriceComparisonResponseSchema>
+        >();
+    });
+
+    it('accepts string and epoch time boundaries', () => {
+        expect(validateApiRequest('CostAnalyticsQuery', { from: '2026-08-01T00:00:00Z' }).valid).toBe(true);
+        expect(validateApiRequest('CostAnalyticsQuery', { from: 1_786_060_800_000 }).valid).toBe(true);
+    });
+
+    it('rejects undeclared request fields through the published component', () => {
+        expect(validateApiRequest('CostRunPriceQuery', { run_id: 'run-1', hidden_filter: true }).valid).toBe(false);
+    });
+
+    it('validates the published model-price response', () => {
+        const response: ModelPriceComparisonResponse = {
+            prices: [
+                {
+                    model: 'gpt-5',
+                    source: 'model_pricing_daily',
+                    input_list_price_per_m_tokens: 1.25,
+                },
+            ],
+            effective_range: { from: '2026-08-01', to: '2026-08-02' },
+        };
+        expect(validateApiResponse('ModelPriceComparisonResponse', response).valid).toBe(true);
+    });
+
+    it('registers the complete cost analytics closure', () => {
+        for (const name of [
+            'CostAnalyticsQuery',
+            'CostRunPriceQuery',
+            'CostModelPricesQuery',
+            'CostExportQuery',
+            'CostAnalyticsResponse',
+            'ModelPriceComparisonResponse',
+            'CostRunPriceResponse',
+        ]) {
+            expect(ApiSchemaComponents[name]).toBeDefined();
+        }
+    });
+});

package/src/api-schemas/cost-analytics.ts

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+
+// Zod renders a union as `anyOf`, while the published contract uses JSON Schema's compact type
+// array. Runtime enforcement compiles the emitted JSON Schema with AJV, so the metadata is both the
+// published shape and the validator; the annotation keeps the inferred TypeScript type equally
+// narrow.
+const timeBoundarySchema: z.ZodType<string | number> = z.any().meta({ type: ['string', 'number'] });
+
+export const PricingSyncPayloadSchema = z
+    .strictObject({
+        date: z.string().optional(),
+        backfill_from: z.string().optional(),
+    })
+    .meta({ id: 'PricingSyncPayload' });
+
+export const PricingSyncDayResultSchema = z
+    .strictObject({
+        date: z.string(),
+        gcp_list: z.number(),
+        gcp_effective: z.number(),
+        aws_pricing: z.number(),
+    })
+    .meta({ id: 'PricingSyncDayResult' });
+
+export const PricingSyncResultSchema = z
+    .strictObject({
+        days: z.array(PricingSyncDayResultSchema),
+        total_days: z.number(),
+    })
+    .meta({ id: 'PricingSyncResult' });
+
+export const CostAnalyticsQuerySchema = z
+    .strictObject({
+        from: timeBoundarySchema.meta({ description: 'Start time (ISO string or epoch ms)' }).optional(),
+        to: timeBoundarySchema.meta({ description: 'End time (ISO string or epoch ms)' }).optional(),
+        group_by: z
+            .enum(['model', 'environment', 'account', 'project', 'project_tag', 'provider', 'interaction', 'workflow'])
+            .meta({ description: 'Group results by this dimension' })
+            .optional(),
+        resolution: z.enum(['hour', 'day', 'week', 'month']).meta({ description: 'Time series resolution' }).optional(),
+        model: z.string().meta({ description: 'Filter by model pattern' }).optional(),
+        environment_id: z.string().meta({ description: 'Filter by environment ID' }).optional(),
+        provider: z.string().meta({ description: 'Filter by provider' }).optional(),
+        project_id: z.string().meta({ description: 'Filter by project ID (optional, for org scope)' }).optional(),
+        workflow_id: z.string().meta({ description: 'Filter by workflow / agent run ID' }).optional(),
+        workflow_run_id: z.string().meta({ description: 'Filter by Temporal workflow run ID' }).optional(),
+        run_id: z.string().meta({ description: 'Filter by interaction execution run ID' }).optional(),
+        agent_run_id: z.string().meta({ description: 'Filter by agent run ID' }).optional(),
+        interaction_id: z
+            .string()
+            .meta({ description: 'Filter by interaction id: stored ObjectId or namespaced in-code id' })
+            .optional(),
+        principal_id: z
+            .string()
+            .meta({
+                description:
+                    'Filter by principal (bare user or API key id; matched against the suffix of principal_id)',
+            })
+            .optional(),
+        account_id: z.string().meta({ description: 'Filter by account ID (set automatically by server)' }).optional(),
+        scope: z
+            .enum(['project', 'org'])
+            .meta({ description: "Scope: 'project' (default, current project) or 'org' (all projects in account)" })
+            .optional(),
+        pricing_source: z
+            .enum(['list', 'historical'])
+            .meta({
+                description:
+                    "Pricing source: 'list' (latest daily prices) or 'historical' (daily effective prices over the query range). Default: 'list'",
+            })
+            .optional(),
+        no_cache: z.boolean().meta({ description: 'Skip cache and force fresh query' }).optional(),
+    })
+    .meta({ id: 'CostAnalyticsQuery' });
+
+export const CostRunPriceQuerySchema = z
+    .strictObject({
+        run_id: z.string().meta({ description: 'Interaction execution run ID' }).optional(),
+        agent_run_id: z.string().meta({ description: 'Agent run ID' }).optional(),
+        workflow_id: z.string().meta({ description: 'Workflow ID, when known' }).optional(),
+        workflow_run_id: z.string().meta({ description: 'Temporal workflow run ID, when known' }).optional(),
+        from: timeBoundarySchema.meta({ description: 'Optional lower bound for audit events' }).optional(),
+        to: timeBoundarySchema.meta({ description: 'Optional upper bound for audit events' }).optional(),
+        pricing_source: z
+            .enum(['list', 'historical'])
+            .meta({ description: 'Pricing source. Defaults to historical effective prices for run pricing.' })
+            .optional(),
+        include_comparison_pricing: z
+            .boolean()
+            .meta({ description: 'Include the full pricing catalog for cross-model comparison. Defaults to false.' })
+            .optional(),
+        project_id: z
+            .string()
+            .meta({ description: 'Project filter; server fills current project by default' })
+            .optional(),
+        account_id: z.string().meta({ description: 'Account filter; server fills current account' }).optional(),
+        scope: z
+            .enum(['project', 'org'])
+            .meta({ description: "Scope: 'project' (default, current project) or 'org'" })
+            .optional(),
+    })
+    .meta({ id: 'CostRunPriceQuery' });
+
+export const CostModelPricesQuerySchema = z
+    .object({
+        from: timeBoundarySchema.meta({ description: 'Start time (ISO string or epoch ms)' }).optional(),
+        to: timeBoundarySchema.meta({ description: 'End time (ISO string or epoch ms)' }).optional(),
+    })
+    .meta({ id: 'CostModelPricesQuery' });
+
+export const CostExportQuerySchema = z
+    .object({
+        from: timeBoundarySchema.meta({ description: 'Start time (ISO string or epoch ms)' }).optional(),
+        to: timeBoundarySchema.meta({ description: 'End time (ISO string or epoch ms)' }).optional(),
+        scope: z
+            .enum(['project', 'org'])
+            .meta({ description: "Scope: 'project' (default, current project) or 'org' (all projects in account)" })
+            .optional(),
+        project_id: z.string().meta({ description: 'Filter by project ID (optional, for org scope)' }).optional(),
+        workflow_id: z.string().meta({ description: 'Filter by workflow / agent run ID' }).optional(),
+    })
+    .meta({ id: 'CostExportQuery' });
+
+export const ModelPricingSchema = z
+    .strictObject({
+        model: z.string(),
+        provider: z.string().optional(),
+        provider_account_id: z.string().optional(),
+        input_price_per_m_tokens: z.number(),
+        cached_input_price_per_m_tokens: z.number().optional(),
+        cache_write_input_price_per_m_tokens: z.number().optional(),
+        output_price_per_m_tokens: z.number(),
+        source: z.enum(['billing_export', 'model_pricing_daily', 'unavailable']),
+    })
+    .meta({ id: 'ModelPricing' });
+
+export const CostTimeSeriesPointSchema = z
+    .strictObject({
+        timestamp: z.string(),
+        cost: z.number(),
+        input_tokens: z.number(),
+        cached_input_tokens: z.number().optional(),
+        cache_write_input_tokens: z.number().optional(),
+        output_tokens: z.number(),
+        calls: z.number(),
+    })
+    .meta({ id: 'CostTimeSeriesPoint' });
+
+export const CostSummarySchema = z
+    .strictObject({
+        total_cost: z.number(),
+        total_input_tokens: z.number(),
+        total_cached_input_tokens: z.number().optional(),
+        total_cache_write_input_tokens: z.number().optional(),
+        total_output_tokens: z.number(),
+        total_calls: z.number(),
+        total_duration_ms: z.number(),
+    })
+    .meta({ id: 'CostSummary' });
+
+export const ModelPriceComparisonSchema = z
+    .strictObject({
+        model: z.string(),
+        provider: z.string().optional(),
+        provider_account_id: z.string().optional(),
+        list_price_date: z.string().optional(),
+        effective_from: z.string().optional(),
+        effective_to: z.string().optional(),
+        input_list_price_per_m_tokens: z.number().optional(),
+        input_effective_price_per_m_tokens: z.number().optional(),
+        cached_input_list_price_per_m_tokens: z.number().optional(),
+        cached_input_effective_price_per_m_tokens: z.number().optional(),
+        cache_write_input_list_price_per_m_tokens: z.number().optional(),
+        cache_write_input_effective_price_per_m_tokens: z.number().optional(),
+        output_list_price_per_m_tokens: z.number().optional(),
+        output_effective_price_per_m_tokens: z.number().optional(),
+        source: z.literal('model_pricing_daily'),
+    })
+    .meta({ id: 'ModelPriceComparison' });
+
+export const CostByDimensionSchema = z
+    .strictObject({
+        dimension: z.string(),
+        label: z.string().optional(),
+        provider: z.string().optional(),
+        cost: z.number(),
+        input_tokens: z.number(),
+        cached_input_tokens: z.number().optional(),
+        cache_write_input_tokens: z.number().optional(),
+        output_tokens: z.number(),
+        calls: z.number(),
+        periods: z.array(CostTimeSeriesPointSchema).optional(),
+    })
+    .meta({ id: 'CostByDimension' });
+
+export const ModelPriceComparisonResponseSchema = z
+    .strictObject({
+        prices: z.array(ModelPriceComparisonSchema),
+        effective_range: z.strictObject({
+            from: z.string(),
+            to: z.string(),
+        }),
+        list_price_date: z.string().optional(),
+    })
+    .meta({ id: 'ModelPriceComparisonResponse' });
+
+export const CostAnalyticsResponseSchema = z
+    .strictObject({
+        summary: CostSummarySchema,
+        by_dimension: z.array(CostByDimensionSchema),
+        time_series: z.array(CostTimeSeriesPointSchema),
+        pricing: z.array(ModelPricingSchema),
+        query_range: z.strictObject({
+            from: z.string(),
+            to: z.string(),
+        }),
+        cached: z.boolean(),
+    })
+    .meta({ id: 'CostAnalyticsResponse' });
+
+export const CostRunPriceResponseSchema = z
+    .strictObject({
+        summary: CostSummarySchema,
+        by_model: z.array(CostByDimensionSchema),
+        pricing: z.array(ModelPricingSchema).optional(),
+        query_range: z
+            .strictObject({
+                from: z.string(),
+                to: z.string(),
+            })
+            .optional(),
+        pricing_source: z.enum(['list', 'historical']),
+        matched_events: z.number(),
+    })
+    .meta({ id: 'CostRunPriceResponse' });

package/src/api-schemas/dashboard.contract.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import type { z } from 'zod';
+import type {
+    CreateDashboardPayload,
+    Dashboard,
+    DashboardDataSource,
+    DashboardItem,
+    DashboardStatus,
+    DashboardVersion,
+    UpdateDashboardPayload,
+} from '../data-platform.js';
+import type {
+    CreateDashboardPayloadSchema,
+    DashboardDataSourceSchema,
+    DashboardItemSchema,
+    DashboardSchema,
+    DashboardStatusSchema,
+    DashboardVersionSchema,
+    UpdateDashboardPayloadSchema,
+} from './dashboard.js';
+import { ApiSchemaComponents, validateApiRequest, validateApiResponse } from './registry.js';
+
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+function assertType<T extends true>(_ok: T): void {}
+
+describe('the dashboard public types', () => {
+    it('derive from the runtime schemas instead of restating them', () => {
+        assertType<Equals<DashboardStatus, z.infer<typeof DashboardStatusSchema>>>(true);
+        assertType<Equals<DashboardDataSource, z.infer<typeof DashboardDataSourceSchema>>>(true);
+        assertType<Equals<DashboardItem, z.infer<typeof DashboardItemSchema>>>(true);
+        assertType<Equals<Dashboard, z.infer<typeof DashboardSchema>>>(true);
+        assertType<Equals<DashboardVersion, z.infer<typeof DashboardVersionSchema>>>(true);
+        assertType<Equals<CreateDashboardPayload, z.infer<typeof CreateDashboardPayloadSchema>>>(true);
+        assertType<Equals<UpdateDashboardPayload, z.infer<typeof UpdateDashboardPayloadSchema>>>(true);
+    });
+
+    it('keeps the runtime status values available without importing Zod from the root entry', async () => {
+        const common = await import('../data-platform.js');
+        expect(common.DashboardStatus).toEqual({ ACTIVE: 'active', ARCHIVED: 'archived' });
+    });
+});
+
+describe('dashboard request validation', () => {
+    const create = {
+        name: 'Revenue',
+        dataSource: { kind: 'data_sql', query: 'select * from revenue' },
+        spec: { mark: 'bar' },
+    };
+
+    it('accepts the two documented data-source branches', () => {
+        expect(validateApiRequest('CreateDashboardPayload', create)).toMatchObject({ valid: true });
+        expect(
+            validateApiRequest('CreateDashboardPayload', {
+                ...create,
+                dataSource: { kind: 'store_es_dsl', dsl: { size: 20 }, result: { type: 'hits' } },
+            }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('rejects an unknown data-source discriminator and undeclared payload fields', () => {
+        expect(
+            validateApiRequest('CreateDashboardPayload', {
+                ...create,
+                dataSource: { kind: 'http', url: 'https://example.test/data' },
+            }).valid,
+        ).toBe(false);
+        expect(validateApiRequest('CreateDashboardPayload', { ...create, project: 'ignored-before' }).valid).toBe(
+            false,
+        );
+    });
+
+    it('derives update as the partial create shape plus skip_versioning', () => {
+        expect(validateApiRequest('UpdateDashboardPayload', {})).toMatchObject({ valid: true });
+        expect(validateApiRequest('UpdateDashboardPayload', { spec: { mark: 'line' } })).toMatchObject({
+            valid: true,
+        });
+        expect(validateApiRequest('UpdateDashboardPayload', { skip_versioning: true })).toMatchObject({ valid: true });
+        expect(validateApiRequest('UpdateDashboardPayload', { unknown: true }).valid).toBe(false);
+    });
+
+    it('keeps the two bulk bodies as the free-form string-array map already published', () => {
+        expect(validateApiRequest('StringArrayMap', { ids: ['one', 'two'] })).toMatchObject({ valid: true });
+        expect(validateApiRequest('StringArrayMap', { labels: ['one'] })).toMatchObject({ valid: true });
+        expect(validateApiRequest('StringArrayMap', { ids: 'one' }).valid).toBe(false);
+    });
+});
+
+describe('dashboard response validation', () => {
+    const item = {
+        id: 'dashboard-1',
+        name: 'Revenue',
+        tags: [],
+        updated_by: 'user:editor',
+        created_by: 'user:author',
+        created_at: '2026-08-01T00:00:00.000Z',
+        updated_at: '2026-08-02T00:00:00.000Z',
+        store_id: 'store-1',
+        status: 'active',
+        panel_count: 0,
+        query_count: 0,
+    };
+
+    it('accepts the mapper-produced listing and full response shapes', () => {
+        expect(validateApiResponse('DashboardItem', item)).toMatchObject({ valid: true });
+        expect(
+            validateApiResponse('Dashboard', {
+                ...item,
+                query: 'select * from revenue',
+                spec: { mark: 'bar' },
+                queries: [],
+                panels: [],
+                layout: { columns: 2, cellWidth: 600, cellHeight: 400, padding: 20 },
+            }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('rejects persistence-only fields instead of allowing a document spread to escape', () => {
+        expect(validateApiResponse('DashboardItem', { ...item, account: 'account-1' }).valid).toBe(false);
+    });
+
+    it('registers the complete response closure used by the endpoints', () => {
+        expect(ApiSchemaComponents).toHaveProperty('DashboardItemArray');
+        expect(ApiSchemaComponents).toHaveProperty('DashboardVersionItemArray');
+        expect(ApiSchemaComponents).toHaveProperty('DashboardVersion');
+        expect(ApiSchemaComponents).toHaveProperty('Dashboard');
+    });
+});