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

package/lib/api-schemas/registry.js

@@ -7,13 +7,13 @@ import ajvFormats from 'ajv-formats';
 import { z } from 'zod';
 import { ACECreatePayloadSchema, ACEUpdatePayloadSchema, AccessControlEntryArraySchema, AccessControlEntrySchema, RoleDefinitionArraySchema, SystemRoleDefinitionArraySchema, } from './access-control.js';
 import { AccountSchema, StripeBillingStatusResponseSchema, UpdateAccountPayloadSchema } from './account.js';
-import { findUnprunablePaths, pruneToSchema, toOpenApiComponents } from './adapter.js';
+import { findUnprunablePaths, isPlainObject, pruneToSchema, toOpenApiComponents } from './adapter.js';
 import * as AgentRunSchemas from './agent-runs.js';
 import { AnalyticsAxisSchema, RunAnalyticsGroupBySchema, RunAnalyticsQuerySchema, RunAnalyticsResultArraySchema, RunAnalyticsResultSchema, TimeResolutionSchema, } from './analytics.js';
 import { ApiKeyArraySchema, ApiKeyListQuerySchema, ApiKeyReadQuerySchema, ApiKeyReadResponseSchema, ApiKeySchema, ApiKeyWithValueSchema, AuthTokenResponseSchema, CreateApiKeyPayloadSchema, DeleteOperationResultSchema, ProjectRefArraySchema, UpdateApiKeyPayloadSchema, } from './apikey.js';
-import { AgentRunSearchHitSchema, AgentRunStatusSchema, AgentRunTypeSchema, AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppPackageScopeSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionArraySchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordArraySchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, ContentObjectTypeRefSchema, ConversationActivityStateSchema, DeleteAppVersionResponseSchema, EventRefSchema, Extract_AppVersionGitRefType_branch_tag_commitSchema, InCodeTypeRefSchema, OAuthClientCredentialsMapSchema, OAuthClientCredentialsSchema, RunKindSchema, RunTypeSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, StoredTypeRefSchema, SystemPackageQuerySchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema, } from './app-lifecycle.js';
+import { AgentRunSearchHitSchema, AgentRunStatusSchema, AgentRunTypeSchema, AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppApiKeyCollectionParamsSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDeleteSummarySchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppPackageScopeSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionArraySchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordArraySchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, ContentObjectTypeRefSchema, ConversationActivityStateSchema, DeleteAppVersionResponseSchema, EventRefSchema, Extract_AppVersionGitRefType_branch_tag_commitSchema, InCodeTypeRefSchema, McpApiKeyCredentialSchema, OAuthClientCredentialsMapSchema, OAuthClientCredentialsSchema, RunKindSchema, RunTypeSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, StoredTypeRefSchema, SystemPackageQuerySchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema, } from './app-lifecycle.js';
 import * as AppRuntimeSchemas from './app-runtime.js';
-import { AppAccessControlSchema, AppCapabilitiesSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPToolAnnotationsSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusArraySchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, ToolCollectionObjectSchema, } from './apps.js';
+import { AppAccessControlSchema, AppCapabilitiesSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPToolAnnotationsSchema, McpApiKeyStatusSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusArraySchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, SetMcpApiKeyRequestSchema, ToolCollectionObjectSchema, } from './apps.js';
 import { AuditActionSchema, AuditAggregationDetailFieldSchema, AuditAggregationDetailFilterSchema, AuditAggregationDimensionMapSchema, AuditAggregationDimensionSchema, AuditAggregationDistinctFieldSchema, AuditAggregationFilterSchema, AuditAggregationGroupSchema, AuditAggregationMetricSchema, AuditAggregationOperationSchema, AuditAggregationQuerySchema, AuditAggregationResolutionSchema, AuditAggregationResponseSchema, AuditAggregationRowSchema, AuditMeterSchema, AuditTrailEventSchema, AuditTrailQuerySchema, AuditTrailResponseSchema, EventCategorySchema, KnownAuditActionSchema, } from './audit-trail.js';
 import { BulkObjectCreateResultSchema, BulkObjectDeleteResultSchema, BulkObjectUpdateResultSchema, BulkOperationPayloadSchema, BulkOperationResponseSchema, BulkOperationResultSchema, } from './bulk-operation.js';
 import { DeleteCountResultSchema, GenericCommandResponseSchema, MigrationListResponseSchema, RunMigrationPayloadSchema, RunMigrationResponseSchema, } from './commands.js';
