@vertesia/common 0.24.0-dev.202601221707

package/src/sts-token-types.ts

@@ -0,0 +1,117 @@
+/**
+ * STS Token Request Types
+ * These types define the structure for token requests to the Security Token Service
+ */
+
+export type TokenType = 'apikey' | 'user' | 'project' | 'environment' | 'agent' | 'service_account';
+export type SigningAlgorithm = 'ES256' | 'RS256';
+
+interface BaseTokenRequest {
+    type: TokenType;
+    audience?: string;
+    /** Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility. */
+    algorithm?: SigningAlgorithm;
+}
+
+// API key doesn't need account/project as it's determined from the key
+export interface ApiKeyTokenRequest extends BaseTokenRequest {
+    type: 'apikey';
+    key: string;
+}
+
+// User token needs optional account/project for scoping
+export interface UserTokenRequest extends BaseTokenRequest {
+    type: 'user';
+    user_id?: string; // Optional - can be determined from auth token
+    account_id?: string; // Optional - for scoping to specific account
+    project_id?: string; // Optional - for scoping to specific project
+    expires_at?: number;
+
+    on_behalf_of?: string; // Optional - user ID when acting on behalf of another user
+}
+
+// Project token requires project_id and account_id
+export interface ProjectTokenRequest extends BaseTokenRequest {
+    type: 'project';
+    project_id: string;
+    account_id: string;
+}
+
+// Environment token requires IDs - names fetched from DB
+export interface EnvironmentTokenRequest extends BaseTokenRequest {
+    type: 'environment';
+    environment_id: string;
+    environment_name: string; // Still required as environments may not be in DB
+    project_id: string; // Will fetch name and verify account
+    account_id: string; // Will fetch name and verify project belongs to it
+}
+
+// Agent token for service accounts acting as agents
+export interface AgentTokenRequest extends BaseTokenRequest {
+    type: 'agent';
+    account_id: string;
+    project_id: string; // Will verify it belongs to account
+    name?: string;
+    on_behalf_of: string; // Required: signed Vertesia token to verify user context
+}
+
+// Service account token
+export interface ServiceAccountTokenRequest extends BaseTokenRequest {
+    type: 'service_account';
+    account_id: string;
+    project_id: string; // Will verify it belongs to account
+    roles?: string[]; // Optional - roles for the service account token
+    name?: string;
+}
+
+export type IssueTokenRequest =
+    | ApiKeyTokenRequest
+    | UserTokenRequest
+    | ProjectTokenRequest
+    | EnvironmentTokenRequest
+    | AgentTokenRequest
+    | ServiceAccountTokenRequest;
+
+export interface RefreshTokenRequest {
+    token: string;
+}
+
+export interface RevokeTokenRequest {
+    token: string;
+}
+
+// Helper type guards for type narrowing
+export function isApiKeyRequest(req: IssueTokenRequest): req is ApiKeyTokenRequest {
+    return req.type === 'apikey';
+}
+
+export function isUserRequest(req: IssueTokenRequest): req is UserTokenRequest {
+    return req.type === 'user';
+}
+
+export function isProjectRequest(req: IssueTokenRequest): req is ProjectTokenRequest {
+    return req.type === 'project';
+}
+
+export function isEnvironmentRequest(req: IssueTokenRequest): req is EnvironmentTokenRequest {
+    return req.type === 'environment';
+}
+
+export function isAgentRequest(req: IssueTokenRequest): req is AgentTokenRequest {
+    return req.type === 'agent';
+}
+
+export function isServiceAccountRequest(req: IssueTokenRequest): req is ServiceAccountTokenRequest {
+    return req.type === 'service_account';
+}
+
+// Response types
+export interface TokenResponse {
+    token: string;
+}
+
+export interface ValidateTokenResponse {
+    valid: boolean;
+    payload?: any;
+    error?: string;
+}

package/src/tenant.ts

