@vertesia/common 1.4.0 → 1.5.0-dev.20260713.113008Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.4.0",
+  "version": "1.5.0-dev.20260713.113008Z",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,17 +17,14 @@
     }
   },
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^29.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^1.0.0",
-    "rollup": "^4.61.1",
+    "rolldown": "1.1.3",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@llumiverse/common": "1.4.0"
+    "@llumiverse/common": "1.5.0-dev"
   },
   "repository": {
     "type": "git",
@@ -47,7 +44,7 @@
     "test": "vitest run",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",
-    "build": "pnpm run clean:lib && tsc -p tsconfig.json && pnpm exec rollup -c",
+    "build": "pnpm run clean:lib && tsc -p tsconfig.json && pnpm exec rolldown -c rolldown.config.js",
     "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
   }
 }

package/src/access-control.ts

@@ -4,7 +4,7 @@
  * Access control interfaces
  */
 
-import type { SystemRoles } from './project.js';
+import type { AbacScope } from './roles/types.js';
 
 export enum Permission {
     int_read = 'interaction:read',
@@ -67,8 +67,18 @@ export enum AccessControlResourceType {
     account = 'account',
     interaction = 'interaction',
     app = 'application',
-    /** Dynamic resource matching by content properties at query time. */
-    content_set = 'content_set',
+    /**
+     * Dynamic resource matching by property conditions at query time. The role
+     * partitions (content, future tasks/etc.) determine which kind of object
+     * the conditions match — selected via `AceConditions.scope`.
+     *
+     * NOTE: the string value remains `'content_set'` for backward compatibility
+     * with stored ACEs and JWTs. The wire/DB rename to `'resource_set'` is a
+     * separate concern (deferred). Until then, code reads
+     * `AccessControlResourceType.resource_set` but the value on the wire stays
+     * `'content_set'`.
+     */
+    resource_set = 'content_set',
 }
 
 export enum AccessControlPrincipalType {
@@ -102,17 +112,32 @@ export type PropertyConditions = Record<string, PropertyConditionValue>;
 /**
  * Conditions attached to an ACE for dynamic matching.
  * - `principal_props`: matched against user/group properties at token time (PrincipalSet).
- * - `resource_props`: matched against content properties at query time (ContentSet).
+ * - `resource_props`: matched against object properties at query time (ResourceSet).
  */
 export interface AceConditions {
     /** Property conditions matched against user/group properties at token time (PrincipalSet). */
     principal_props?: PropertyConditions;
-    /** Property conditions matched against content properties at query time (ContentSet). */
+    /** Property conditions matched against object properties at query time (ResourceSet). */
     resource_props?: PropertyConditions;
+    /**
+     * Kind of object the `resource_props` matches. Used to disambiguate which
+     * partition's roles apply (e.g. content roles vs task roles) and to form
+     * the JWT `content_security` key prefix (`{scope}:{verb}`). Absent →
+     * `'document'` (default; emits bare `read`/`write`/`delete` keys for
+     * backward compatibility).
+     */
+    scope?: AbacScope;
 }
 
 export interface AccessControlEntry {
-    role: SystemRoles;
+    /**
+     * Role name. Typed as `string` because role names now span multiple
+     * partitions: `SystemRoles` enum values for system-domain roles, and bare
+     * strings for ABAC-domain roles (e.g. `'content:reader'`,
+     * `'content:writer'`, `'content:manager'`). Mongoose schema validates the
+     * value against the registered role catalog via `getAllRoleNames()`.
+     */
+    role: string;
     resource_type: AccessControlResourceType;
     resource: string; //objectId
     principal_type: AccessControlPrincipalType;

package/src/apikey.ts

@@ -4,14 +4,28 @@ import type { ProjectRef, SystemRoles } from './project.js';
 import type { AccountRef } from './user.js';
 
 /**
- * Content security conditions in the JWT, keyed by permission type.
- * Each key maps to an array of condition sets — at query time, any matching set grants access ($or).
- * Presence of this object in the JWT switches content access from allow-all to restrict mode.
+ * Per-scope, per-verb property-condition arrays that narrow content visibility
+ * at query time. Each value array uses $or semantics — any matching condition
+ * set grants access. Presence of this object switches content access from
+ * allow-all to restrict mode.
+ *
+ * The bare keys `read`/`write`/`delete` apply to the default `'document'`
+ * scope. They also receive entries emitted by system-role ABAC ACEs (which
+ * predate the scope concept).
+ *
+ * Non-default scopes appear as prefixed keys: `'collection:read'`,
+ * `'collection:write'`, `'task:read'`, etc. — the prefix is the
+ * `AceConditions.scope` value, the suffix is the verb derived from the
+ * ABAC role's permission set.
+ *
+ * Consumers that aren't scope-aware can keep reading only the bare keys.
  */
 export interface ContentSecurity {
     read?: PropertyConditions[];
     write?: PropertyConditions[];
     delete?: PropertyConditions[];
+    /** Scope-prefixed entries: `'collection:read'`, `'task:write'`, etc. */
+    [scopedKey: string]: PropertyConditions[] | undefined;
 }
 
 export enum ApiKeyTypes {
@@ -107,12 +121,22 @@ export interface AuthTokenPayload {
     groups?: UserGroupRef[]; //group ids
 
     /** Content security conditions keyed by permission (read/write/delete).
-     *  Presence triggers restrict mode: project:* is dropped from security filters. */
+     *  Presence triggers restrict mode: project:* is dropped from security filters.
+     *
+     *  Transitional: this field is being renamed to `abac` (see [[pending-migrations]]).
+     *  Both fields are typed so consumers can dual-read during the transition.
+     *  Only one will ever be populated in a given token. */
     content_security?: ContentSecurity;
+    /**
+     * New name for `content_security`. Consumers should prefer this field and
+     * fall back to `content_security`. Sts will be flipped to emit this field
+     * once all consumers have shipped their dual-read.
+     */
+    abac?: ContentSecurity;
 
     /**
      * API endpoints information to be used with this token.
-     * Either a n API domain like 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api-staging.vertesia.io' | 'local'
+     * Either an API domain like 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api.us1.vertesia.io' | 'local'
      * or explicit studio, store, and token URLs.
      */
     endpoints?:

package/src/apps.ts

@@ -40,11 +40,17 @@ export interface AppUIConfig {
      */
     src: string;
     /**
-     * The isolation strategy. If not specified it defaults to shadow
+     * The isolation strategy. If not specified it defaults to shadow.
      * - shadow - use Shadow DOM to fully isolate the plugin from the host.
-     * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
+     * - css - inject the plugin's styles (minus the preflight) into the host document;
+     *   lighter but styles may conflict with the host.
      */
     isolation?: 'shadow' | 'css';
+    /**
+     * When true the host modifies the app's css at load time to attempt to fix broken
+     * or missing styles. Only takes effect in css isolation mode. Defaults to false.
+     */
+    css_rebuild?: boolean;
     /**
      * Navigation items for the app's sidebar UI.
      * Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell).
@@ -758,10 +764,21 @@ export interface AppManifest extends AppManifestData {
     id: string;
     /** The owning account. Undefined for apps imported from a master region. */
     account?: string;
+    /** Source metadata for generated or synced app manifests. */
+    source?: AppManifestSource;
     created_at: string;
     updated_at: string;
 }
 
+export interface AppManifestSource {
+    kind: 'git';
+    git: {
+        url: string;
+        default_branch?: string;
+        development_branch?: string;
+    };
+}
+
 /**
  * Binding between an MCP collection and an OAuth provider created at install time.
  * Stored on AppInstallation so the runtime can look up the correct OAuth provider by ID,
@@ -1056,6 +1073,10 @@ export interface CompositeAppSwitchersOverrides {
 
 /**
  * Header button visibility overrides for the CompositeApp header.
+ *
+ * @deprecated Superseded by `CompositeAppConfig.headerMenu` (free-form header items).
+ * Retained for backward compatibility and to seed the default header menu when no
+ * `headerMenu` has been configured yet.
  */
 export interface CompositeAppHeaderOverrides {
     /** Whether to hide the App Portal button (defaults to false) */
@@ -1068,6 +1089,10 @@ export interface CompositeAppHeaderOverrides {
 
 /**
  * User menu overrides for the CompositeApp.
+ *
+ * @deprecated Superseded by the `user_menu` item in `CompositeAppConfig.headerMenu`.
+ * Retained for backward compatibility and to seed the default header menu when no
+ * `headerMenu` has been configured yet.
  */
 export interface CompositeAppUserMenuOverrides {
     /** Whether to hide the User Menu (defaults to false) */
@@ -1189,6 +1214,51 @@ export interface CompositeAppHomePlugin {
     appRoute?: string;
 }
 
+// ============================================================================
+// Header Menu Types
+// ============================================================================
+
+/**
+ * Discriminator for a header item.
+ * The four built-ins (`app_portal`, `docs`, `help`, `user_menu`) seed the default
+ * header and cannot be deleted (only hidden/customized); `custom` items are fully
+ * user-defined buttons.
+ */
+export type CompositeAppHeaderItemKind = 'app_portal' | 'docs' | 'help' | 'user_menu' | 'custom';
+
+/** Where a header link opens. */
+export type CompositeAppHeaderItemTarget = '_self' | '_blank';
+
+/** Stable identifiers for the built-in header items. */
+export const COMPOSITE_APP_HEADER_BUILTIN_IDS = ['app_portal', 'docs', 'help', 'user_menu'] as const;
+
+/**
+ * A single button in the CompositeApp header bar.
+ *
+ * Unlike sidebar nav-items, header items are free-form and not tied to an installed
+ * app: each is a labelled, icon-bearing button linking to a route or external URL.
+ * The `user_menu` item is special — it renders the account dropdown, so its `icon`,
+ * `href`, and `target` are ignored.
+ */
+export interface CompositeAppHeaderItem {
+    /** Stable unique identifier. Built-ins use their kind as id (e.g. "app_portal"). */
+    id: string;
+    /** Item kind. `custom` for user-added buttons; otherwise one of the four built-ins. */
+    kind: CompositeAppHeaderItemKind;
+    /** Display label, used as the button tooltip / accessible name. */
+    label: string;
+    /** Lucide icon name or SVG content string. Ignored for `user_menu`. */
+    icon?: string;
+    /** Destination route ("/...") or external URL. Ignored for `user_menu`. */
+    href?: string;
+    /** Where to open the link (defaults to "_self"). Ignored for `user_menu`. */
+    target?: CompositeAppHeaderItemTarget;
+    /** When true, this item is hidden from the header. */
+    hidden?: boolean;
+    /** Optional access control settings for this header item. */
+    permissions?: CompositeAppNavItemPermissions;
+}
+
 /**
  * CompositeApp shell configuration.
  * This is the main configuration interface for storing CompositeApp settings.
@@ -1212,10 +1282,23 @@ export interface CompositeAppConfig {
     switchers?: CompositeAppSwitchersOverrides;
     /** Optional sidebar display overrides */
     sidebar?: CompositeAppSidebarOverrides;
-    /** Optional header button visibility overrides */
+    /**
+     * @deprecated Use `headerMenu` instead. Optional header button visibility overrides.
+     * Still read to seed `headerMenu` defaults for configs saved before the header menu existed.
+     */
     header?: CompositeAppHeaderOverrides;
-    /** Optional user menu overrides */
+    /**
+     * @deprecated Use the `user_menu` item in `headerMenu` instead. Optional user menu overrides.
+     * Still read to seed `headerMenu` defaults for configs saved before the header menu existed.
+     */
     userMenu?: CompositeAppUserMenuOverrides;
+    /**
+     * Optional free-form header menu. When present, the header renders from this ordered
+     * list instead of the legacy `header`/`userMenu` flags. Built-in items (App Portal,
+     * Docs, Help, User Menu) can be hidden/relabeled/re-icon'd/redirected; custom items
+     * are arbitrary buttons.
+     */
+    headerMenu?: CompositeAppHeaderItem[];
     /** Optional theme overrides (e.g. disable dark mode) */
     theme?: CompositeAppThemeOverrides;
     /** Optional home page override. When set, redirects "/" to the specified app route instead of the dashboard. Send null to unset. */

package/src/audit-trail.ts

@@ -1,25 +1,31 @@
-export type AuditAction =
+import type { EventCategory } from './platform-event.js';
+
+export const AUDIT_ACTIONS = [
     // CRUD operations
-    | 'create'
-    | 'update'
-    | 'delete'
-    | 'bulk_create'
-    | 'bulk_change_type'
-    | 'bulk_update'
-    | 'bulk_delete'
-    | 'attach'
-    | 'detach'
-    | 'credentials_fill'
-    | 'credentials_totp_generation'
-    | 'publish'
-    | 'unpublish'
+    'create',
+    'update',
+    'delete',
+    'bulk_create',
+    'bulk_change_type',
+    'bulk_update',
+    'bulk_delete',
+    'attach',
+    'detach',
+    'credentials_fill',
+    'credentials_totp_generation',
+    'publish',
+    'unpublish',
     // Billable operations
-    | 'inference'
-    | 'embedding'
-    | 'image_generation';
+    'inference',
+    'embedding',
+    'image_generation',
+] as const;
+
+export type KnownAuditAction = (typeof AUDIT_ACTIONS)[number];
+export type AuditAction = KnownAuditAction | (string & {});
 
 /** Billable audit actions for cost analytics queries */
-export const BILLABLE_AUDIT_ACTIONS: AuditAction[] = ['inference', 'embedding', 'image_generation'];
+export const BILLABLE_AUDIT_ACTIONS = ['inference', 'embedding', 'image_generation'] satisfies KnownAuditAction[];
 
 /**
  * Generic metering entry attached to audit events.
@@ -39,6 +45,16 @@ export interface AuditMeter {
 
 export interface AuditTrailEvent {
     event_type: 'audit';
+    event_id?: string;
+    event_category?: EventCategory;
+    source?: string | null;
+    root_event_id?: string;
+    caused_by_event_id?: string;
+    hop_count?: number;
+    audit_trail?: boolean;
+    replay_of?: string;
+    replay_root_event_id?: string;
+    replayed_by?: string;
     action: AuditAction;
     resource_type: string;
     resource_id: string;

package/src/environment.ts

@@ -166,6 +166,13 @@ export interface ExecutionEnvironmentConfigUpdatePayload {
     config?: MediatorEnvConfig | LoadBalancingEnvConfig;
 }
 
+export interface EnableEnvironmentModelPayload {
+    /**
+     * Provider model ID to resolve from the environment's available model listing.
+     */
+    model_id: string;
+}
+
 export interface MigrateInteractionsPayload {
     /**
      * The new environment ID to set in the Interactions

package/src/index.ts

@@ -27,6 +27,8 @@ export * from './oauth-server.js';
 export * from './Progress.js';
 export * from './payload.js';
 export * from './pending-asks.js';
+export * from './platform-event.js';
+export * from './platform-event-validation.js';
 export * from './principal-context.js';
 export * from './project.js';
 export * from './prompt.js';
@@ -38,6 +40,29 @@ export * from './runs.js';
 export * from './secrets.js';
 export * from './skill.js';
 export * from './store/index.js';
+export type {
+    ContentObjectExportArtifact,
+    ContentObjectExportArtifactFile,
+    ContentObjectExportProgress,
+    ContentObjectExportResult,
+    ContentObjectExportStatusResponse,
+    DeleteContentObjectExportResponse,
+    ExportContentObjectsFilter,
+    ExportContentObjectsIncludeOptions,
+    ExportedContentObjectRecord,
+    ListContentObjectExportsResponse,
+    StartContentObjectExportRequest,
+    StartContentObjectExportResponse,
+    ZenoBulkContentObjectExportComposeRequest,
+    ZenoBulkContentObjectExportPlanRequest,
+    ZenoBulkContentObjectExportPlanResponse,
+    ZenoBulkContentObjectExportRequest,
+    ZenoBulkContentObjectExportShardRange,
+    ZenoBulkContentObjectExportShardRequest,
+    ZenoBulkContentObjectExportShardResult,
+    ZenoBulkContentObjectExportSplitShardRequest,
+    ZenoBulkContentObjectExportSplitShardResponse,
+} from './store/store.js';
 export * from './sts-token-types.js';
 export * from './tenant.js';
 export * from './tool-execution.js';

package/src/integrations.ts

@@ -18,8 +18,21 @@ export interface GladiaConfigurationWithSecrets extends GladiaConfiguration {
     api_key?: string;
 }
 
+export interface GithubConfigurationInput extends IntegrationConfigurationBase<SupportedIntegrations.github> {
+    /** Numeric GitHub App id used to mint installation tokens (non-secret). */
+    github_app_id?: string;
+    /** Allow-list of `owner/name` repos the bot may mint installation tokens for (default-deny when empty). */
+    allowed_repositories?: string[];
+    /** GitHub App private key (PEM). Write-only; never returned. Empty string clears it. */
+    private_key?: string;
+}
+
 export interface GithubConfiguration extends IntegrationConfigurationBase<SupportedIntegrations.github> {
+    /** Numeric GitHub App id used to mint installation tokens (non-secret). */
+    github_app_id?: string;
     allowed_repositories: string[];
+    /** True when a GitHub App private key is stored for the project (the key itself is never returned). */
+    has_github_app_private_key?: boolean;
 }
 
 export interface AwsConfiguration extends IntegrationConfigurationBase<SupportedIntegrations.aws> {
@@ -168,7 +181,7 @@ export enum SupportedIntegrations {
  */
 export type ProjectIntegrationConfigRequest =
     | GladiaConfigurationInput
-    | GithubConfiguration
+    | GithubConfigurationInput
     | AwsConfiguration
     | MagicPdfConfiguration
     | SerperConfigurationInput