@@ -863,17 +863,21 @@ const EVENT_DELIVERY_SCHEMAS = {
     EventOutboxStatus: EventSchemas.EventOutboxStatusSchema,
     EventDeliverySortField: EventSchemas.EventDeliverySortFieldSchema,
     WebhookEventDeliveryTarget: EventSchemas.WebhookEventDeliveryTargetSchema,
+    AppEventDeliveryTarget: EventSchemas.AppEventDeliveryTargetSchema,
     WorkflowEventDeliveryTarget: EventSchemas.WorkflowEventDeliveryTargetSchema,
     EventDeliveryQueueFailureSummary: EventSchemas.EventDeliveryQueueFailureSummarySchema,
     EventOutboxQueueSummary: EventSchemas.EventOutboxQueueSummarySchema,
     EventDeliveryQueueSortField: EventSchemas.EventDeliveryQueueSortFieldSchema,
     AgentEventDeliveryTarget: EventSchemas.AgentEventDeliveryTargetSchema,
     WebhookEventDeliveryTargetInput: EventSchemas.WebhookEventDeliveryTargetInputSchema,
+    AppEventDeliveryTargetInput: EventSchemas.AppEventDeliveryTargetInputSchema,
     WorkflowEventDeliveryTargetInput: EventSchemas.WorkflowEventDeliveryTargetInputSchema,
     SemanticEvaluator: EventSchemas.SemanticEvaluatorSchema,
     SemanticEvaluationRecord: EventSchemas.SemanticEvaluationRecordSchema,
     EventDeliveryQueueSubscriptionSummary: EventSchemas.EventDeliveryQueueSubscriptionSummarySchema,
     EventDeliveryQueueSummaryPayload: EventSchemas.EventDeliveryQueueSummaryPayloadSchema,
+    CancelEventDeliveryIntentsPayload: EventSchemas.CancelEventDeliveryIntentsPayloadSchema,
+    CancelEventDeliveryIntentsResponse: EventSchemas.CancelEventDeliveryIntentsResponseSchema,
     EventSemanticCondition: EventSchemas.EventSemanticConditionSchema,
     EventDeliveryIntentSummary: EventSchemas.EventDeliveryIntentSummarySchema,
     EventDeliveryQueueSummaryResponse: EventSchemas.EventDeliveryQueueSummaryResponseSchema,
@@ -1071,6 +1075,10 @@ const REMOTE_MCP_SCHEMAS = {
     McpOAuthConnectResponse: McpOAuthConnectResponseSchema,
     OAuthAuthorizeResponse: OAuthAuthorizeResponseSchema,
     OAuthAuthStatusArray: OAuthAuthStatusArraySchema,
+    // The static-key alternative to that handshake: the key itself is write-only, so only the
+    // setter payload and the configured/hint projection are published.
+    SetMcpApiKeyRequest: SetMcpApiKeyRequestSchema,
+    McpApiKeyStatus: McpApiKeyStatusSchema,
 };
 const AUDIT_TRAIL_SCHEMAS = {
     // The audit trail: the events the endpoint pages through and the aggregation it
@@ -1181,6 +1189,7 @@ const APP_LIFECYCLE_SCHEMAS = {
     RunType: RunTypeSchema,
     AppBuildProgressStatus: AppBuildProgressStatusSchema,
     DeleteAppVersionResponse: DeleteAppVersionResponseSchema,
+    AppDeleteSummary: AppDeleteSummarySchema,
     AppRepoBranch: AppRepoBranchSchema,
     AppRepoDocumentCommit: AppRepoDocumentCommitSchema,
     AppVersionGitSource: AppVersionGitSourceSchema,
@@ -1190,6 +1199,8 @@ const APP_LIFECYCLE_SCHEMAS = {
     AppDevelopmentTaskList: AppDevelopmentTaskListSchema,
     OAuthClientCredentialsMap: OAuthClientCredentialsMapSchema,
     AppOAuthCollectionParams: AppOAuthCollectionParamsSchema,
+    McpApiKeyCredential: McpApiKeyCredentialSchema,
+    AppApiKeyCollectionParams: AppApiKeyCollectionParamsSchema,
     AppInspectionIssue: AppInspectionIssueSchema,
     AppScaffoldProgress: AppScaffoldProgressSchema,
     AppRepoTree: AppRepoTreeSchema,
@@ -1333,6 +1344,7 @@ const STS_SCHEMAS = {
     ServiceAccountTokenRequest: StsSchemas.ServiceAccountTokenRequestSchema,
     IssueTokenRequest: StsSchemas.IssueTokenRequestSchema,
     IssueTokenResponse: StsSchemas.IssueTokenResponseSchema,
+    IssueTokenForbiddenResponse: StsSchemas.IssueTokenForbiddenResponseSchema,
     IssueTokenUnavailableResponse: StsSchemas.IssueTokenUnavailableResponseSchema,
 };
 const API_SCHEMA_GROUPS = [
@@ -1413,6 +1425,7 @@ const STRICT_COMPONENTS = new Set([
     'AgentTokenRequest',
     'ServiceAccountTokenRequest',
     'IssueTokenResponse',
+    'IssueTokenForbiddenResponse',
     'IssueTokenUnavailableResponse',
     'ApiKeyListQuery',
     // These payloads previously referenced closed generated utility components. They now own their
@@ -1560,6 +1573,7 @@ const STRICT_COMPONENTS = new Set([
     'AppUIConfig',
     'AppUINavItem',
     'MCPOAuthConfig',
+    'MCPApiKeyConfig',
     'MCPToolCollectionObject',
     'VertesiaSDKToolCollectionObject',
     // File, task, content-type and command components. Every one is published closed
@@ -1851,6 +1865,8 @@ const STRICT_COMPONENTS = new Set([
     'ListWorkflowRunsResponse',
     'EventDeliveryQueueSubscriptionSummary',
     'EventDeliveryQueueSummaryPayload',
+    'CancelEventDeliveryIntentsPayload',
+    'CancelEventDeliveryIntentsResponse',
     'ContentObjectExportStatusResponse',
     'TimerTask',
     'SignalTask',
@@ -2118,6 +2134,8 @@ const STRICT_COMPONENTS = new Set([
     'McpOAuthDisconnectResponse',
     'McpOAuthConnectResponse',
     'OAuthAuthorizeResponse',
+    'SetMcpApiKeyRequest',
+    'McpApiKeyStatus',
     'AuditMeter',
     'AuditAggregationDimensionMap',
     'AuditAggregationRow',
@@ -2171,6 +2189,7 @@ const STRICT_COMPONENTS = new Set([
     'AppInstallationProviderBinding',
     'AppInstallationOAuthBinding',
     'OAuthClientCredentials',
+    'McpApiKeyCredential',
     'AppInspectionCapabilityReport',
     'AppRepoTreeEntry',
     'AppRepoRef',
@@ -2179,6 +2198,7 @@ const STRICT_COMPONENTS = new Set([
     'InCodeTypeRef',
     'StoredTypeRef',
     'DeleteAppVersionResponse',
+    'AppDeleteSummary',
     'AppRepoBranch',
     'AppRepoDocumentCommit',
     'AppVersionGitSource',
@@ -2452,15 +2472,96 @@ const validators = new Map();
  * it reuse the compiled form of a component that two others reference.
  */
 let ajvInstance;
+/**
+ * The published components as AJV can consume them: the same schemas, with the two adjustments
+ * AJV's discriminator support requires and the OpenAPI document must not have.
+ *
+ * `discriminator: true` below is what makes AJV validate a discriminated union through the branch
+ * its tag names, instead of trying every branch and reporting all of their failures at once. The
+ * difference is not cosmetic — a legacy MCP tool collection missing `id` used to report the real
+ * error alongside two impossible ones from the branch it was never meant to match:
+ *
+ *     / must have required property 'id'                        <- the real one
+ *     / must NOT have additional properties: oauth_app          <- vertesia_sdk branch
+ *     /type must be equal to constant                           <- vertesia_sdk branch
+ *     / must match exactly one schema in oneOf
+ *
+ * AJV rejects `mapping` outright ("discriminator: mapping is not supported"), because it derives
+ * the tag-to-branch map from each branch's own `const`/`enum` instead. The OpenAPI document still
+ * needs the mapping — a generated Java or Go client reads it to pick a concrete subtype — so both
+ * fixups here apply to AJV's copy only, and `ApiSchemaComponents` is published exactly as built.
+ *
+ * AJV's remaining requirements — the tag required in every branch, carrying `const` or a
+ * single-valued `enum`, with the union node typed as an object — are what `synthesizeDiscriminator`
+ * in the adapter already checks before it emits a discriminator at all, and what the hand-written
+ * `.meta({ discriminator })` declarations restate. `api-discriminators.test.ts` compiles every
+ * registered component so a union satisfying neither fails the build rather than the request.
+ */
+function toAjvComponents() {
+    const schemas = structuredClone(ApiSchemaComponents);
+    const resolve = (value) => {
+        if (!isPlainObject(value))
+            return undefined;
+        const ref = value.$ref;
+        if (typeof ref !== 'string' || !ref.startsWith(COMPONENT_REF_PREFIX))
+            return value;
+        return schemas[ref.slice(COMPONENT_REF_PREFIX.length)];
+    };
+    visitSchemaNodes(schemas, (node) => {
+        const discriminator = node.discriminator;
+        if (!isPlainObject(discriminator) || !Array.isArray(node.oneOf))
+            return;
+        // AJV derives the tag-to-branch map from each branch's own literal, so `mapping` is both
+        // redundant and rejected.
+        delete discriminator.mapping;
+        const tag = discriminator.propertyName;
+        if (typeof tag !== 'string')
+            return;
+        for (const member of node.oneOf) {
+            const branch = resolve(member);
+            const properties = branch && isPlainObject(branch.properties) ? branch.properties : undefined;
+            const tagSchema = properties?.[tag];
+            if (!isPlainObject(tagSchema) || tagSchema.const !== undefined || tagSchema.enum !== undefined)
+                continue;
+            // The tag is a `$ref` to a named literal component — `TaskType_ACTIVITY`,
+            // `SupportedIntegrations_gladia` — because the literal carries its own `.meta({ id })`.
+            // AJV reads `properties/<tag>` looking for `const` or `enum` and does not follow a
+            // `$ref` to find one, so it refuses to compile the union at all. Restating the resolved
+            // literal ALONGSIDE the `$ref` is validation-neutral: `$ref` has no special precedence
+            // in 2020-12, both keywords apply, and they carry the same value by construction.
+            const target = resolve(tagSchema);
+            if (!target)
+                continue;
+            if (target.const !== undefined)
+                tagSchema.const = target.const;
+            else if (Array.isArray(target.enum))
+                tagSchema.enum = target.enum;
+        }
+    });
+    return schemas;
+}
+/** Every object node in the component graph, parents before children. */
+function visitSchemaNodes(value, visit) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            visitSchemaNodes(item, visit);
+        return;
+    }
+    if (!isPlainObject(value))
+        return;
+    visit(value);
+    for (const item of Object.values(value))
+        visitSchemaNodes(item, visit);
+}
 function getAjv() {
     if (ajvInstance)
         return ajvInstance;
-    const ajv = new Ajv2020({ strictSchema: false, allErrors: true });
+    const ajv = new Ajv2020({ strictSchema: false, allErrors: true, discriminator: true });
     // Without this, AJV treats `format` as an annotation and ignores it, so a `date-time` property
     // would document a constraint nothing checks — the exact spec/enforcement gap this design is
     // meant to close.
     addFormats(ajv);
-    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: ApiSchemaComponents } });
+    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: toAjvComponents() } });
     ajvInstance = ajv;
     return ajv;
 }
@@ -2472,17 +2573,68 @@ function getValidator(name) {
     validators.set(name, validate);
     return validate;
 }
-function formatErrors(validate) {
-    return (validate.errors ?? []).map((error) => {
+function additionalProperty(error) {
+    // AJV writes "must NOT have additional properties" and puts the offending key in `params`,
+    // so the message alone says a body is wrong without saying which property made it wrong.
+    // Every other keyword names its subject already — `required` quotes the missing property,
+    // `enum` and `type` describe the value in place — and this is the one a caller most often
+    // trips, so it is the one worth spelling out rather than reformatting all of them.
+    return error.params?.additionalProperty;
+}
+/**
+ * The failures, with all undeclared properties at a given path gathered into ONE issue.
+ *
+ * AJV reports `additionalProperties` per property, so a value carrying a whole foreign object —
+ * a Mongoose document that reached the response mapper unmapped, say — produces one error per own
+ * key and buries every other failure in the payload. Gathering is lossless: every name is kept, in
+ * the order AJV found it, on the issue for the path it belongs to.
+ */
+function collectIssues(validate) {
+    const errors = validate.errors ?? [];
+    const undeclaredByPath = new Map();
+    for (const error of errors) {
+        const additional = additionalProperty(error);
+        if (additional === undefined)
+            continue;
         const where = error.instancePath || '/';
-        // AJV writes "must NOT have additional properties" and puts the offending key in `params`,
-        // so the message alone says a body is wrong without saying which property made it wrong.
-        // Every other keyword names its subject already — `required` quotes the missing property,
-        // `enum` and `type` describe the value in place — and this is the one a caller most often
-        // trips, so it is the one worth spelling out rather than reformatting all of them.
-        const additional = error.params?.additionalProperty;
-        return additional ? `${where} ${error.message}: ${additional}` : `${where} ${error.message}`;
-    });
+        const names = undeclaredByPath.get(where);
+        // A union whose branches all reject the same property reports it once per branch. The name
+        // is the same fact each time, so it is listed once.
+        if (names)
+            names.add(additional);
+        else
+            undeclaredByPath.set(where, new Set([additional]));
+    }
+    const gathered = new Set();
+    const issues = [];
+    for (const error of errors) {
+        const path = error.instancePath || '/';
+        const message = error.message ?? 'is invalid';
+        if (additionalProperty(error) === undefined) {
+            issues.push({ path, message });
+            continue;
+        }
+        if (gathered.has(path))
+            continue;
+        gathered.add(path);
+        issues.push({ path, message, undeclared: [...(undeclaredByPath.get(path) ?? [])] });
+    }
+    return issues;
+}
+/**
+ * The complete rendering of one issue — every name, no budget.
+ *
+ * This is what gets logged. A caller-facing message renders from {@link ApiValidationIssue} itself
+ * with a length limit rather than shortening this string; see `reportableErrors` in the enforcer.
+ */
+export function renderApiValidationIssue(issue) {
+    const head = `${issue.path} ${issue.message}`;
+    return issue.undeclared?.length ? `${head}: ${issue.undeclared.join(', ')}` : head;
+}
+/** The failed branch of every validator here, so the two views cannot be built inconsistently. */
+function invalidResult(validate) {
+    const issues = collectIssues(validate);
+    return { valid: false, errors: issues.map(renderApiValidationIssue), issues };
 }
 /**
  * Validates an untyped request body against the component the endpoint publishes.
@@ -2501,7 +2653,7 @@ export function validateApiRequest(name, value) {
     if (validate(value)) {
         return { valid: true, data: value };
     }
-    return { valid: false, errors: formatErrors(validate) };
+    return invalidResult(validate);
 }
 /**
  * Validates an already-mapped response against the component it is published as.
@@ -2515,7 +2667,7 @@ export function validateApiResponse(name, value) {
     if (validate(value)) {
         return { valid: true, data: value };
     }
-    return { valid: false, errors: formatErrors(validate) };
+    return invalidResult(validate);
 }
 /**
  * Best-effort normalization of a response payload towards the fields its published component
@@ -2557,7 +2709,7 @@ export function pruneAndValidateApiResponse(name, value) {
     if (validate(pruned)) {
         return { valid: true, data: pruned };
     }
-    return { valid: false, data: pruned, errors: formatErrors(validate) };
+    return { ...invalidResult(validate), data: pruned };
 }
 /**
  * Paths inside a component where pruning cannot narrow. Empty means no STRUCTURAL gaps for