@vertesia/common 1.5.0-dev.20260714.072725Z → 1.5.0-dev.20260722.120446Z

package/src/audit-trail.ts

@@ -19,6 +19,8 @@ export const AUDIT_ACTIONS = [
     'inference',
     'embedding',
     'image_generation',
+    // Content processing outcomes
+    'document_processed',
 ] as const;
 
 export type KnownAuditAction = (typeof AUDIT_ACTIONS)[number];
@@ -113,3 +115,84 @@ export interface AuditTrailResponse {
     limit: number;
     offset: number;
 }
+
+export const AUDIT_AGGREGATION_DIMENSIONS = [
+    'time',
+    'action',
+    'resource_type',
+    'event_category',
+    'provider',
+    'project_id',
+    'details.pipeline',
+    'details.verdict',
+    'details.workflow_type',
+    'details.rule_id',
+    'model',
+] as const;
+
+export type AuditAggregationDimension = (typeof AUDIT_AGGREGATION_DIMENSIONS)[number];
+export type AuditAggregationResolution = 'hour' | 'day' | 'week' | 'month';
+export type AuditAggregationDetailField = 'pipeline' | 'verdict' | 'workflow_type' | 'rule_id';
+export type AuditAggregationOperation = 'count' | 'count_distinct' | 'sum_meter' | 'average_meter';
+export type AuditAggregationDistinctField = 'resource_id' | 'request_id';
+
+export interface AuditAggregationGroup {
+    dimension: AuditAggregationDimension;
+    /** Required for the time dimension; defaults to day. */
+    resolution?: AuditAggregationResolution;
+}
+
+export interface AuditAggregationMetric {
+    /** Stable key used in response rows. Must contain only letters, numbers, underscores, or hyphens. */
+    id: string;
+    operation: AuditAggregationOperation;
+    /** Required for count_distinct. */
+    field?: AuditAggregationDistinctField;
+    /** Required for meter operations. */
+    meterCategory?: string;
+    /** Required for meter operations. */
+    meterType?: string;
+}
+
+export interface AuditAggregationDetailFilter {
+    field: AuditAggregationDetailField;
+    values: string[];
+}
+
+export interface AuditAggregationFilter {
+    actions?: AuditAction[];
+    resourceTypes?: string[];
+    eventCategories?: EventCategory[];
+    providers?: string[];
+    success?: boolean;
+    details?: AuditAggregationDetailFilter[];
+}
+
+/**
+ * Safe audit aggregation query. The server always applies the authenticated account scope and,
+ * for project-scoped principals, replaces projectId with the authenticated project.
+ */
+export interface AuditAggregationQuery {
+    /** Optional account-admin project filter. Ignored for project-scoped principals. */
+    projectId?: string;
+    /** Start time; defaults to 30 days before to. The server caps the range at 366 days. */
+    from?: string;
+    /** End time; defaults to the current time. */
+    to?: string;
+    filter?: AuditAggregationFilter;
+    groupBy?: AuditAggregationGroup[];
+    metrics: AuditAggregationMetric[];
+    /** Maximum groups returned (default 50, max 200). */
+    limit?: number;
+}
+
+export interface AuditAggregationRow {
+    dimensions: Partial<Record<AuditAggregationDimension, string | null>>;
+    metrics: Record<string, number>;
+}
+
+export interface AuditAggregationResponse {
+    rows: AuditAggregationRow[];
+    from: string;
+    to: string;
+}

package/src/data-platform.ts

@@ -851,6 +851,99 @@ export interface DashboardQueryParameters {
     defaults: Record<string, string>;
 }
 