@@ -0,0 +1,10 @@
+/**
+ * This interface is used only on the client side and is shared between @vertesia/ui/session and the main app.
+ */
+export interface UIResolvedTenant {
+    firebaseTenantId: string;
+    label?: string;
+    logo?: string;
+    provider?: string;
+    name?: string;
+}

package/src/tool-execution.ts

@@ -0,0 +1,47 @@
+/**
+ * Types for tool execution payloads shared between workflows and tool servers
+ */
+
+/**
+ * Endpoint configuration that can override JWT-embedded endpoints
+ */
+export interface ToolEndpointOverrides {
+    /**
+     * Studio server URL
+     */
+    studio?: string;
+    /**
+     * Store/Zeno server URL
+     */
+    store?: string;
+    /**
+     * Token server URL
+     */
+    token?: string;
+}
+
+/**
+ * Metadata passed with tool execution requests from workflows to tool servers
+ */
+export interface ToolExecutionMetadata {
+    /**
+     * Workflow run ID
+     */
+    run_id?: string;
+    /**
+     * App installation ID
+     */
+    app_install_id?: string;
+    /**
+     * App-specific settings
+     */
+    app_settings?: Record<string, any>;
+    /**
+     * Endpoint overrides from workflow config (takes precedence over JWT endpoints)
+     */
+    endpoints?: ToolEndpointOverrides;
+    /**
+     * Additional metadata fields
+     */
+    [key: string]: any;
+}

package/src/training.ts

@@ -0,0 +1,44 @@
+import type { TrainingJob } from "@llumiverse/common";
+import { ExecutionEnvironmentRef } from "./environment.js";
+
+export enum TrainingSessionStatus {
+    'created' = 'created',
+    'building' = 'building',
+    'prepared' = 'prepared',
+    'processing' = 'processing',
+    'completed' = 'completed',
+    'cancelled' = 'cancelled',
+    'failed' = 'failed'
+}
+
+export interface TrainingSession {
+    id: string;
+    project: string;
+    name: string
+    env: ExecutionEnvironmentRef,
+    model: string,
+    status: TrainingSessionStatus,
+    runs: string[],
+    dataset: string, //the name of the file dataset which was generated in GCS
+    job: TrainingJob,
+    created_by: string,
+    updated_by: string,
+    created_at: Date,
+    updated_at: Date,
+}
+
+export interface TrainingSessionRef extends Omit<TrainingSession, 'runs'> {
+}
+
+
+export interface TrainingSessionCreatePayload {
+    name: string
+    env: string,
+    model: string,
+}
+
+export interface ListTrainingSessionsQuery {
+    limit?: number;
+    offset?: number;
+    status?: TrainingSessionStatus;
+}

package/src/transient-tokens.ts

@@ -0,0 +1,30 @@
+import { ProjectRef, ProjectRoles } from "./project.js";
+import { AccountRef, UserRef } from "./user.js";
+
+
+export enum TransientTokenType {
+    userInvite = 'user-invite',
+    migration = 'migration',
+}
+
+export interface TransientToken<T> {
+    id: string;
+    type: TransientTokenType;
+    data: T;
+    expires: Date;
+    account?: string;
+    created_at: Date;
+    updated_at: Date;
+}
+
+
+export interface CreateOrUpdateTransientTokenPayload<T> extends Partial<TransientToken<T>> {
+}
+
+export interface UserInviteTokenData {
+    email: string;
+    role: ProjectRoles;
+    account: AccountRef;
+    project: ProjectRef;
+    invited_by: UserRef;
+}

package/src/user.ts

