@vertesia/common 1.6.0-dev.20260918.090710Z → 1.6.0-dev.20260918.115658Z

package/src/api-schemas/embeddings.ts

@@ -102,10 +102,40 @@ export const EmbeddingsApiRequestSchema = z
     })
     .meta({ id: 'EmbeddingsApiRequest' });
 
+export const EmbeddingBatchRunStateSchema = z.enum([
+    'preparing',
+    'submitted',
+    'running',
+    'applying',
+    'completed',
+    'completed_with_errors',
+    'cancelled',
+    'stale',
+    'failed',
+]);
+
+export const EmbeddingBatchRunSummarySchema = z
+    .strictObject({
+        id: z.string(),
+        state: EmbeddingBatchRunStateSchema,
+        model: z.string(),
+        created_at: z.string().meta({ format: 'date-time' }),
+        completed_at: z.string().meta({ format: 'date-time' }).optional(),
+        applied: z.number().int().nonnegative(),
+        skipped: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        stale: z.number().int().nonnegative(),
+    })
+    .meta({
+        id: 'EmbeddingBatchRunSummary',
+        description: 'Latest batch run for this embedding type, without provider payloads or input content.',
+    });
+
 export const EmbeddingsStatusResponseSchema = z
     .strictObject({
         status: z.string(),
         embeddingRunsInProgress: z.number().optional(),
+        latestBatchRun: EmbeddingBatchRunSummarySchema.optional(),
         totalIndexableObjects: z.number().optional(),
         embeddingsModels: z.array(z.string()).optional(),
         objectsWithEmbeddings: z.number().optional(),
@@ -117,6 +147,25 @@ export const EmbeddingsStatusResponseSchema = z
     })
     .meta({ id: 'EmbeddingsStatusResponse' });
 
+export const RecalculateEmbeddingsQuerySchema = z
+    .strictObject({
+        mode: z
+            .literal('sync')
+            .meta({
+                description:
+                    'Force synchronous per-object recalculation. When omitted, batch inference is used when supported.',
+            })
+            .optional(),
+        force: z
+            .boolean()
+            .meta({
+                description:
+                    'Recalculate all eligible objects, including current embeddings. Token limits still apply; existing renditions are reused.',
+            })
+            .optional(),
+    })
+    .meta({ id: 'RecalculateEmbeddingsQuery' });
+
 export const ProjectConfigurationEmbeddingEnablePayloadSchema = z
     .strictObject({
         environment: z.string(),
@@ -124,3 +173,138 @@ export const ProjectConfigurationEmbeddingEnablePayloadSchema = z
         model: z.string().optional(),
     })
     .meta({ id: 'ProjectConfigurationEmbeddingEnablePayload' });