+/**
+ * Elasticsearch DSL supported by dashboard data sources.
+ * Queries execute through Vertesia Store, so project/security filtering remains server-side.
+ */
+export interface DashboardElasticsearchDsl {
+    query?: Record<string, unknown>;
+    aggs?: Record<string, unknown>;
+    size?: number;
+    from?: number;
+    sort?: Array<Record<string, unknown>>;
+}
+
+/**
+ * How an Elasticsearch DSL result should be converted into Vega rows.
+ */
+export type DashboardElasticsearchResultMapping =
+    | {
+          type: 'hits';
+      }
+    | {
+          type: 'aggregation_buckets';
+          /** Dot path under `aggregations` that contains a `buckets` array. */
+          path: string;
+          /** Output field name for bucket key. Defaults to `key`. */
+          keyField?: string;
+          /** Output field name for doc count. Defaults to `doc_count`. */
+          countField?: string;
+      };
+
+/**
+ * Dashboard data source backed by a Data Platform SQL query.
+ */
+export interface DashboardSqlDataSource {
+    kind: 'data_sql';
+    /** SQL query that returns all rows for the dashboard. */
+    query: string;
+    /** Maximum rows to return from the query. */
+    queryLimit?: number;
+    /** Default values for SQL {{param}} placeholders. */
+    queryParameters?: Record<string, string>;
+}
+
+/**
+ * Dashboard data source backed by Vertesia Store Elasticsearch DSL.
+ */
+export interface DashboardStoreElasticsearchDataSource {
+    kind: 'store_es_dsl';
+    /** Elasticsearch DSL query executed through the secured Store query API. */
+    dsl: DashboardElasticsearchDsl;
+    /** Result mapping. Defaults to `hits`. */
+    result?: DashboardElasticsearchResultMapping;
+}
+
+/**
+ * Data source for a Vega dashboard.
+ */
+export type DashboardDataSource = DashboardSqlDataSource | DashboardStoreElasticsearchDataSource;
+
+/**
+ * Dashboard definition contributed by an app package.
+ *
+ * App dashboard IDs are local to the app. The platform exposes them as
+ * `app:<app_name>:<id>` when listing or retrieving dashboards.
+ */
+export interface AppDashboardDefinition {
+    /** Local app dashboard ID. */
+    id: string;
+    /** Machine-friendly dashboard name. Defaults to `id`. */
+    name?: string;
+    /** Display title. Defaults to `name` or `id`. */
+    title?: string;
+    /** User-facing description. */
+    description?: string;
+    /** Tags for discovery and filtering. */
+    tags?: string[];
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query shortcut for app dashboards backed by data stores. */
+    query?: string;
+    /** Maximum SQL rows to return. */
+    queryLimit?: number;
+    /** Default values for SQL {{param}} placeholders. */
+    queryParameters?: Record<string, string>;
+    /** Complete Vega-Lite specification for the dashboard. */
+    spec?: Record<string, unknown>;
+    /** Legacy named SQL queries. */
+    queries?: DashboardQuery[];
+    /** Legacy panel definitions. */
+    panels?: DashboardPanel[];
+    /** Legacy dashboard layout. */
+    layout?: DashboardLayout;
+}
+
 /**
  * Summary view of a dashboard (for listings).
  */
