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

package/src/email.ts

@@ -1,3 +1,5 @@
+import type { z } from 'zod';
+import type { EmailChannelSchema, InteractiveChannelSchema, UserChannelSchema } from './api-schemas/interaction.js';
 /**
  * Email-related types for agent communication and routing.
  */
@@ -8,27 +10,13 @@
  * Email channel configuration with threading support.
  * Used for email-based agent communication.
  */
-export interface EmailChannel {
-    type: 'email';
-    /** Email address to send agent messages to */
-    to_email: string;
-    /** Subject for the email thread (without "Re:" prefix) */
-    thread_subject?: string;
-    /** Message ID for In-Reply-To header (most recent message) */
-    in_reply_to?: string;
-    /** Chain of message IDs for References header */
-    references?: string[];
-    /** Short routing key for reply emails (8-char alphanumeric, stored in Redis) */
-    route_key?: string;
-}
+export type EmailChannel = z.infer<typeof EmailChannelSchema>;
 
 /**
  * Interactive (UI chat) channel configuration.
  * Used for real-time chat interface communication.
  */
-export interface InteractiveChannel {
-    type: 'interactive';
-}
+export type InteractiveChannel = z.infer<typeof InteractiveChannelSchema>;
 
 /**
  * Union of all supported user communication channel types.
@@ -36,7 +24,7 @@ export interface InteractiveChannel {
 /**
  * @discriminator type
  */
-export type UserChannel = EmailChannel | InteractiveChannel;
+export type UserChannel = z.infer<typeof UserChannelSchema>;
 
 /**
  * Type guard for email channels

package/src/embeddings.ts

@@ -1,72 +1,34 @@
-import type { EmbeddingsResult, EmbeddingTaskType } from '@llumiverse/common';
+import type { EmbeddingsResult } from '@llumiverse/common';
+import type { z } from 'zod';
+import type {
+    EmbeddingsApiAudioInputSchema,
+    EmbeddingsApiImageInputSchema,
+    EmbeddingsApiInputSchema,
+    EmbeddingsApiRequestSchema,
+    EmbeddingsApiSourceSchema,
+    EmbeddingsApiTextInputSchema,
+    EmbeddingsApiVideoInputSchema,
+} from './api-schemas/embeddings.js';
 
 /**
- * Wire-format inputs accepted by the studio-server embeddings endpoint.
- * Mirror of @llumiverse/common's EmbeddingInput, but binary modalities
- * carry a JSON-friendly source (URL or base64) instead of a DataSource.
- *
- * The server wraps each source in a Base64DataSource or URLDataSource
- * before passing the request to the llumiverse driver.
+ * The embeddings request types, inferred from `./api-schemas/embeddings.js`. Their documentation
+ * moved with them: a doc comment above one of these would be published on top of the schema's own
+ * `description`, which is how the union's description came to be the truncated `"…Mirror of"` the
+ * document carried for as long as the types lived here.
  */
-export type EmbeddingsApiInput =
-    | EmbeddingsApiTextInput
-    | EmbeddingsApiImageInput
-    | EmbeddingsApiVideoInput
-    | EmbeddingsApiAudioInput;
+export type EmbeddingsApiInput = z.infer<typeof EmbeddingsApiInputSchema>;
 
-export interface EmbeddingsApiSource {
-    /** Display name for the source (defaults to "embedding-input"). */
-    name?: string;
-    /** MIME type of the binary content. Required for most providers. */
-    mime_type?: string;
-    /**
-     * Provider-native URL the driver may pass through directly:
-     * - gs:// or https://storage.googleapis.com/ for Vertex AI
-     * - s3:// or https://*.amazonaws.com for Bedrock
-     * - https:// for fetch fallback
-     * Mutually exclusive with base64.
-     */
-    url?: string;
-    /** Base64-encoded bytes. Mutually exclusive with url. */
-    base64?: string;
-}
+export type EmbeddingsApiSource = z.infer<typeof EmbeddingsApiSourceSchema>;
 
