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

package/src/ask-user.ts

@@ -55,7 +55,15 @@ export interface AskUserUxConfig {
 }
 
 /** Message details structure for REQUEST_INPUT messages with UX config */
-export interface AskUserMessageDetails {
+export interface AskUserMessageDetails extends Record<string, unknown> {
+    /** Stable identifier used to correlate this prompt with the user's persisted response. */
+    request_id?: string;
     /** UX configuration for rendering the ask_user widget */
     ux?: AskUserUxConfig;
 }
+
+/** Metadata carried by a user response to a structured REQUEST_INPUT message. */
+export interface RequestInputResponseMetadata {
+    /** Stable identifier copied from the REQUEST_INPUT message. */
+    request_id: string;
+}

package/src/audit-trail.ts

@@ -1,4 +1,21 @@
-import type { EventCategory } from './platform-event.js';
+import type { z } from 'zod';
+import type {
+    AuditAggregationDetailFieldSchema,
+    AuditAggregationDetailFilterSchema,
+    AuditAggregationDistinctFieldSchema,
+    AuditAggregationFilterSchema,
+    AuditAggregationGroupSchema,
+    AuditAggregationMetricSchema,
+    AuditAggregationOperationSchema,
+    AuditAggregationQuerySchema,
+    AuditAggregationResolutionSchema,
+    AuditAggregationResponseSchema,
+    AuditAggregationRowSchema,
+    AuditMeterSchema,
+    AuditTrailEventSchema,
+    AuditTrailQuerySchema,
+    AuditTrailResponseSchema,
+} from './api-schemas/audit-trail.js';
 
 export const AUDIT_ACTIONS = [
     // CRUD operations
@@ -23,6 +40,9 @@ export const AUDIT_ACTIONS = [
     'document_processed',
 ] as const;
 
+// `AuditAction` is deliberately NOT inferred from `AuditActionSchema`: the schema is
+// `KnownAuditAction | string`, which TypeScript collapses to `string`, losing the completion the
+// `(string & {})` half of the union exists to preserve. The two agree on what they accept.
 export type KnownAuditAction = (typeof AUDIT_ACTIONS)[number];
 export type AuditAction = KnownAuditAction | (string & {});
 
@@ -39,82 +59,13 @@ export const BILLABLE_AUDIT_ACTIONS = ['inference', 'embedding', 'image_generati
  *   { category: "compute", type: "duration_ms", quantity: 2100 }
  *   { category: "processing", type: "pages", quantity: 12 }
  */
-export interface AuditMeter {
-    category: string;
-    type: string;
-    quantity: number;
-}
-
-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;
-    timestamp: string;
-    request_id: string;
-    status: number;
-    success: boolean;
-    principal_id: string | null;
-    principal_type: string | null;
-    effective_principal_id: string | null;
-    roles: string[];
-    account_id: string | null;
-    project_id: string | null;
-    tenant_id: string | null;
-    account_name: string | null;
-    project_name: string | null;
-    /** Provider type for billable/provider-backed events, e.g. vertexai, bedrock. */
-    provider?: string | null;
-    /** Generic metering data for cost attribution and usage tracking */
-    meters?: AuditMeter[];
-    /** Event-specific metadata — shape varies by action/resource_type */
-    details?: Record<string, unknown>;
-}
-
-export interface AuditTrailQuery {
-    /** Filter by action types */
-    actions?: AuditAction[];
-    /** Filter by resource types */
-    resourceTypes?: string[];
-    /** Filter by resource ID */
-    resourceId?: string;
-    /** Filter by exact actor principal ref (matches principal_id column). */
-    principalId?: string;
-    /** Filter by top-level actor category (matches principal_type column). */
-    principalType?: string;
-    /** Filter by delegated/direct effective principal ref (matches effective_principal_id column). */
-    effectivePrincipalId?: string;
-    /** Filter by whether an event has an effective principal ref. */
-    hasEffectivePrincipal?: boolean;
-    /** Filter by project ID */
-    projectId?: string;
-    /** Start time (ISO string) */
-    from?: string;
-    /** End time (ISO string) */
-    to?: string;
-    /** Pagination: number of items to return (default 50, max 200) */
-    limit?: number;
-    /** Pagination: offset */
-    offset?: number;
-}
-
-export interface AuditTrailResponse {
-    events: AuditTrailEvent[];
-    /** Whether there are more events after this page */
-    hasNext: boolean;
-    limit: number;
-    offset: number;
-}
+export type AuditMeter = z.infer<typeof AuditMeterSchema>;
+
+export type AuditTrailEvent = z.infer<typeof AuditTrailEventSchema>;
+
+export type AuditTrailQuery = z.infer<typeof AuditTrailQuerySchema>;
+
+export type AuditTrailResponse = z.infer<typeof AuditTrailResponseSchema>;
 
 export const AUDIT_AGGREGATION_DIMENSIONS = [
     'time',
@@ -131,68 +82,25 @@ export const AUDIT_AGGREGATION_DIMENSIONS = [
 ] as const;
 
 export type AuditAggregationDimension = (typeof AUDIT_AGGREGATION_DIMENSIONS)[number];
-export type AuditAggregationResolution = 'hour' | 'day' | 'week' | 'month';
-export type AuditAggregationDetailField = 'pipeline' | 'verdict' | 'workflow_type' | 'rule_id';
-export type AuditAggregationOperation = 'count' | 'count_distinct' | 'sum_meter' | 'average_meter';
-export type AuditAggregationDistinctField = 'resource_id' | 'request_id';
-
-export interface AuditAggregationGroup {
-    dimension: AuditAggregationDimension;
-    /** Required for the time dimension; defaults to day. */
-    resolution?: AuditAggregationResolution;
-}
-
-export interface AuditAggregationMetric {
-    /** Stable key used in response rows. Must contain only letters, numbers, underscores, or hyphens. */
-    id: string;
-    operation: AuditAggregationOperation;
-    /** Required for count_distinct. */
-    field?: AuditAggregationDistinctField;
-    /** Required for meter operations. */
-    meterCategory?: string;
-    /** Required for meter operations. */
-    meterType?: string;
-}
-
-export interface AuditAggregationDetailFilter {
-    field: AuditAggregationDetailField;
-    values: string[];
-}
-
-export interface AuditAggregationFilter {
-    actions?: AuditAction[];
-    resourceTypes?: string[];
-    eventCategories?: EventCategory[];
-    providers?: string[];
-    success?: boolean;
-    details?: AuditAggregationDetailFilter[];
-}
+export type AuditAggregationResolution = z.infer<typeof AuditAggregationResolutionSchema>;
+export type AuditAggregationDetailField = z.infer<typeof AuditAggregationDetailFieldSchema>;
+export type AuditAggregationOperation = z.infer<typeof AuditAggregationOperationSchema>;
+export type AuditAggregationDistinctField = z.infer<typeof AuditAggregationDistinctFieldSchema>;
+
+export type AuditAggregationGroup = z.infer<typeof AuditAggregationGroupSchema>;
+
+export type AuditAggregationMetric = z.infer<typeof AuditAggregationMetricSchema>;
+
+export type AuditAggregationDetailFilter = z.infer<typeof AuditAggregationDetailFilterSchema>;
+
+export type AuditAggregationFilter = z.infer<typeof AuditAggregationFilterSchema>;
 
 /**
  * Safe audit aggregation query. The server always applies the authenticated account scope and,
  * for project-scoped principals, replaces projectId with the authenticated project.
  */
-export interface AuditAggregationQuery {
-    /** Optional account-admin project filter. Ignored for project-scoped principals. */
-    projectId?: string;
-    /** Start time; defaults to 30 days before to. The server caps the range at 366 days. */
-    from?: string;
-    /** End time; defaults to the current time. */
-    to?: string;
-    filter?: AuditAggregationFilter;
-    groupBy?: AuditAggregationGroup[];
-    metrics: AuditAggregationMetric[];
-    /** Maximum groups returned (default 50, max 200). */
-    limit?: number;
-}
-
-export interface AuditAggregationRow {
-    dimensions: Partial<Record<AuditAggregationDimension, string | null>>;
-    metrics: Record<string, number>;
-}
-
-export interface AuditAggregationResponse {
-    rows: AuditAggregationRow[];
-    from: string;
-    to: string;
-}
+export type AuditAggregationQuery = z.infer<typeof AuditAggregationQuerySchema>;
+
+export type AuditAggregationRow = z.infer<typeof AuditAggregationRowSchema>;
+
+export type AuditAggregationResponse = z.infer<typeof AuditAggregationResponseSchema>;

package/src/browser-credentials.ts

@@ -1,96 +1,28 @@
-export type WebsiteCredentialCapability = 'password' | 'totp' | 'oauth';
+import type { z } from 'zod';
+import type {
+    WebsiteCredentialCapabilitySchema,
+    WebsiteCredentialFillRequestSchema,
+    WebsiteCredentialFillResponseSchema,
+    WebsiteCredentialMetadataSchema,
+    WebsiteCredentialRecordSchema,
+    WebsiteCredentialSecretInputSchema,
+    WebsiteCredentialTotpAlgorithmSchema,
+    WebsiteCredentialTotpMetadataSchema,
+    WebsiteCredentialWebsiteSchema,
+} from './api-schemas/secrets.js';
+export type WebsiteCredentialCapability = z.infer<typeof WebsiteCredentialCapabilitySchema>;
 
-export type WebsiteCredentialTotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512';
+export type WebsiteCredentialTotpAlgorithm = z.infer<typeof WebsiteCredentialTotpAlgorithmSchema>;
 
-export interface WebsiteCredentialWebsite {
-    /**
-     * Hostname this credential is allowed on. Subdomains match.
-     */
-    host: string;
-    /**
-     * Optional login URL used by agents as a hint.
-     */
-    login_url?: string;
-    /**
-     * Optional narrower origin allowlist for this credential.
-     */
-    allowed_origins?: string[];
-}
+export type WebsiteCredentialWebsite = z.infer<typeof WebsiteCredentialWebsiteSchema>;
 
-export interface WebsiteCredentialTotpMetadata {
-    algorithm?: WebsiteCredentialTotpAlgorithm;
-    digits?: 6 | 8;
-    period?: number;
-    issuer?: string;
-    account?: string;
-}
+export type WebsiteCredentialTotpMetadata = z.infer<typeof WebsiteCredentialTotpMetadataSchema>;
 
-export interface WebsiteCredentialMetadata {
-    name: string;
-    websites: WebsiteCredentialWebsite[];
-    username?: string;
-    username_hint?: string;
-    username_secret?: boolean;
-    properties?: Record<string, unknown>;
-    tags?: string[];
-    enabled?: boolean;
-    capabilities?: WebsiteCredentialCapability[];
-    notes?: string;
-    totp?: WebsiteCredentialTotpMetadata;
-    /**
-     * Optional ISO timestamp after which the credential is no longer usable.
-     * Expired credentials are hidden from lookup and cannot be filled.
-     */
-    expires_at?: string;
-}
+export type WebsiteCredentialMetadata = z.infer<typeof WebsiteCredentialMetadataSchema>;
 
-export interface WebsiteCredentialRecord {
-    id: string;
-    credential_ref: string;
-    project: string;
-    name: string;
-    websites: WebsiteCredentialWebsite[];
-    username?: string;
-    username_hint?: string;
-    username_secret_enabled: boolean;
-    properties?: Record<string, unknown>;
-    tags?: string[];
-    enabled?: boolean;
-    capabilities?: WebsiteCredentialCapability[];
-    notes?: string;
-    totp_metadata?: WebsiteCredentialTotpMetadata;
-    /**
-     * Optional ISO timestamp after which the credential is no longer usable.
-     * Expired credentials are hidden from lookup and cannot be filled.
-     */
-    expires_at?: string;
-    created_at?: string;
-    updated_at?: string;
-    has_username_secret: boolean;
-    has_password: boolean;
-    has_totp: boolean;
-    has_oauth: boolean;
-    password_hint?: string;
-}
+export type WebsiteCredentialRecord = z.infer<typeof WebsiteCredentialRecordSchema>;
 
-export interface WebsiteCredentialSecretInput {
-    /**
-     * Optional encrypted username. Prefer metadata.username unless the username itself is sensitive.
-     */
-    username?: string;
-    password?: string;
-    totp?: WebsiteCredentialTotpMetadata & {
-        seed: string;
-    };
-    /**
-     * Future OAuth materialization hook. The token itself remains in the OAuth secret store.
-     */
-    oauth?: {
-        provider_id?: string;
-        token_owner?: 'user' | 'project';
-        token_ref?: string;
-    };
-}
+export type WebsiteCredentialSecretInput = z.infer<typeof WebsiteCredentialSecretInputSchema>;
 
 export interface CreateWebsiteCredentialRequest extends WebsiteCredentialMetadata {
     secret?: WebsiteCredentialSecretInput;
@@ -111,23 +43,6 @@ export interface WebsiteCredentialFillTarget {
     submit_target_id?: string;
 }
 
-export interface WebsiteCredentialFillRequest extends WebsiteCredentialFillTarget {
-    /**
-     * Browser-use parent workflow id. The API resolves the Daytona sandbox and
-     * observes the current page server-side before decrypting the credential.
-     */
-    browser_workflow_id: string;
-}
+export type WebsiteCredentialFillRequest = z.infer<typeof WebsiteCredentialFillRequestSchema>;
 
-export interface WebsiteCredentialFillResponse {
-    ok: boolean;
-    credential_ref: string;
-    url: string;
-    title: string;
-    filled: {
-        username: boolean;
-        password: boolean;
-        totp: boolean;
-        submitted: boolean;
-    };
-}
+export type WebsiteCredentialFillResponse = z.infer<typeof WebsiteCredentialFillResponseSchema>;

package/src/common.ts

@@ -1,94 +1,83 @@
-export interface FindPayload {
-    query: Record<string, unknown>;
-    offset?: number;
-    limit?: number;
-    select?: string;
-    all_revisions?: boolean;
-    from_root?: string;
-}
+import type { z } from 'zod';
+import type { DeleteOperationResultSchema } from './api-schemas/apikey.js';
+import type {
+    BulkObjectCreateResultSchema,
+    BulkObjectDeleteResultSchema,
+    BulkObjectUpdateResultSchema,
+    BulkOperationPayloadSchema,
+    BulkOperationResponseSchema,
+    BulkOperationResultSchema,
+} from './api-schemas/bulk-operation.js';
+import type { DeleteCountResultSchema, GenericCommandResponseSchema } from './api-schemas/commands.js';
+import type { FindPayloadSchema } from './api-schemas/content.js';
+import type { SuccessResponseSchema } from './api-schemas/oauth.js';
+import type { CountResultSchema } from './api-schemas/project.js';
+import type { DeleteByIdResultSchema } from './api-schemas/user.js';
+import type { ContentObjectProcessingPriority } from './store/store.js';
 
-export interface GenericCommandResponse {
-    status: string;
-    message: string;
-    err?: unknown;
-    details?: unknown;
-}
+export type FindPayload = z.infer<typeof FindPayloadSchema>;
 
-export interface DeleteByIdResult {
-    id: string;
-}
+export type GenericCommandResponse = z.infer<typeof GenericCommandResponseSchema>;
 
-export interface DeleteCountResult {
-    id: string;
-    count: number;
-}
+/**
+ * Derived from `DeleteByIdResultSchema`. Shared by eight studio delete endpoints; only `DeleteUser`
+ * publishes it canonically so far, and the generator fails the build if the canonical and derived
+ * definitions ever differ.
+ */
+export type DeleteByIdResult = z.infer<typeof DeleteByIdResultSchema>;
 
-export interface SuccessResponse {
-    success: true;
-}
+export type DeleteCountResult = z.infer<typeof DeleteCountResultSchema>;
 
-export interface DeleteOperationResult {
-    acknowledged: boolean;
-    deletedCount: number;
-}
+/**
+ * The success acknowledgement the OAuth provider and client endpoints return, inferred from
+ * `./api-schemas/oauth.js`.
+ *
+ * `success: boolean`, not `success: true`, which is what the document has always published — the
+ * scanner widened the literal on its way out. The handlers still only ever return `true`; the type
+ * now says what a client can be sent rather than what our five handlers happen to send.
+ */
+export type SuccessResponse = z.infer<typeof SuccessResponseSchema>;
 
-export interface CountResult {
-    count: number;
-}
+/**
+ * The raw Mongo delete acknowledgement, inferred from `./api-schemas/apikey.js`.
+ *
+ * One slot returns it (`DeleteApiKey`), so unlike {@link CountResult} it did not have to move as a
+ * group — it is here rather than in an apikey module because `./common.js` is where the shared
+ * result shapes live.
+ */
+export type DeleteOperationResult = z.infer<typeof DeleteOperationResultSchema>;
 
-export interface BulkOperationPayload {
-    /**
-     * The operation name
-     */
-    name: 'change_type' | 'create' | 'delete' | 'start_workflow' | 'update';
+/**
+ * How many rows an operation touched, inferred from `./api-schemas/project.js`.
+ *
+ * The module that owns it is named for the batch that converted it, not for the only resource that
+ * uses it: four slots across three resources and two services return this.
+ */
+export type CountResult = z.infer<typeof CountResultSchema>;
 
-    /**
-     * The IDs of the objects to operate on
-     */
-    ids: string[];
+export type BulkOperationPayload = z.infer<typeof BulkOperationPayloadSchema>;
 
-    /**
-     * The operation parameters.
-     */
-    params: Record<string, unknown>;
-}
+export type BulkOperationResult = z.infer<typeof BulkOperationResultSchema>;
 
-export interface BulkOperationResult<TOperation extends string = 'generic'> {
-    operation: TOperation;
-    status: 'in_progress' | 'completed' | 'failed';
-}
+export type BulkObjectDeleteResult = z.infer<typeof BulkObjectDeleteResultSchema>;
 
-export interface BulkObjectDeleteResult extends BulkOperationResult<'delete'> {
-    operation: 'delete';
-    /** Number of documents deleted (including revisions) */
-    deleted: number;
-    /** IDs that were not found or user had no permission to delete */
-    failed: string[];
-}
+export type BulkObjectUpdateResult = z.infer<typeof BulkObjectUpdateResultSchema>;
+
+export type BulkObjectCreateResult = z.infer<typeof BulkObjectCreateResultSchema>;
 
-export interface BulkObjectUpdateResult extends BulkOperationResult<'update'> {
-    operation: 'update';
-    /** Number of documents successfully updated */
-    updated: number;
-    /** IDs that were not found, not authorized, or failed to update */
-    failed: string[];
+export interface BulkObjectCreateOptions {
+    collection_id?: string;
+    /** @deprecated Events are now always emitted. This suppresses Temporal-backed delivery targets. */
+    skip_workflows?: boolean;
+    processing_priority?: ContentObjectProcessingPriority;
+    /** Stable identity for retrying an ambiguous bulk-create request without duplicating objects. */
+    idempotency_key?: string;
 }
 
-export interface BulkObjectCreateResult extends BulkOperationResult<'create'> {
-    operation: 'create';
-    /** Number of documents successfully created */
-    created: number;
-    /** Successfully created objects with their IDs */
-    objects: { id: string; external_id?: string }[];
-    /** Objects that failed to create */
-    failed: { external_id?: string; index: number; error: string }[];
+export interface BulkObjectUpdateOptions {
+    processing_priority?: ContentObjectProcessingPriority;
+    /** Stable identity for retrying an ambiguous bulk-update request without duplicating events. */
+    idempotency_key?: string;
 }
 
-/**
- * @discriminator operation
- */
-export type BulkOperationResponse =
-    | BulkOperationResult
-    | BulkObjectCreateResult
-    | BulkObjectUpdateResult
-    | BulkObjectDeleteResult;
+export type BulkOperationResponse = z.infer<typeof BulkOperationResponseSchema>;