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

package/lib/views.js

@@ -0,0 +1,41 @@
+export const VIEW_EXPERIENCE_SCHEMA_VERSION = 1;
+/** Build the generic reusable client route for a persisted or app-contributed View. */
+export function viewExperienceRoute(id) {
+    return `/view/${encodeURIComponent(id)}`;
+}
+export const VIEW_SEARCH_FIELD_TYPES = ['text', 'keyword', 'number', 'date', 'boolean'];
+export const VIEW_RESULT_FIELD_FORMATS = [
+    'text',
+    'date',
+    'number',
+    'badge',
+    'user',
+    'content_type',
+    'location',
+];
+/**
+ * Project a persisted or extended View value back to its reusable configuration
+ * fields. Callers that require a persisted configuration must validate the
+ * result at their API or persistence boundary because legacy records may not
+ * satisfy newer persisted-only requirements.
+ */
+export function getViewExperienceConfiguration(value) {
+    return {
+        name: value.name,
+        ...(value.description === undefined ? {} : { description: value.description }),
+        ...(value.enabled === undefined ? {} : { enabled: value.enabled }),
+        ...(value.layout === undefined ? {} : { layout: value.layout }),
+        ...(value.scope === undefined ? {} : { scope: value.scope }),
+        ...(value.navigation === undefined ? {} : { navigation: value.navigation }),
+        ...(value.search === undefined ? {} : { search: value.search }),
+        ...(value.results === undefined ? {} : { results: value.results }),
+    };
+}
+/** Project a type-valid persisted View while preserving its required documentation field. */
+export function getPersistedViewExperienceConfiguration(value) {
+    return {
+        ...getViewExperienceConfiguration(value),
+        description: value.description,
+    };
+}
+//# sourceMappingURL=views.js.map