-export interface EmbeddingsApiTextInput {
-    type: 'text';
-    text: string;
-    task_type?: EmbeddingTaskType;
-    title?: string;
-}
+export type EmbeddingsApiTextInput = z.infer<typeof EmbeddingsApiTextInputSchema>;
 
-export interface EmbeddingsApiImageInput {
-    type: 'image';
-    source: EmbeddingsApiSource;
-}
+export type EmbeddingsApiImageInput = z.infer<typeof EmbeddingsApiImageInputSchema>;
 
-export interface EmbeddingsApiVideoInput {
-    type: 'video';
-    source: EmbeddingsApiSource;
-    start_sec?: number;
-    length_sec?: number;
-    interval_sec?: number;
-    use_fixed_length_sec?: boolean;
-    min_clip_sec?: number;
-    embedding_option?: ('visual-text' | 'visual-image' | 'audio')[];
-}
+export type EmbeddingsApiVideoInput = z.infer<typeof EmbeddingsApiVideoInputSchema>;
 
-export interface EmbeddingsApiAudioInput {
-    type: 'audio';
-    source: EmbeddingsApiSource;
-    start_sec?: number;
-    length_sec?: number;
-}
+export type EmbeddingsApiAudioInput = z.infer<typeof EmbeddingsApiAudioInputSchema>;
 
-export interface EmbeddingsApiRequest {
-    inputs: EmbeddingsApiInput[];
-    model?: string;
-    task_type?: EmbeddingTaskType;
-    dimensions?: number;
-}
+export type EmbeddingsApiRequest = z.infer<typeof EmbeddingsApiRequestSchema>;
 
 /**
  * Wire-format result. Identical to @llumiverse/common's EmbeddingsResult

package/src/environment.ts

@@ -1,5 +1,23 @@
-import type { AIModel, ProviderParams } from '@llumiverse/common';
+import type { ProviderParams } from '@llumiverse/common';
 import { ProviderList, Providers } from '@llumiverse/common';
+import type { z } from 'zod';
+import type {
+    EnableEnvironmentModelPayloadSchema,
+    ExecutionEnvironmentConfigUpdatePayloadSchema,
+    ExecutionEnvironmentCreatePayloadSchema,
+    ExecutionEnvironmentRefSchema,
+    ExecutionEnvironmentSchema,
+    ExecutionEnvironmentSettingsSchema,
+    ExecutionEnvironmentUpdatePayloadSchema,
+    ListEnvironmentsQuerySchema,
+    LoadBalancingEnvConfigSchema,
+    LoadBalancingEnvEntryConfigSchema,
+    MediatorEnvConfigSchema,
+    MigrateInteractionsPayloadSchema,
+    MigrateInteractionsResultSchema,
+    SupportedProvidersSchema,
+    VirtualEnvEntrySchema,
+} from './api-schemas/environment.js';
 
 // Virtual providers from studio
 export enum CustomProviders {
@@ -8,13 +26,16 @@ export enum CustomProviders {
     test = 'test',
 }
 
-export type SupportedProviders = Providers | CustomProviders;
-
+// The const and the type are one declaration in two halves: the object is what `z.enum()` reads the
+// members off, and the type is inferred back from that schema rather than restated as
+// `Providers | CustomProviders` — which is the same union, but a second statement of it.
 export const SupportedProviders = {
     ...Providers,
     ...CustomProviders,
 } as const;
 
+export type SupportedProviders = z.infer<typeof SupportedProvidersSchema>;
+
 export interface SupportedProviderParams extends Omit<ProviderParams, 'id'> {
     id: SupportedProviders;
 }
@@ -48,50 +69,29 @@ export const SupportedProvidersList: Record<SupportedProviders, SupportedProvide
     ...CustomProvidersList,
 } as const;
 
-export interface VirtualEnvEntry {
-    model: string;
-}
+// The environment contract types, inferred from `./api-schemas/environment.js`. Their documentation
+// moved with them: a doc comment above one of these is published on top of the schema's own
+// `description`, so there would be two statements of it.
+//
+// `LoadBalancingEnvEntryConfig` no longer `extends VirtualEnvEntry` — a mapped or extended type over
+// a canonical alias is opaque to the scanner and would publish as an empty object. It restates
+// `model`, which is what the component has always listed anyway.
+export type VirtualEnvEntry = z.infer<typeof VirtualEnvEntrySchema>;
 
-export interface ListEnvironmentsQuery {
-    all?: boolean;
-}
+export type ListEnvironmentsQuery = z.infer<typeof ListEnvironmentsQuerySchema>;
 
-/**
- * Custom configuration for virtual environments
- **/
-export interface LoadBalancingEnvConfig {
-    entries?: LoadBalancingEnvEntryConfig[];
-    failover?: boolean;
-}
+export type LoadBalancingEnvConfig = z.infer<typeof LoadBalancingEnvConfigSchema>;
 