@@ -867,15 +960,22 @@ export interface DashboardItem extends BaseObject {
     last_rendered_at?: string;
     /** Tags for organization */
     tags: string[];
+    /** Source of the dashboard definition. Defaults to stored dashboards. */
+    source?: 'stored' | 'app';
+    /** App name when `source` is `app`. */
+    app_name?: string;
+    /** App dashboards are read-only until cloned into a stored dashboard. */
+    readonly?: boolean;
 }
 
 /**
  * Full dashboard with SQL query and Vega-Lite specification.
  *
  * **New architecture (v2):**
- * - Single `query` field with SQL (use JOINs/CTEs for complex data needs)
+ * - `dataSource` field with either SQL or Store Elasticsearch DSL
  * - Single `spec` field with complete Vega-Lite spec (vconcat/hconcat for multiple panels)
  * - Cross-panel interactivity via Vega selections
+ * - Legacy top-level `query` fields are treated as a SQL data source
  *
  * **Legacy architecture (v1, deprecated):**
  * - Multiple `queries` with named data sources
@@ -885,18 +985,26 @@ export interface DashboardItem extends BaseObject {
  */
 export interface Dashboard extends DashboardItem {
     // ============= New architecture (v2) =============
+    /**
+     * Data source used to populate Vega `data.values`.
+     * When omitted, top-level `query` is treated as a SQL data source for backwards compatibility.
+     */
+    dataSource?: DashboardDataSource;
     /**
      * SQL query that returns all data for the dashboard.
      * Use JOINs, CTEs, or UNION ALL to combine data from multiple tables.
      * Can include {{param_name}} placeholders for dynamic values.
+     * @deprecated Use `dataSource: { kind: 'data_sql', query }` instead.
      */
     query?: string;
     /**
      * Maximum rows to return from the query (default: 10000).
+     * @deprecated Use `dataSource.queryLimit` instead.
      */
     queryLimit?: number;
     /**
      * Default values for SQL parameters.
+     * @deprecated Use `dataSource.queryParameters` instead.
      */
     queryParameters?: Record<string, string>;
     /**
@@ -930,15 +1038,17 @@ export interface Dashboard extends DashboardItem {
 
 /**
  * Payload for creating a new dashboard.
- * Requires query (SQL) and spec (Vega-Lite).
+ * Requires a data source and spec (Vega-Lite).
  */
 export interface CreateDashboardPayload {
     /** Dashboard name (unique within store) */
     name: string;
     /** Dashboard summary */
     summary?: string;
-    /** SQL query that returns all data for the dashboard */
-    query: string;
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard. Deprecated shortcut for a SQL data source. */
+    query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
     /** Default values for SQL {{param}} placeholders */
@@ -955,7 +1065,9 @@ export interface UpdateDashboardPayload {
     name?: string;
     /** Dashboard summary */
     summary?: string;
-    /** SQL query that returns all data for the dashboard */
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard. Deprecated shortcut for a SQL data source. */
     query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
@@ -972,6 +1084,8 @@ export interface UpdateDashboardPayload {
  */
 export interface PreviewDashboardPayload {
     // ============= New architecture (v2) =============
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
     /** SQL query that returns all data for the dashboard */
     query?: string;
     /** Maximum rows to return from the query (default: 10000) */
@@ -1035,6 +1149,16 @@ export interface DashboardVersion {
     version_number: number;
     /** Commit message describing the change */
     message: string;
+    /** Snapshot of v2 data source at this version */
+    dataSource?: DashboardDataSource;
+    /** Snapshot of v2 SQL query at this version */
+    query?: string;
+    /** Snapshot of v2 query limit at this version */
+    queryLimit?: number;
+    /** Snapshot of v2 query parameters at this version */
+    queryParameters?: Record<string, string>;
+    /** Snapshot of v2 Vega-Lite spec at this version */
+    spec?: Record<string, unknown>;
     /** Snapshot of queries at this version */
     queries: DashboardQuery[];
     /** Snapshot of panels at this version */

package/src/index.ts

@@ -37,6 +37,7 @@ export * from './rate-limiter.js';
 export * from './refs.js';
 export * from './roles/types.js';
 export * from './runs.js';
+export * from './schema-for-extraction.js';
 export * from './secrets.js';
 export * from './skill.js';
 export * from './store/index.js';
@@ -74,4 +75,15 @@ export * from './utils/auth.js';
 export * from './utils/schemas.js';
 export type * from './utils/type-helpers.js';
 export * from './versions.js';
+export * from './view-configuration-validation.js';
+export * from './view-query-validation.js';
+export * from './view-validation-helpers.js';
+export * from './views.js';
+export * from './views-schema.js';
+export {
+    type AppViewExperienceId,
+    parseAppViewExperienceId,
+    type ViewValidationIssue,
+    validateViewExperienceId,
+} from './views-validation.js';
 export * from './workflow-analytics.js';

package/src/interaction.ts

@@ -26,7 +26,7 @@ import type {
 } from './prompt.js';
 import type { ExecutionRunDocRef } from './runs.js';
 import type { AgentToolApprovalMode } from './store/agent-approval.js';
-import type { ConversationState } from './store/conversation-state.js';
+import type { ConversationState, TextArtifactReference } from './store/conversation-state.js';
 import type { AccountRef } from './user.js';
 import type { LlmCallType } from './workflow-analytics.js';
 
@@ -895,6 +895,8 @@ export interface ResultStorageOptions {
     // - Otherwise → text/markdown or text/plain
 }
 
+export type AsyncCompletionMode = 'conversation_state' | 'text';
+
 /**
  * Streaming-specific options (only needed when stream=true)
  */
@@ -950,6 +952,13 @@ export interface AsyncCompletionOptions {
      * after inference completes (before completing the Temporal activity).
      */
     result_storage?: ResultStorageOptions;
+    /**
+     * Controls the value used to complete the Temporal activity.
+     * Defaults to `conversation_state` for agent resume/continuation calls.
+     * Use `text` for one-shot helper calls, such as checkpoint summaries,
+     * that need the model's text result instead of merged conversation state.
+     */
+    completion_mode?: AsyncCompletionMode;
 }
 
 interface ResumeConversationPayload {
@@ -966,6 +975,12 @@ interface ResumeConversationPayload {
 
 export interface ToolResultContent {
     content: string;
+    /**
+     * Reference to text content stored outside Temporal/API payloads. Servers that
+     * execute the next model turn should resolve this before constructing the
+     * provider prompt.
+     */
+    content_ref?: TextArtifactReference;
     is_error: boolean;
     files?: string[];
     /**
@@ -1181,6 +1196,10 @@ export interface InteractionExecutionConfiguration {
     run_data?: RunDataStorageLevel;
     configMode?: ConfigModes;
     model_options?: ModelOptions;
+    /** Stable provider-side routing key for automatic prompt caching. */
+    prompt_cache_key?: string;
+    /** Put the result schema after the cached prefix; Vertesia still validates the returned JSON against it. */
+    prompt_cache_schema_suffix?: boolean;
     /** Per-run HTTP timeouts for upstream LLM-provider calls. */
     http_timeout?: HttpTimeoutOptions;
 }

package/src/json-schema.ts

@@ -2,7 +2,6 @@ export type {
     JSONSchema,
     JSONSchemaArray,
     JSONSchemaObject,
-    JSONSchemaProperties,
     JSONSchemaType,
     JSONSchemaTypeName,
 } from '@llumiverse/common';

package/src/platform-event.ts

@@ -3,6 +3,7 @@ import type { ConversationVisibility, InteractionExecutionConfiguration } from '
 import type { SystemRoles } from './project.js';
 import type {
     AgentRunStatus,
+    GroundedVerificationBreakdown,
     JsonLogicRule,
     ProcessDefinitionBody,
     ProcessRunType,
@@ -81,12 +82,44 @@ export interface PlatformEvent extends EventRef {
  */
 export type WorkflowLifecycleAction = 'workflow_completed' | 'workflow_failed';
 
+export interface DocumentProcessingModelUsage {
+    role: 'extraction' | 'review';
+    run_id: string;
+    model?: string;
+    environment_id?: string;
+    provider?: string;
+}
+
+/** Compact, content-free operational summary emitted after grounded IDP completes. */
+export interface DocumentProcessedEventData {
+    schema_version: 1;
+    pipeline: 'grounded_extraction';
+    object_id: string;
+    page_count: number;
+    ocr_page_count: number;
+    vision_page_count: number;
+    property_count: number;
+    citation_count: number;
+    verification: GroundedVerificationBreakdown;
+    result_path: string;
+    confidence?: number;
+    coverage_min?: number;
+    hardness?: number;
+    escalated?: boolean;
+    reviewed?: boolean;
+    review_issue_count?: number;
+    verdict?: 'good_to_go' | 'needs_review';
+    verdict_reason?: string;
+    models_used?: DocumentProcessingModelUsage[];
+    review_agent_run_id?: string;
+}
+
 /**
  * Resource flavor of a workflow lifecycle event, derived from the Temporal workflow type:
  * ExecuteConversationWorkflow -> agent_run, ExecuteProcessWorkflow -> process_run,
- * anything else -> workflow_run.
+ * document-scoped workflows may use content_object, and anything else -> workflow_run.
  */
-export type WorkflowLifecycleResourceType = 'workflow_run' | 'agent_run' | 'process_run';
+export type WorkflowLifecycleResourceType = 'workflow_run' | 'agent_run' | 'process_run' | 'content_object';
 
 /**
  * Body of POST /internal/events/publish (zeno-server, workload-identity gated). Sent by Temporal
@@ -98,6 +131,8 @@ export interface PublishWorkflowLifecycleEventRequest {
     project_id: string;
     action: WorkflowLifecycleAction;
     resource_type: WorkflowLifecycleResourceType;
+    /** Domain resource the workflow acted on. Defaults to workflow_id for workflow-scoped events. */
+    resource_id?: string;
     workflow_id: string;
     workflow_run_id: string;
     workflow_type: string;
@@ -110,6 +145,8 @@ export interface PublishWorkflowLifecycleEventRequest {
     error?: string;
     /** EventRef of the event that started the workflow (payload.vars.event_ref), if any. */
     caused_by?: EventRef;
+    /** Optional IDP outcome published as a separate, subscribable content event. */
+    document_processed?: DocumentProcessedEventData;
 }
 
 /**
@@ -489,6 +526,59 @@ export interface ListEventDeliveriesResponse {
     deliveries: EventDeliverySummary[];
 }
 
+export interface StreamEventDeliveriesQuery {
+    limit?: number;
+    event_id?: string;
+    resource_id?: string;
+    resource_type?: string[];
+    event_category?: EventCategory[];
+    action?: string[];
+    outbox_status?: EventOutboxStatus[];
+    since_event_id?: string;
+    since_created_at?: string;
+    include_event?: boolean;
+    poll_interval_ms?: number;
+}
+
+export interface EventDeliveryStreamItem {
+    cursor: string;
+    delivery: EventDeliverySummary;
+    event?: PlatformEvent;
+}
+
+export interface EventDeliveryStreamSnapshot {
+    type: 'snapshot';
+    emitted_at: string;
+    cursor?: string;
+    deliveries: EventDeliveryStreamItem[];
+}
+
+export interface EventDeliveryStreamUpdate {
+    type: 'event';
+    emitted_at: string;
+    cursor: string;
+    item: EventDeliveryStreamItem;
+}
+
+export interface EventDeliveryStreamHeartbeat {
+    type: 'heartbeat';
+    emitted_at: string;
+    cursor?: string;
+}
+
+export interface EventDeliveryStreamError {
+    type: 'error';
+    emitted_at: string;
+    cursor?: string;
+    error: string;
+}
+
+export type EventDeliveryStreamEnvelope =
+    | EventDeliveryStreamSnapshot
+    | EventDeliveryStreamUpdate
+    | EventDeliveryStreamHeartbeat
+    | EventDeliveryStreamError;
+
 export type EventSubscriptionSortField = 'name' | 'scope' | 'target_type' | 'enabled' | 'updated_at';
 
 export interface ListEventSubscriptionsQuery {

package/src/project.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { validateProjectSearchPropertyMappings } from './project.js';
+
+describe('validateProjectSearchPropertyMappings', () => {
+    it('accepts supported leaf mappings on relative property paths', () => {
+        expect(
+            validateProjectSearchPropertyMappings({
+                order_total: { type: 'double', ignore_malformed: true },
+                release_date: {
+                    type: 'date',
+                    format: 'strict_date_optional_time||yyyy-MM-dd',
+                    ignore_malformed: true,
+                },
+                'customer.account_number': { type: 'keyword', ignore_above: 128 },
+            }),
+        ).toEqual([]);
+    });
+
+    it('rejects unsupported mapping options and types', () => {
+        const issues = validateProjectSearchPropertyMappings({
+            order_total: { type: 'scaled_float', scaling_factor: 100 },
+            release_date: { type: 'keyword', format: 'yyyy-MM-dd' },
+            customer: { type: 'keyword', ignore_malformed: true },
+        });
+
+        expect(issues).toEqual(
+            expect.arrayContaining([
+                expect.stringContaining('unsupported option(s): scaling_factor'),
+                expect.stringContaining('type must be one of'),
+                expect.stringContaining('format is supported only for date mappings'),
+                expect.stringContaining('ignore_malformed is supported only for long, double, and date mappings'),
+            ]),
+        );
+    });
+
+    it('allows parent and child leaf mappings for subobjects:false indexes', () => {
+        expect(
+            validateProjectSearchPropertyMappings({
+                customer: { type: 'keyword' },
+                'customer.name': { type: 'keyword' },
+            }),
+        ).toEqual([]);
+    });
+});