@@ -0,0 +1,153 @@
+import { ApiKey } from "./apikey.js";
+import { ProjectRoles } from "./project.js";
+
+export interface UserWithAccounts extends User {
+    accounts: AccountRef[];
+}
+
+
+export interface User {
+    id: string;
+    externalId: string;
+    email: string;
+    name: string;
+    username?: string;
+    picture?: string;
+    language?: string;
+    phone?: string;
+    sign_in_provider?: string;
+    last_selected_account?: string;
+    source?: 'firebase' | 'scim';
+}
+
+
+export interface UserRef {
+    id: string;
+    name: string;
+    email: string;
+    picture?: string;
+}
+
+export const UserRefPopulate = "id name email picture";
+
+export enum Datacenters {
+    aws = 'aws',
+    gcp = 'gcp',
+    azure = 'azure'
+}
+
+
+export enum BillingMethod {
+    stripe = 'stripe',
+    invoice = 'invoice'
+}
+
+export enum AccountType {
+    vertesia = 'vertesia',
+    partner = 'partner',
+    free = 'free',
+    customer = 'customer',
+    unknown = 'unknown'
+}
+
+export interface AccountBilling {
+    method: BillingMethod;
+    stripe_customer_id?: string;
+}
+
+
+export interface Account {
+    id: string;
+    name: string;
+
+    email_domains: string[];
+
+    onboarding: {
+        completed: boolean,
+        completed_at: Date,
+    };
+
+    datacenter: string;
+
+    account_type: AccountType;
+
+    billing: AccountBilling;
+
+    created_by: string;
+    updated_by: string;
+    created_at: string;
+    updated_at: string;
+}
+
+
+export interface UpdateAccountPayload {
+    name?: string;
+    email_domains?: string[];
+    billing?: AccountBilling;
+}
+
+
+export interface AccountRef {
+    id: string;
+    name: string;
+}
+
+export const AccountRefPopulate = "id name";
+
+export interface InviteUserRequestPayload {
+    email: string;
+    role: ProjectRoles;
+}
+
+
+export interface InviteUserResponsePayload {
+    action: 'invited' | 'added';
+}
+
+
+
+type UserOrApiKey<T extends User | ApiKey> = T extends User ? User : ApiKey;
+type SessionType<T extends User | ApiKey> = T extends User ? "user" : "apikey";
+export interface SessionInfo<T extends User | ApiKey> {
+    isNew?: boolean;
+    type: SessionType<T>;
+    subject: UserOrApiKey<T>;
+    //User | ApiKey; // no user if using an apikey
+    current_account: Account;
+    //role: string; // TODO the role on the selected account
+    accounts: AccountRef[];
+}
+
+
+export interface UserSessionInfo extends SessionInfo<User> { }
+export interface ApiKeySessionInfo extends SessionInfo<ApiKey> { }
+
+export interface OnboardingProgress {
+    interactions: boolean,
+    prompts: boolean,
+    environments: boolean,
+    default_environment_defined: boolean
+}
+
+
+
+/**
+ * Data collected at signup
+ * used for onboarding and segments
+ **/
+export interface SignupData {
+    accountType: string;
+    companyName?: string;
+    companySize?: number;
+    companyWebsite?: string;
+    maturity?: string;
+}
+
+
+/**
+ * Signup Payload: used to create a new user
+ */
+export interface SignupPayload {
+    firebaseToken: string;
+    signupData: SignupData;
+}

package/src/utils/auth.ts

@@ -0,0 +1,12 @@
+import { ProjectRef } from "../project.js";
+
+export function getTenantId(accountId: string, projectId: string): string {
+    //use the last 6 characters of the accountId as the db name
+    //as in mongo the last 6 char are an incrementing counter
+    const accountLast6 = accountId.slice(-6);
+    const projectLast6 = projectId.slice(-6);
+    return accountLast6 + '_' + projectLast6;
+}
+export function getTenantIdFromProject(project: ProjectRef): string {
+    return getTenantId(project.account, project.id);
+}

package/src/utils/schemas.ts