-export interface LoadBalancingEnvEntryConfig extends VirtualEnvEntry {
-    weight: number;
-}
+export type LoadBalancingEnvEntryConfig = z.infer<typeof LoadBalancingEnvEntryConfigSchema>;
 
-export interface MediatorEnvConfig {
-    entries?: VirtualEnvEntry[];
-    max_concurrent_requests?: number;
-    // the model used to evaluate the responses. If not specified all entries will mediates the response
-    // and the best response will be picked
-    mediators?: VirtualEnvEntry[];
-    model_options?: TextFallbackOptions;
-}
+export type MediatorEnvConfig = z.infer<typeof MediatorEnvConfigSchema>;
 
-export interface TextFallbackOptions {
-    _option_id: 'text-fallback';
-    max_tokens?: number;
-    temperature?: number;
-    top_p?: number;
-    top_k?: number;
-    presence_penalty?: number;
-    frequency_penalty?: number;
-    stop_sequence?: string[];
-}
+// Re-exported, not restated. This file carried a byte-for-byte copy of llumiverse's interface, which
+// published under the same component name — so which of the two the OpenAPI document described
+// depended on which one the scanner reached first. They agreed, so nothing ever failed.
+export type { TextFallbackOptions } from '@llumiverse/common';
 
-export interface ExecutionEnvironmentSettings {
-    [key: string]: unknown;
-    bucket_access_principal?: string;
-}
+export type ExecutionEnvironmentSettings = z.infer<typeof ExecutionEnvironmentSettingsSchema>;
 
 /**
  * Returns the configured Vertex AI bucket access principal for an environment, or undefined.
@@ -106,91 +106,19 @@ export function getVertexBucketAccessPrincipal(
     return typeof principal === 'string' && principal.trim().length > 0 ? principal.trim() : undefined;
 }
 
-export interface ExecutionEnvironment {
-    id: string;
-    name: string;
-    provider: SupportedProviders;
-    description?: string;
-    endpoint_url?: string;
-    default_model?: string;
-    enabled_models?: AIModel[];
-    apiKey?: string;
-    /**
-     * Hint showing first and last characters of the API key (e.g. "AKIA...3xQf").
-     * Stored alongside the encrypted key so the UI can display which key is configured.
-     */
-    apikey_hint?: string;
-    config?: unknown;
-    /**
-     * Additional provider-specific settings passed through to the driver.
-     * For example, custom headers for Apigee-proxied endpoints.
-     */
-    settings?: ExecutionEnvironmentSettings;
-    account: string;
-    allowed_projects?: string[];
-    created_by: string;
-    updated_by: string;
-    created_at: string;
-    updated_at: string;
-}
+export type ExecutionEnvironment = z.infer<typeof ExecutionEnvironmentSchema>;
 