+
+export const EmbeddingBatchProviderStateSchema = z.enum([
+    'pending',
+    'running',
+    'succeeded',
+    'failed',
+    'cancelled',
+    'paused',
+]);
+
+export const EmbeddingBatchCapabilityRequestSchema = z
+    .strictObject({ embedding_type: SupportedEmbeddingTypesSchema })
+    .meta({ id: 'EmbeddingBatchCapabilityRequest' });
+
+export const EmbeddingBatchCapabilityResponseSchema = z
+    .strictObject({
+        eligible: z.boolean(),
+        reason: z.string().optional(),
+        environment: z.string().optional(),
+        provider: z.string().optional(),
+        model: z.string().optional(),
+        dimensions: z.number().int().positive().optional(),
+        max_tokens: z.number().int().positive().optional(),
+        location: z.string().optional(),
+        input_format: z.string().optional(),
+        max_rows: z.number().int().positive().optional(),
+        artifact_uri: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingBatchCapabilityResponse' });
+
+export const EmbeddingBatchCreateRequestSchema = z
+    .strictObject({
+        embedding_type: SupportedEmbeddingTypesSchema,
+        model: z.string(),
+        dimensions: z.number().int().positive(),
+        display_name: z.string(),
+        input_uri: z.string(),
+        output_uri: z.string(),
+    })
+    .meta({ id: 'EmbeddingBatchCreateRequest' });
+
+export const EmbeddingBatchJobRequestSchema = z
+    .strictObject({
+        embedding_type: SupportedEmbeddingTypesSchema,
+        model: z.string(),
+        name: z.string(),
+        include_output_artifacts: z.boolean().optional().meta({
+            description:
+                'On get, resolve terminal result artifacts for application. Omit for lightweight status polling.',
+        }),
+    })
+    .meta({ id: 'EmbeddingBatchJobRequest' });
+
+export const EmbeddingBatchJobResponseSchema = z
+    .strictObject({
+        name: z.string(),
+        display_name: z.string().optional(),
+        state: EmbeddingBatchProviderStateSchema,
+        model: z.string().optional(),
+        input_uri: z.string().optional(),
+        output_uri: z.string().optional(),
+        output_artifacts: z.array(z.string()).optional().meta({
+            description:
+                'Terminal job result artifacts in application storage, including partial results. Never provider file IDs.',
+        }),
+        error_message: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingBatchJobResponse' });
+
+export const EmbeddingBatchPrepareRequestSchema = z
+    .strictObject({
+        run_id: z.string(),
+        embedding_type: SupportedEmbeddingTypesSchema,
+        capability: EmbeddingBatchCapabilityResponseSchema,
+    })
+    .meta({ id: 'EmbeddingBatchPrepareRequest' });
+
+export const EmbeddingBatchSubjobSchema = z.strictObject({
+    index: z.number().int().nonnegative(),
+    display_name: z.string(),
+    input_uri: z.string(),
+    output_uri: z.string(),
+    row_count: z.number().int().nonnegative(),
+    provider_name: z.string().optional(),
+    state: EmbeddingBatchProviderStateSchema.optional(),
+});
+
+export const EmbeddingBatchPrepareResponseSchema = z
+    .strictObject({
+        run_id: z.string(),
+        row_count: z.number().int().nonnegative(),
+        subjobs: z.array(EmbeddingBatchSubjobSchema),
+    })
+    .meta({ id: 'EmbeddingBatchPrepareResponse' });
+
+export const EmbeddingBatchRenditionPageRequestSchema = z
+    .strictObject({ run_id: z.string() })
+    .meta({ id: 'EmbeddingBatchRenditionPageRequest' });
+
+export const EmbeddingBatchRenditionPageResponseSchema = z
+    .strictObject({
+        status: z.enum(['running', 'page_completed', 'completed']),
+        page_index: z.number().int().nonnegative(),
+        page_scanned: z.number().int().nonnegative(),
+        page_ready: z.number().int().nonnegative(),
+        page_generated: z.number().int().nonnegative(),
+        page_failed: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+    })
+    .meta({ id: 'EmbeddingBatchRenditionPageResponse' });
+
+export const EmbeddingBatchUpdateRequestSchema = z
+    .strictObject({
+        run_id: z.string(),
+        state: EmbeddingBatchRunStateSchema,
+        subjobs: z.array(EmbeddingBatchSubjobSchema).optional(),
+        error_code: z.string().optional(),
+        error_message: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingBatchUpdateRequest' });
+
+export const EmbeddingBatchApplyRequestSchema = z
+    .strictObject({ run_id: z.string() })
+    .meta({ id: 'EmbeddingBatchApplyRequest' });
+
+export const EmbeddingBatchApplyResponseSchema = z
+    .strictObject({
+        state: EmbeddingBatchRunStateSchema,
+        succeeded: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        stale: z.number().int().nonnegative(),
+        applied: z.number().int().nonnegative(),
+        failure_counts: z.record(z.string(), z.number().int().nonnegative()).optional(),
+    })
+    .meta({ id: 'EmbeddingBatchApplyResponse' });

package/src/api-schemas/files.ts

@@ -74,6 +74,7 @@ export const BulkUploadUrlsPayloadSchema = z
 export const FileBucketResponseSchema = z
     .strictObject({
         bucket: z.string(),
+        location: z.string().optional(),
     })
     .meta({ id: 'FileBucketResponse' });
 

package/src/api-schemas/indexing.contract.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { GenericCommandResponse } from '../common.js';
+import type { RecalculateEmbeddingsQuery } from '../embeddings.js';
 import type {
     DriftAnalysisStatusResponse,
     EmbeddingsStatusResponse,
@@ -11,7 +12,11 @@ import type {
 } from '../project.js';
 import { WorkflowExecutionStatus } from '../store/workflow.js';
 import type { GenericCommandResponseSchema } from './commands.js';
-import type { EmbeddingsStatusResponseSchema, ProjectConfigurationEmbeddingEnablePayloadSchema } from './embeddings.js';
+import type {
+    EmbeddingsStatusResponseSchema,
+    ProjectConfigurationEmbeddingEnablePayloadSchema,
+    RecalculateEmbeddingsQuerySchema,
+} from './embeddings.js';
 import type {
     DriftAnalysisStatusResponseSchema,
     IndexingStatusResponseSchema,
@@ -28,6 +33,7 @@ describe('indexing and embedding API contracts', () => {
     it('derives every public type from its domain schema', () => {
         assertType<Equals<GenericCommandResponse, typeof GenericCommandResponseSchema._output>>(true);
         assertType<Equals<EmbeddingsStatusResponse, typeof EmbeddingsStatusResponseSchema._output>>(true);
+        assertType<Equals<RecalculateEmbeddingsQuery, typeof RecalculateEmbeddingsQuerySchema._output>>(true);
         assertType<Equals<IndexingStatusResponse, typeof IndexingStatusResponseSchema._output>>(true);
         assertType<Equals<DriftAnalysisStatusResponse, typeof DriftAnalysisStatusResponseSchema._output>>(true);
         assertType<
@@ -51,6 +57,39 @@ describe('indexing and embedding API contracts', () => {
         );
     });
 
+    it('allows only the explicit synchronous embedding recalculation override', () => {
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', {}).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { mode: 'sync' }).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { force: true }).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { mode: 'sync', force: true }).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { force_renditions: true }).valid).toBe(false);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { mode: 'batch' }).valid).toBe(false);
+    });
+
+    it('validates the optional batch summary without exposing stored run fields', () => {
+        const summary = {
+            id: 'run-1',
+            state: 'completed_with_errors',
+            model: 'model-1',
+            created_at: '2026-01-01T00:00:00Z',
+            applied: 110,
+            skipped: 17,
+            failed: 0,
+            stale: 0,
+        };
+        expect(
+            validateApiResponse('EmbeddingsStatusResponse', {
+                status: 'success',
+                vectorIndex: { status: 'READY' },
+                latestBatchRun: summary,
+            }).valid,
+        ).toBe(true);
+        expect(validateApiResponse('EmbeddingBatchRunSummary', { ...summary, applied: -1 }).valid).toBe(false);
+        expect(validateApiResponse('EmbeddingBatchRunSummary', { ...summary, prefix_uri: 'private' }).valid).toBe(
+            false,
+        );
+    });
+
     it('keeps drift workflow status numeric and nullable identifiers explicit', () => {
         expect(
             validateApiResponse('DriftAnalysisStatusResponse', {

package/src/api-schemas/mcp-api-key.contract.test.ts

@@ -84,3 +84,42 @@ describe('McpApiKeyStatus', () => {
         );
     });
 });
+
+describe('MCP anonymous authentication — emitted contract', () => {
+    const collection = {
+        type: 'mcp',
+        id: 'public',
+        name: 'Public tools',
+        description: 'Public tools',
+        namespace: 'public',
+        url: 'https://example.com/mcp',
+    };
+
+    it.each(['none', 'oauth', 'api_key', 'other', undefined])('accepts auth=%s', (auth) => {
+        expect(
+            validateApiRequest('AppManifestData', {
+                name: 'public-mcp',
+                title: 'Public MCP',
+                description: 'Public tools',
+                publisher: 'Vertesia',
+                status: 'beta',
+                visibility: 'private',
+                tool_collections: [{ ...collection, auth }],
+            }).valid,
+        ).toBe(true);
+    });
+
+    it('rejects unknown authentication modes', () => {
+        expect(
+            validateApiRequest('AppManifestData', {
+                name: 'public-mcp',
+                title: 'Public MCP',
+                description: 'Public tools',
+                publisher: 'Vertesia',
+                status: 'beta',
+                visibility: 'private',
+                tool_collections: [{ ...collection, auth: 'anonymous' }],
+            }).valid,
+        ).toBe(false);
+    });
+});

package/src/api-schemas/registry.ts

@@ -370,6 +370,22 @@ import {
     WorkflowExecutionStatusSchema,
 } from './document-processing.js';
 import {
+    EmbeddingBatchApplyRequestSchema,
+    EmbeddingBatchApplyResponseSchema,
+    EmbeddingBatchCapabilityRequestSchema,
+    EmbeddingBatchCapabilityResponseSchema,
+    EmbeddingBatchCreateRequestSchema,
+    EmbeddingBatchJobRequestSchema,
+    EmbeddingBatchJobResponseSchema,
+    EmbeddingBatchPrepareRequestSchema,
+    EmbeddingBatchPrepareResponseSchema,
+    EmbeddingBatchProviderStateSchema,
+    EmbeddingBatchRenditionPageRequestSchema,
+    EmbeddingBatchRenditionPageResponseSchema,
+    EmbeddingBatchRunStateSchema,
+    EmbeddingBatchRunSummarySchema,
+    EmbeddingBatchSubjobSchema,
+    EmbeddingBatchUpdateRequestSchema,
     EmbeddingsApiAudioInputSchema,
     EmbeddingsApiImageInputSchema,
     EmbeddingsApiInputSchema,
@@ -379,6 +395,7 @@ import {
     EmbeddingsApiVideoInputSchema,
     EmbeddingsStatusResponseSchema,
     ProjectConfigurationEmbeddingEnablePayloadSchema,
+    RecalculateEmbeddingsQuerySchema,
 } from './embeddings.js';
 import { emitJsonSchema } from './emit-json-schema.js';
 import {
@@ -1476,7 +1493,24 @@ const INDEXING_SCHEMAS = {
 
 const EMBEDDING_ADMIN_SCHEMAS = {
     EmbeddingsStatusResponse: EmbeddingsStatusResponseSchema,
+    RecalculateEmbeddingsQuery: RecalculateEmbeddingsQuerySchema,
     ProjectConfigurationEmbeddingEnablePayload: ProjectConfigurationEmbeddingEnablePayloadSchema,
+    EmbeddingBatchProviderState: EmbeddingBatchProviderStateSchema,
+    EmbeddingBatchCapabilityRequest: EmbeddingBatchCapabilityRequestSchema,
+    EmbeddingBatchCapabilityResponse: EmbeddingBatchCapabilityResponseSchema,
+    EmbeddingBatchCreateRequest: EmbeddingBatchCreateRequestSchema,
+    EmbeddingBatchJobRequest: EmbeddingBatchJobRequestSchema,
+    EmbeddingBatchJobResponse: EmbeddingBatchJobResponseSchema,
+    EmbeddingBatchRunState: EmbeddingBatchRunStateSchema,
+    EmbeddingBatchRunSummary: EmbeddingBatchRunSummarySchema,
+    EmbeddingBatchSubjob: EmbeddingBatchSubjobSchema,
+    EmbeddingBatchPrepareRequest: EmbeddingBatchPrepareRequestSchema,
+    EmbeddingBatchPrepareResponse: EmbeddingBatchPrepareResponseSchema,
+    EmbeddingBatchRenditionPageRequest: EmbeddingBatchRenditionPageRequestSchema,
+    EmbeddingBatchRenditionPageResponse: EmbeddingBatchRenditionPageResponseSchema,
+    EmbeddingBatchUpdateRequest: EmbeddingBatchUpdateRequestSchema,
+    EmbeddingBatchApplyRequest: EmbeddingBatchApplyRequestSchema,
+    EmbeddingBatchApplyResponse: EmbeddingBatchApplyResponseSchema,
 } as const satisfies Record<string, z.ZodType>;
 
 const COMMAND_SCHEMAS = {
@@ -2799,6 +2833,8 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'DriftAnalysisResult',
     'DriftAnalysisProgress',
     'EmbeddingsStatusResponse',
+    'EmbeddingBatchRunSummary',
+    'RecalculateEmbeddingsQuery',
     'ProjectConfigurationEmbeddingEnablePayload',
     'GenericCommandResponse',
     'DriftAnalysisStatusResponse',

package/src/embeddings.ts

@@ -1,6 +1,22 @@
 import type { EmbeddingsResult } from '@llumiverse/common';
 import type { z } from 'zod';
 import type {
+    EmbeddingBatchApplyRequestSchema,
+    EmbeddingBatchApplyResponseSchema,
+    EmbeddingBatchCapabilityRequestSchema,
+    EmbeddingBatchCapabilityResponseSchema,
+    EmbeddingBatchCreateRequestSchema,
+    EmbeddingBatchJobRequestSchema,
+    EmbeddingBatchJobResponseSchema,
+    EmbeddingBatchPrepareRequestSchema,
+    EmbeddingBatchPrepareResponseSchema,
+    EmbeddingBatchProviderStateSchema,
+    EmbeddingBatchRenditionPageRequestSchema,
+    EmbeddingBatchRenditionPageResponseSchema,
+    EmbeddingBatchRunStateSchema,
+    EmbeddingBatchRunSummarySchema,
+    EmbeddingBatchSubjobSchema,
+    EmbeddingBatchUpdateRequestSchema,
     EmbeddingsApiAudioInputSchema,
     EmbeddingsApiImageInputSchema,
     EmbeddingsApiInputSchema,
@@ -8,6 +24,7 @@ import type {
     EmbeddingsApiSourceSchema,
     EmbeddingsApiTextInputSchema,
     EmbeddingsApiVideoInputSchema,
+    RecalculateEmbeddingsQuerySchema,
 } from './api-schemas/embeddings.js';
 
 /**
@@ -36,3 +53,20 @@ export type EmbeddingsApiRequest = z.infer<typeof EmbeddingsApiRequestSchema>;
  * that prefer to consume types from @vertesia/common.
  */
 export type EmbeddingsApiResult = EmbeddingsResult;
+export type RecalculateEmbeddingsQuery = z.infer<typeof RecalculateEmbeddingsQuerySchema>;
+export type EmbeddingBatchCapabilityRequest = z.infer<typeof EmbeddingBatchCapabilityRequestSchema>;
+export type EmbeddingBatchCapabilityResponse = z.infer<typeof EmbeddingBatchCapabilityResponseSchema>;
+export type EmbeddingBatchCreateRequest = z.infer<typeof EmbeddingBatchCreateRequestSchema>;
+export type EmbeddingBatchJobRequest = z.infer<typeof EmbeddingBatchJobRequestSchema>;
+export type EmbeddingBatchJobResponse = z.infer<typeof EmbeddingBatchJobResponseSchema>;
+export type EmbeddingBatchProviderState = z.infer<typeof EmbeddingBatchProviderStateSchema>;
+export type EmbeddingBatchRunState = z.infer<typeof EmbeddingBatchRunStateSchema>;
+export type EmbeddingBatchRunSummary = z.infer<typeof EmbeddingBatchRunSummarySchema>;
+export type EmbeddingBatchSubjob = z.infer<typeof EmbeddingBatchSubjobSchema>;
+export type EmbeddingBatchPrepareRequest = z.infer<typeof EmbeddingBatchPrepareRequestSchema>;
+export type EmbeddingBatchPrepareResponse = z.infer<typeof EmbeddingBatchPrepareResponseSchema>;
+export type EmbeddingBatchRenditionPageRequest = z.infer<typeof EmbeddingBatchRenditionPageRequestSchema>;
+export type EmbeddingBatchRenditionPageResponse = z.infer<typeof EmbeddingBatchRenditionPageResponseSchema>;
+export type EmbeddingBatchUpdateRequest = z.infer<typeof EmbeddingBatchUpdateRequestSchema>;
+export type EmbeddingBatchApplyRequest = z.infer<typeof EmbeddingBatchApplyRequestSchema>;
+export type EmbeddingBatchApplyResponse = z.infer<typeof EmbeddingBatchApplyResponseSchema>;

package/src/index.ts

@@ -57,6 +57,7 @@ export * from './schema-for-extraction.js';
 export * from './secrets.js';
 export * from './skill.js';
 export * from './store/index.js';
+export * from './store/rendering.js';
 export type {
     ContentObjectExportArtifact,
     ContentObjectExportArtifactFile,

package/src/store/rendering.ts

@@ -43,6 +43,15 @@ export function getRenditionsPath(contentEtag: string, params: ImageRenditionPar
     return `renditions/${contentEtag}/${params.max_hw}`;
 }
 
+export function getRenditionPagePath(
+    contentEtag: string,
+    params: ImageRenditionParams,
+    pageNumber: number | string = 0,
+) {
+    const page = typeof pageNumber === 'number' ? String(pageNumber).padStart(4, '0') : pageNumber;
+    return `${getRenditionsPath(contentEtag, params)}/${page}.${params.format}`;
+}
+
 /** Metadata for PDF rendering, inferred from the published API schema. */
 export type PdfRenderingMetadata = z.infer<typeof PdfRenderingMetadataSchema>;