@@ -0,0 +1,108 @@
+import type { JSONSchema } from "@llumiverse/common";
+import { PromptRole } from "@llumiverse/common";
+import type { JSONSchema4 } from "json-schema";
+import { InCodePrompt, InteractionRefWithSchema, PopulatedInteraction } from "../interaction.js";
+import { ExecutablePromptSegmentDef, PromptSegmentDefType } from "../prompt.js";
+
+
+// Remove custom properties from the JSON before sending further down execution pipeline
+export function removeExtraProperties<T>(schema: T): T {
+    if (!schema) return schema;
+    if (Array.isArray(schema)) {
+        for (const item of schema) {
+            removeExtraProperties(item);
+        }
+    } else if (typeof schema === 'object') {
+        const obj = schema as Record<string, any>;
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === 'editor' && (value === 'textarea' || value === 'document' || value === 'media')) {
+                delete obj[key];
+            } else if (key === 'format' && (value === 'textarea' || value === 'document' || value === 'media')) {
+                delete obj[key];
+            } else if (typeof value === 'object') {
+                removeExtraProperties(value)
+            }
+        }
+    }
+    return schema;
+}
+
+export function mergeJSONSchemas(schemas: JSONSchema[]) {
+    const props: Record<string, JSONSchema4> = {};
+    let required: string[] = [];
+    for (const schema of schemas) {
+        if (schema.properties) {
+            if (schema.required) {
+                for (const prop of schema.required as string[]) {
+                    if (!required.includes(prop)) required.push(prop);
+                }
+            }
+            Object.assign(props, schema.properties);
+        }
+    }
+    const schema = Object.keys(props).length > 0 ? { properties: props, required, type: 'object' } as JSONSchema : null;
+    return schema;
+}
+
+export function _mergePromptsSchema(prompts: ExecutablePromptSegmentDef[]) {
+    const props: Record<string, JSONSchema4> = {};
+    let required = new Set<String>();
+    for (const prompt of prompts) {
+        if (prompt.template?.inputSchema?.properties) {
+            const schema = prompt.template?.inputSchema;
+            if (schema.required) {
+                for (const prop of schema.required as string[]) {
+                    required.add(prop);
+                }
+            }
+            Object.assign(props, schema.properties);
+        } else if (prompt.type === PromptSegmentDefType.chat) {
+            Object.assign(props, {
+                chat: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            role: {
+                                type: 'string',
+                                enum: [PromptRole.assistant, PromptRole.user]
+                            },
+                            content: { type: 'string' },
+                        },
+                        required: ['role', 'content']
+                    }
+                }
+            });
+            required.add('chat');
+        }
+    }
+    return Object.keys(props).length > 0 ? {
+        properties: props,
+        required: Array.from(required)
+    } as JSONSchema4 : null;
+}
+
+export function mergePromptsSchema(interaction: InteractionRefWithSchema | PopulatedInteraction) {
+    if (!interaction.prompts) return null;
+    return _mergePromptsSchema(interaction.prompts as ExecutablePromptSegmentDef[]);
+}
+
+export function mergeInCodePromptSchemas(prompts: InCodePrompt[]) {
+    const props: Record<string, JSONSchema> = {};
+    let required = new Set<String>();
+    for (const prompt of prompts) {
+        if (prompt.schema?.properties) {
+            const schema = prompt.schema;
+            if (schema.required) {
+                for (const prop of schema.required as string[]) {
+                    required.add(prop);
+                }
+            }
+            Object.assign(props, schema.properties);
+        }
+    }
+    return Object.keys(props).length > 0 ? {
+        properties: props,
+        required: Array.from(required)
+    } as JSONSchema : null;
+}

package/src/utils/type-helpers.ts

@@ -0,0 +1,6 @@
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
+    Pick<T, Exclude<keyof T, Keys>> &
+    {
+        [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>
+    }[Keys];
+

package/src/versions.ts

@@ -0,0 +1,3 @@
+export enum ApiVersions {
+    COMPLETION_RESULT_V1 = 20250925,
+}