-export interface ExecutionEnvironmentRef {
-    id: string;
-    name: string;
-    provider: SupportedProviders;
-    enabled_models?: AIModel[];
-    default_model?: string;
-    endpoint_url?: string;
-    allowed_projects?: string[];
-    account: string;
-    created_by: string;
-    updated_by: string;
-    created_at: string;
-    updated_at: string;
-}
+export type ExecutionEnvironmentRef = z.infer<typeof ExecutionEnvironmentRefSchema>;
 
-export interface ExecutionEnvironmentCreatePayload
-    extends Omit<
-        ExecutionEnvironment,
-        'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'project' | 'apikey_hint'
-    > {}
-export interface ExecutionEnvironmentUpdatePayload
-    extends Partial<
-        Omit<
-            ExecutionEnvironment,
-            'id' | 'account' | 'created_at' | 'updated_at' | 'created_by' | 'updated_by' | 'apikey_hint'
-        >
-    > {}
-export interface ExecutionEnvironmentConfigUpdatePayload {
-    enabled_models?: AIModel[];
-    config?: MediatorEnvConfig | LoadBalancingEnvConfig;
-}
+// Write payloads have their own named schemas because their fields differ from the read response.
+export type ExecutionEnvironmentCreatePayload = z.infer<typeof ExecutionEnvironmentCreatePayloadSchema>;
 
-export interface EnableEnvironmentModelPayload {
-    /**
-     * Provider model ID to resolve from the environment's available model listing.
-     */
-    model_id: string;
-}
+export type ExecutionEnvironmentUpdatePayload = z.infer<typeof ExecutionEnvironmentUpdatePayloadSchema>;
 
-export interface MigrateInteractionsPayload {
-    /**
-     * The new environment ID to set in the Interactions
-     */
-    new_env_id: string;
-    /**
-     * The new model ID to set in the Interactions
-     */
-    new_model_id: string;
-    /**
-     * The list of Interaction IDs to update.
-     *
-     * The Interactions must be in draft status.
-     */
-    interaction_ids: string[];
-}
+export type ExecutionEnvironmentConfigUpdatePayload = z.infer<typeof ExecutionEnvironmentConfigUpdatePayloadSchema>;
 
-export interface MigrateInteractionsResult {
-    matched_count: number;
-    modified_count: number;
-}
+export type EnableEnvironmentModelPayload = z.infer<typeof EnableEnvironmentModelPayloadSchema>;
+
+export type MigrateInteractionsPayload = z.infer<typeof MigrateInteractionsPayloadSchema>;
+
+export type MigrateInteractionsResult = z.infer<typeof MigrateInteractionsResultSchema>;

package/src/facets.ts