package/lib/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../src/views.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAU,CAAC;AAIzD,uFAAuF;AACvF,MAAM,UAAU,mBAAmB,CAAC,EAAU;IAC1C,OAAO,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7C,CAAC;AAkGD,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAqDjG,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACrC,MAAM;IACN,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,cAAc;IACd,UAAU;CACJ,CAAC;AAwHX;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAkC;IAC7E,OAAO;QACH,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;QAC9E,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAClE,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5D,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;QAC3E,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;KACrE,CAAC;AACN,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,uCAAuC,CACnD,KAA2C;IAE3C,OAAO;QACH,GAAG,8BAA8B,CAAC,KAAK,CAAC;QACxC,WAAW,EAAE,KAAK,CAAC,WAAW;KACjC,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.5.0-dev.20260717.131047Z",
+  "version": "1.5.0-dev.20260722.120446Z",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,14 +17,14 @@
     }
   },
   "devDependencies": {
-    "rolldown": "1.1.4",
+    "rolldown": "1.1.5",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.10",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@llumiverse/common": "1.5.0-dev.20260713.114357Z"
+    "@llumiverse/common": "1.5.0-dev.20260722.112223Z"
   },
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "8aaad228827b2927db8e6aa75b27bfac90fec36f",
+  "gitHead": "203c30e5a8ddc583ac9f1acce0f5445eb38a9551",
   "scripts": {
     "lint": "biome lint src",
     "test": "vitest run",

package/src/apps.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest';
-import { effectiveAppAccessControl } from './apps.js';
+import { APP_ARTIFACT_TYPES, APP_CAPABILITIES, APP_PACKAGE_SCOPES, effectiveAppAccessControl } from './apps.js';
+
+describe('app capability contracts', () => {
+    it('keeps views in manifest, package, and build-artifact contracts', () => {
+        expect(APP_CAPABILITIES).toContain('views');
+        expect(APP_PACKAGE_SCOPES).toContain('views');
+        expect(APP_ARTIFACT_TYPES).toContain('view');
+    });
+});
 
 describe('effectiveAppAccessControl', () => {
     it("returns 'all' when neither installation nor manifest set the field", () => {

package/src/apps.ts

@@ -2,6 +2,7 @@ import type { JSONObject, JSONSchema, ToolDefinition } from '@llumiverse/common'
 import type { AppDashboardDefinition } from './data-platform.js';
 import type { CatalogInteractionRef } from './interaction.js';
 import type { DSLActivityOptions, InCodeProcessDefinition, InCodeTypeDefinition } from './store/index.js';
+import type { InCodeViewDefinition } from './views.js';
 
 /** Allowed values for AppUINavItem.preferredSection */
 export const PREFERRED_SECTIONS = ['default', 'footer', 'settings'] as const;
@@ -383,27 +384,26 @@ export interface RemoteActivityDefinition {
     options?: DSLActivityOptions;
 }
 
-export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates' | 'dashboards';
-
 /**
- * Canonical runtime list of {@link AppCapabilities} — the app capabilities Studio
- * renders/supports. Co-located with the type so TypeScript rejects any drift between
- * the two. Consumers (publish manifest derivation, etc.) must use this rather than
- * re-listing the values.
+ * Canonical app capabilities Studio renders/supports. The public type is derived from
+ * this list so runtime validation and TypeScript cannot drift.
  */
-export const APP_CAPABILITIES: readonly AppCapabilities[] = [
+export const APP_CAPABILITIES = [
     'ui',
     'tools',
     'interactions',
     'types',
     'processes',
+    'views',
     'templates',
     'dashboards',
-];
+] as const;
+
+export type AppCapabilities = (typeof APP_CAPABILITIES)[number];
 
 /**
  * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
- * capability refs (`app:<app>:...`) against that version (candidate testing) instead of current.
+ * capability refs (`app:<app>:...`) against that exact version instead of the promoted version.
  * Resolution-time only; never persisted. Set by the generated app template via client.withAppVersion.
  */
 export const APP_VERSION_HEADER = 'x-vertesia-app-version';
@@ -414,26 +414,19 @@ export const APP_VERSION_HEADER = 'x-vertesia-app-version';
  * {@link AppCapabilities} folds together. Used by the App Solution Architect manifest and
  * the publish-time capability gate.
  */
-export type AppArtifactType =
-    | 'interaction'
-    | 'agent'
-    | 'type'
-    | 'process'
-    | 'template'
-    | 'dashboard'
-    | 'activity'
-    | 'tool';
-
-export const APP_ARTIFACT_TYPES: readonly AppArtifactType[] = [
+export const APP_ARTIFACT_TYPES = [
     'interaction',
     'agent',
     'type',
     'process',
+    'view',
     'template',
     'dashboard',
     'activity',
     'tool',
-];
+] as const;
+
+export type AppArtifactType = (typeof APP_ARTIFACT_TYPES)[number];
 
 /**
  * A single platform artifact the App Solution Architect requires the build to create.
@@ -473,8 +466,8 @@ export interface AppPlannedArtifact {
 /**
  * Structured result the App Solution Architect emits alongside its prose artifacts — the
  * machine-readable contract for the build. The implementation MUST create and successfully
- * exercise every required artifact before preview/publish. Persisted into the app repo as
- * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the publish-time
+ * exercise every required artifact before building a deployable version. Persisted into the app repo as
+ * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the version-build
  * capability gate can verify against it deterministically. If the builder finds the plan
  * wrong or insufficient, the orchestrator relaunches the architect to revise the manifest;
  * the gate always checks against the latest committed copy.
@@ -499,16 +492,14 @@ export interface AppCapabilityManifest {
     notes?: string;
 }
 
-/** Repo-relative path the capability manifest is committed to, read by the publish gate. */
+/** Repo-relative path the capability manifest is committed to, read by version-build gates. */
 export const APP_CAPABILITY_MANIFEST_PATH = 'docs/app-capability-manifest.json';
-
 export type AppAvailableIn = 'app_portal' | 'composite_app';
 
-export type AppVersionKind = 'design' | 'preview' | 'published';
+export type AppVersionKind = 'design' | 'version';
 export type AppVersionState = 'ready' | 'failed' | 'expired';
 export type AppVersionTarget = 'static' | 'service';
 export type AppVersionGitRefType = 'branch' | 'tag' | 'commit' | 'detached';
-export type AppBuildIntent = 'preview' | 'publish';
 export type AppBuildTrigger = 'ui' | 'git_push' | 'agent' | 'api';
 
 export interface AppVersionStorage {
@@ -527,8 +518,8 @@ export interface AppVersionGitSource {
     url?: string;
     remote?: string;
     /**
-     * The source ref that should be used to reproduce this version. For immutable
-     * app versions this is normally the tag created during preview/publish.
+     * The source ref that should be used to reproduce this version. Immutable
+     * app versions use the exact commit SHA rather than a mutable branch or tag.
      */
     ref?: string;
     ref_type?: AppVersionGitRefType;
@@ -558,13 +549,19 @@ export interface AppVersionRecord {
     version_id: string;
     kind: AppVersionKind;
     state: AppVersionState;
-    active?: boolean;
+    promoted?: boolean;
     target?: AppVersionTarget;
     agent_run_id?: string;
+    /** Temporal workflow that produced this version. */
+    build_workflow_id?: string;
+    /** Temporal run that produced this version. */
+    build_workflow_run_id?: string;
     sandbox_id?: string;
     title?: string;
     description?: string;
     storage?: AppVersionStorage;
+    /** Exact Git commit used to build this immutable version. */
+    source_commit?: string;
     urls?: AppVersionUrls;
     manifest?: Record<string, unknown>;
     files?: string[];
@@ -575,25 +572,39 @@ export interface AppVersionRecord {
     created_by?: string;
     created_at: string;
     updated_at: string;
-    published_at?: string;
+    built_at?: string;
     checked_at?: string;
     expires_at?: string;
 }
 
+export interface DeleteAppVersionResponse {
+    id: string;
+    app_id: string;
+    version_id: string;
+    storage_prefix?: string;
+    deleted: boolean;
+    warnings: string[];
+}
+
 export interface UpsertAppVersionRequest {
+    /** Existing version record to update in place, used by reproducible rebuilds. */
+    record_id?: string;
     app?: string;
     app_id: string;
     app_name?: string;
     version_id: string;
     kind: AppVersionKind;
     state?: AppVersionState;
-    active?: boolean;
     target?: AppVersionTarget;
     agent_run_id?: string;
+    build_workflow_id?: string;
+    build_workflow_run_id?: string;
     sandbox_id?: string;
     title?: string;
     description?: string;
     storage?: AppVersionStorage;
+    /** Exact Git commit used to build this immutable version. */
+    source_commit?: string;
     urls?: AppVersionUrls;
     manifest?: Record<string, unknown>;
     files?: string[];
@@ -601,7 +612,7 @@ export interface UpsertAppVersionRequest {
     source_file_count?: number;
     screenshot_artifact?: string;
     checks?: string[];
-    published_at?: string;
+    built_at?: string;
     checked_at?: string;
     expires_at?: string;
 }
@@ -613,7 +624,7 @@ export interface AppVersionListQuery {
     limit?: number;
 }
 
-export interface ActivateAppVersionResponse {
+export interface PromoteAppVersionResponse {
     version: AppVersionRecord;
     app?: AppManifest;
 }
@@ -621,15 +632,12 @@ export interface ActivateAppVersionResponse {
 export interface StartAppBuildRequest {
     /**
      * Source branch, tag, or commit to build. When omitted, the app source
-     * configuration chooses the dev branch for previews and production branch
-     * for publishes.
+     * configuration chooses its default branch.
      */
     source_ref?: string;
     source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
-    intent?: AppBuildIntent;
     trigger?: AppBuildTrigger;
     target?: AppVersionTarget;
-    activate?: boolean;
     title?: string;
     description?: string;
 }
@@ -638,7 +646,8 @@ export interface StartAppBuildResponse {
     workflow_id: string;
     run_id: string;
     app_id: string;
-    intent: AppBuildIntent;
+    version_id?: string;
+    rebuild_version_record_id?: string;
     source_ref?: string;
     source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
 }
@@ -646,6 +655,8 @@ export interface StartAppBuildResponse {
 export interface AppBuildWorkflowInput extends StartAppBuildRequest {
     app_id: string;
     app_record_id?: string;
+    /** Rebuild this persisted version record at its original commit and target. */
+    rebuild_version_record_id?: string;
     app_title?: string;
     app_description?: string;
     source_git_url?: string;
@@ -654,8 +665,9 @@ export interface AppBuildWorkflowInput extends StartAppBuildRequest {
 export interface AppBuildWorkflowResult {
     app_id: string;
     version_id: string;
-    kind: Extract<AppVersionKind, 'preview' | 'published'>;
+    kind: Extract<AppVersionKind, 'version'>;
     state: AppVersionState;
+    source_commit: string;
     source_git?: AppVersionGitSource;
     urls?: AppVersionUrls;
     file_count?: number;
@@ -668,7 +680,6 @@ export interface AppBuildProgress {
     step: string;
     app_id?: string;
     version_id?: string;
-    intent?: AppBuildIntent;
     source_ref?: string;
     source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
     source_commit?: string;
@@ -678,6 +689,66 @@ export interface AppBuildProgress {
     updated_at: string;
 }
 
+export type AppScaffoldModule = 'service' | 'assistant' | 'content-app' | 'examples';
+
+export interface StartAppScaffoldRequest {
+    /**
+     * App id / package name to create. It is normalized to the same slug rules
+     * used by @vertesia/create-plugin.
+     */
+    app_id: string;
+    title?: string;
+    description?: string;
+    modules?: AppScaffoldModule[];
+    /**
+     * Start an initial app version build after the source has been pushed.
+     * Defaults to true.
+     */
+    create_version?: boolean;
+}
+
+export interface StartAppScaffoldResponse {
+    workflow_id: string;
+    run_id: string;
+    app_id: string;
+    app_record_id?: string;
+    git_url?: string;
+    create_version: boolean;
+}
+
+export interface AppScaffoldWorkflowInput extends StartAppScaffoldRequest {}
+
+export interface AppScaffoldWorkflowResult {
+    app_id: string;
+    app_record_id?: string;
+    git_url?: string;
+    source_git?: AppVersionGitSource;
+    files?: number;
+    initial_version_build?: StartAppBuildResponse;
+}
+
+export type AppScaffoldProgressStatus =
+    | 'queued'
+    | 'reserving'
+    | 'scaffolding'
+    | 'pushing'
+    | 'building'
+    | 'completed'
+    | 'failed';
+
+export interface AppScaffoldProgress {
+    status: AppScaffoldProgressStatus;
+    step: string;
+    app_id?: string;
+    app_record_id?: string;
+    git_url?: string;
+    files?: number;
+    initial_version_build?: StartAppBuildResponse;
+    error?: string;
+    error_details?: string[];
+    updated_at: string;
+}
+
 /**
  * Access control policy for an app installation.
  * Declares which access surfaces are gated by per-user ACEs.
@@ -832,8 +903,9 @@ export interface AppManifestData {
 
     /**
      * Source repository configuration for apps generated and maintained through
-     * AppGen. Branches are mutable deployment lanes; immutable app versions
-     * record their exact source tag/commit in AppVersionRecord.storage.source_git.
+     * AppGen. Branches are mutable development lanes; immutable app versions
+     * record their exact source commit in AppVersionRecord.source_commit and
+     * AppVersionRecord.storage.source_git.
      */
     source?: AppSourceConfig;
 
@@ -881,7 +953,7 @@ export interface Endpoints {
     ui?: string;
     /** The Smart HTTP app source git server base URL */
     git?: string;
-    /** The appgen app-gateway base URL (serves published app bundles + their `/api` runtime). */
+    /** The appgen app-gateway base URL (serves promoted app bundles + their `/api` runtime). */
     gateway?: string;
 }
 
@@ -927,14 +999,46 @@ export interface AppRepoTree {
     entries: AppRepoTreeEntry[];
 }
 
-/** The content of a single file read from an app git repo at a given ref. */
-export interface AppRepoFile {
-    /** Path relative to the repo root. */
-    path: string;
-    /** The ref the file was read at (empty/undefined = default branch / HEAD). */
+/** Browser-side limits mirrored by the app Git service document endpoint. */
+export const APP_REPO_DOCUMENT_UPLOAD_MAX_FILE_BYTES = 20 * 1024 * 1024;
+export const APP_REPO_DOCUMENT_UPLOAD_MAX_TOTAL_BYTES = 80 * 1024 * 1024;
+export const APP_REPO_DOCUMENT_UPLOAD_MAX_FILES = 20;
+export const APP_REPO_DOCUMENT_UPLOAD_PREFIX = 'docs/';
+
+/** Result of committing one or more uploaded documents to an app repository. */
+export interface AppRepoDocumentCommit {
+    /** Updated branch name. */
+    ref: string;
+    /** Branch HEAD before the commit. */
+    previous_commit: string;
+    /** Newly created commit SHA. */
+    commit: string;
+    /** Repository paths changed by the commit. */
+    paths: string[];
+}
+
+/** One commit that inserted or changed a file in an app git repository. */
+export interface AppRepoCommit {
+    /** Full commit SHA. */
+    commit: string;
+    /** Complete commit message. */
+    message: string;
+    /** Commit author name, when available. */
+    author?: string;
+    /** Commit author date as an ISO-8601 string, when available. */
+    date?: string;
+}
+
+/** Commit history in an app git repository, optionally filtered to a file. */
+export interface AppRepoCommits {
+    /** Ref from which history traversal started (empty/undefined = default branch / HEAD). */
     ref?: string;
-    /** UTF-8 file content. */
-    content: string;
+    /** File path relative to the repository root, when history was filtered to a file. */
+    path?: string;
+    /** Commits ordered newest first. */
+    commits: AppRepoCommit[];
+    /** Pass this cursor to retrieve the next page. Absent when history is exhausted. */
+    next_cursor?: string;
 }
 
 /** A branch or tag in an app git repo, resolved to its latest commit. */
@@ -959,37 +1063,26 @@ export interface AppRepoRefs {
     tags: AppRepoRef[];
 }
 
-export type AppPackageScope =
-    | 'ui'
-    | 'tools'
-    | 'interactions'
-    | 'types'
-    | 'processes'
-    | 'templates'
-    | 'dashboards'
-    | 'settings'
-    | 'widgets'
-    | 'activities'
-    | 'all';
-
 /**
- * Canonical runtime list of {@link AppPackageScope} — every package scope, including the
- * catch-all `'all'`. Co-located with the type so TypeScript rejects drift. Consumers (the
- * /package?scope= parser, the inspection report) must use this rather than re-listing.
+ * Canonical package scopes, including the catch-all `all`. The public type is derived
+ * from this list so request parsing and TypeScript cannot drift.
  */
-export const APP_PACKAGE_SCOPES: readonly AppPackageScope[] = [
+export const APP_PACKAGE_SCOPES = [
     'ui',
     'tools',
     'interactions',
     'types',
     'processes',
+    'views',
     'templates',
     'dashboards',
     'settings',
     'widgets',
     'activities',
     'all',
-];
+] as const;
+
+export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -1024,6 +1117,11 @@ export interface AppPackage {
      */
     processes?: InCodeProcessDefinition[];
 
+    /**
+     * View Experiences exposed by the app as in-code definitions.
+     */
+    views?: InCodeViewDefinition[];
+
     /**
      * Templates provided by the app.
      */
@@ -1066,14 +1164,14 @@ export interface AppInspectionIssue {
 }
 
 /**
- * Per-capability report of what an app's published package actually exposes,
+ * Per-capability report of what an app's promoted package actually exposes,
  * compared against what its manifest declares.
  */
 export interface AppInspectionCapabilityReport {
     capability: AppPackageScope;
     /** True when the manifest's `capabilities` array declares this capability. */
     declared: boolean;
-    /** The local ids the published package actually serves for this capability. */
+    /** The local ids the promoted package actually serves for this capability. */
     exposed_ids: string[];
     /** Convenience count of `exposed_ids`. */
     exposed_count: number;
@@ -1081,7 +1179,7 @@ export interface AppInspectionCapabilityReport {
 
 /**
  * Result of inspecting an app's registration: the resolved manifest state, what
- * the published package actually exposes per capability, and diagnostics. This
+ * the promoted package actually exposes per capability, and diagnostics. This
  * is the ground truth used by the `app_inspect_registration` agent tool and the
  * Build › App inspection UI to verify what is registered vs declared, instead of
  * inferring it from failed object/import calls.
@@ -1099,7 +1197,7 @@ export interface AppInspectionResult {
     access_control?: string;
     /** The capabilities declared on the manifest. */
     capabilities: AppPackageScope[];
-    /** What the published package exposes, per capability. */
+    /** What the promoted package exposes, per capability. */
     package: AppInspectionCapabilityReport[];
     /** Diagnostics — errors and warnings about the registration state. */
     issues: AppInspectionIssue[];

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;
+}