@@ -1,3 +1,5 @@
+import type { z } from 'zod';
+import type { ComputedFacetResponseSchema, FacetSpecSchema } from './api-schemas/interaction.js';
 // this is the mongo definition of a facet. see https://www.mongodb.com/docs/atlas/atlas-search/facet/
 export interface StringFacet {
     type: 'string';
@@ -21,10 +23,7 @@ export interface DateFacet<T extends Date | string = string> {
 
 export type Facet<DateT extends Date | string = string> = StringFacet | NumericFacet | DateFacet<DateT>;
 
-export interface FacetSpec {
-    name: string;
-    field: string;
-}
+export type FacetSpec = z.infer<typeof FacetSpecSchema>;
 
 export interface FacetBucket {
     _id: string;
@@ -46,6 +45,4 @@ export interface ComputedFacetBucket {
     count: number;
 }
 
-export type ComputedFacetResponse = Record<string, ComputedFacetBucket[] | number> & {
-    total?: number;
-};
+export type ComputedFacetResponse = z.infer<typeof ComputedFacetResponseSchema>;

package/src/group.ts

@@ -1,51 +1,47 @@
+import type { z } from 'zod';
+import type {
+    CreateUserGroupPayloadSchema,
+    UpdateUserGroupPayloadSchema,
+    UserGroupRefSchema,
+    UserGroupSchema,
+} from './api-schemas/group.js';
 import type { UserRef } from './user.js';
 
-export interface UserGroup {
-    id: string;
-    account: string;
-    name: string;
-    description?: string;
-    tags: string[];
-    created_at: Date;
-    updated_at: Date;
-    created_by?: string;
-    updated_by?: string;
-    /** Custom properties for dynamic permission matching */
-    properties?: Record<string, unknown>;
-    /** BLP clearance level — merged with user clearance using max() */
-    clearance?: number;
-    /** Compartments — merged with user compartments using array union */
-    compartments?: string[];
-}
+/**
+ * The user group and its payloads as they cross the wire.
+ *
+ * Derived from the schemas in `./api-schemas/group.js`, which are what OpenAPI publishes and AJV
+ * compiles. The field descriptions live there too — Zod reads `.meta()`, not TSDoc.
+ *
+ * NOTE the timestamps are `string`, not `Date`. The document has always published them as
+ * `format: date-time` strings and JSON has no date type, so the previous `Date` declaration
+ * described the Mongoose document rather than the response a client parses. `IUserGroup` in
+ * `@dglabs/server-common` describes what Mongo actually holds and is deliberately independent.
+ */
+export type UserGroup = z.infer<typeof UserGroupSchema>;
+export type CreateUserGroupPayload = z.infer<typeof CreateUserGroupPayloadSchema>;
+export type UpdateUserGroupPayload = z.infer<typeof UpdateUserGroupPayloadSchema>;
 
+/**
+ * A group with its members resolved.
+ *
+ * Not a published component, and deliberately not one: `members` is `select: false` on the model, no
+ * endpoint documents it on `UserGroup`, and the members listing publishes `UserRef[]` on its own
+ * route instead.
+ */
 export interface PopulatesUserGroup extends UserGroup {
     members: UserRef[];
 }
 
-export interface CreateUserGroupPayload {
-    name: string;
-    description?: string;
-    tags?: string[];
-}
-
-export interface UpdateUserGroupPayload {
-    name: string;
-    description?: string;
-    tags?: string[];
-    properties?: Record<string, unknown>;
-    clearance?: number;
-    compartments?: string[];
-}
-
-export interface UserGroupRef {
-    id: string;
-    name: string;
-    tags?: string[];
-    properties?: Record<string, unknown>;
-    clearance?: number;
-    compartments?: string[];
-}
-
-export const UserGroupRefPopulate = 'id name tags description properties clearance compartments';
+/**
+ * The group as it appears in a token payload, read by the servers' authorization layer, the clients
+ * and the integration tests.
+ *
+ * The Mongoose projections that feed it live beside their queries in the servers, not here: a
+ * `select()` string is MongoDB field-selection behaviour, and a shared one has to be the union of
+ * every caller's needs. The previous one selected `description`, which token generation has never
+ * emitted, and the security fields, which the resource-reference endpoint has no use for.
+ */
+export type UserGroupRef = z.infer<typeof UserGroupRefSchema>;
 
 export const MEMBERS_GROUP_NAME = 'members';

package/src/index.ts

@@ -1,6 +1,17 @@
 export * from './access-control.js';
 export * from './agent-request-template.js';
 export * from './analytics.js';
+/**
+ * Schema-derived API types. MUST stay `export type` — tsc erases it, so `lib/index.js` never
+ * references `./api-schemas/*` and zod stays out of the browser bundle. A runtime `export *` here
+ * would ship zod to every UI user; see `./api-schemas/index.ts` for why.
+ */
+export type { UserGroupArrayFromSchema } from './api-schemas/group.js';
+export type {
+    PrincipalContextFromSchema,
+    UserArrayFromSchema,
+    UserRefArrayFromSchema,
+} from './api-schemas/user.js';
 export * from './apikey.js';
 export * from './apps.js';
 export * from './ask-user.js';