@vertesia/common 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260806.125520Z

package/src/meters.ts

@@ -1,4 +1,5 @@
-import type { BillingMethod } from './user.js';
+import type { z } from 'zod';
+import type { StripeBillingStatusResponseSchema } from './api-schemas/account.js';
 
 export interface MeterAdjustment {
     meter: string;
@@ -19,9 +20,12 @@ export enum MeterNames {
     task_run = 'task_run',
 }
 
-export interface StripeBillingStatusResponse {
-    status: 'enabled' | 'disabled';
-    billing_method: BillingMethod | null;
-    portal_url?: string;
-    reason?: string;
-}
+/**
+ * Stripe billing status, derived from `StripeBillingStatusResponseSchema`.
+ *
+ * A real discriminated union rather than the flat object this used to be: the server sets
+ * `portal_url` only when enabled and `reason` only when disabled, and the flat shape gave every
+ * generated client two unrelated optionals with no way to tell which was populated. Narrowing on
+ * `status` now tells TypeScript which fields exist.
+ */
+export type StripeBillingStatusResponse = z.infer<typeof StripeBillingStatusResponseSchema>;

package/src/oauth-server.ts

@@ -1,13 +1,44 @@
+import type { z } from 'zod';
+import type {
+    BulkRevokeOAuthGrantsPayloadSchema,
+    CreateOAuthClientPayloadSchema,
+    ListOAuthGrantsQuerySchema,
+    OAuthClientCreateResponseSchema,
+    OAuthClientDataSchema,
+    OAuthClientSchema,
+    OAuthClientScopeMetadataSchema,
+    OAuthClientStatusSchema,
+    OAuthClientTypeSchema,
+    OAuthGrantListResponseSchema,
+    OAuthGrantRevokeResponseSchema,
+    OAuthGrantSchema,
+    OAuthGrantSortFieldSchema,
+    OAuthGrantSortOrderSchema,
+    OAuthGrantStatusSchema,
+    OAuthGrantTypeSchema,
+    OAuthProjectBindingModeSchema,
+    OAuthRegistrationSourceSchema,
+    OAuthResponseTypeSchema,
+    OAuthTokenEndpointAuthMethodSchema,
+    RevokeOAuthGrantQuerySchema,
+    UpdateOAuthClientPayloadSchema,
+} from './api-schemas/oauth-server.js';
 import type { AuthTokenPayload, PrincipalType } from './apikey.js';
 import type { ProjectRef } from './project.js';
 
-export type OAuthClientType = 'public' | 'confidential';
-export type OAuthClientStatus = 'active' | 'disabled';
-export type OAuthRegistrationSource = 'admin' | 'dynamic';
-export type OAuthProjectBindingMode = 'user_select' | 'fixed';
-export type OAuthTokenEndpointAuthMethod = 'none' | 'client_secret_post' | 'client_secret_basic';
-export type OAuthGrantType = 'authorization_code' | 'refresh_token' | 'urn:ietf:params:oauth:grant-type:device_code';
-export type OAuthResponseType = 'code';
+/**
+ * The types the three studio OAuth resources publish are inferred from
+ * `./api-schemas/oauth-server.js` — the same objects the OpenAPI document and the request validator
+ * are built from. The rest of this module is the token server's own OAuth surface, still declared
+ * here and still TypeScript-derived; it converts with that service's own slots.
+ */
+export type OAuthClientType = z.infer<typeof OAuthClientTypeSchema>;
+export type OAuthClientStatus = z.infer<typeof OAuthClientStatusSchema>;
+export type OAuthRegistrationSource = z.infer<typeof OAuthRegistrationSourceSchema>;
+export type OAuthProjectBindingMode = z.infer<typeof OAuthProjectBindingModeSchema>;
+export type OAuthTokenEndpointAuthMethod = z.infer<typeof OAuthTokenEndpointAuthMethodSchema>;
+export type OAuthGrantType = z.infer<typeof OAuthGrantTypeSchema>;
+export type OAuthResponseType = z.infer<typeof OAuthResponseTypeSchema>;
 export type OAuthAuthorizationRequestStatus = 'pending' | 'denied' | 'consumed';
 export type OAuthClientRegistrationMode = 'registered' | 'client_id_metadata_document';
 /**
@@ -16,136 +47,36 @@ export type OAuthClientRegistrationMode = 'registered' | 'client_id_metadata_doc
  * describes how inbound clients identified themselves to Vertesia's own AS.
  */
 export type RemoteOAuthRegistrationMode = 'dynamic_client_registration' | 'client_id_metadata_document';
-export type OAuthGrantStatus = 'active' | 'revoked' | 'expired';
-export type OAuthGrantSortField =
-    | 'granted_at'
-    | 'client_name'
-    | 'user_name'
-    | 'resource'
-    | 'last_used_at'
-    | 'expires_at'
-    | 'status';
-export type OAuthGrantSortOrder = 'asc' | 'desc';
-
-export interface OAuthClientData {
-    client_name: string;
-    client_type: OAuthClientType;
-    redirect_uris: string[];
-    grant_types: OAuthGrantType[];
-    response_types: OAuthResponseType[];
-    token_endpoint_auth_method: OAuthTokenEndpointAuthMethod;
-    allowed_scopes: string[];
-    default_scopes?: string[];
-    registration_source: OAuthRegistrationSource;
-    status: OAuthClientStatus;
-    project_binding_mode: OAuthProjectBindingMode;
-    fixed_project_id?: string;
-    /**
-     * When true (the default for new clients), the client may only be authorized for projects in its
-     * owning account/organization. Set to false to allow authorization for any project the approving
-     * user can access, regardless of account — required for OAuth/MCP clients used across
-     * organizations. The owning account itself is internal and not exposed here.
-     */
-    restrict_to_owner_account?: boolean;
-    metadata?: Record<string, unknown>;
-    created_by?: string;
-    client_secret_configured?: boolean;
-    created_at: string;
-    updated_at: string;
-}
+export type OAuthGrantStatus = z.infer<typeof OAuthGrantStatusSchema>;
+export type OAuthGrantSortField = z.infer<typeof OAuthGrantSortFieldSchema>;
+export type OAuthGrantSortOrder = z.infer<typeof OAuthGrantSortOrderSchema>;
 
-export interface OAuthClient extends OAuthClientData {
-    client_id: string;
-}
+/** An OAuth client's registration, without the id the server issues for it. */
+export type OAuthClientData = z.infer<typeof OAuthClientDataSchema>;
 
-export interface OAuthClientCreateResponse extends OAuthClient {
-    client_secret?: string;
-}
+export type OAuthClient = z.infer<typeof OAuthClientSchema>;
 
-export interface OAuthClientScopeMetadata {
-    supported_scopes: string[];
-}
+/** The read shape plus the client secret, which is returned by the create call and never again. */
+export type OAuthClientCreateResponse = z.infer<typeof OAuthClientCreateResponseSchema>;
 
-export interface OAuthGrant {
-    grant_id: string;
-    client_id: string;
-    client_name: string;
-    user_id: string;
-    user_name?: string;
-    user_email?: string;
-    account_id: string;
-    project_id: string;
-    resource: string;
-    scope: string[];
-    status: OAuthGrantStatus;
-    token_count: number;
-    granted_at: string;
-    created_at: string;
-    last_used_at?: string;
-    expires_at?: string;
-}
+export type OAuthClientScopeMetadata = z.infer<typeof OAuthClientScopeMetadataSchema>;
 
-export interface ListOAuthGrantsQuery {
-    account_id?: string;
-    project_id?: string;
-    user_id?: string;
-    client_id?: string;
-    resource?: string;
-    status?: OAuthGrantStatus | 'all';
-    limit?: number;
-    offset?: number;
-    sort_by?: OAuthGrantSortField;
-    sort_order?: OAuthGrantSortOrder;
-}
+export type OAuthGrant = z.infer<typeof OAuthGrantSchema>;
 
-export interface OAuthGrantListResponse {
-    grants: OAuthGrant[];
-    total_count: number;
-    limit: number;
-    offset: number;
-}
+export type ListOAuthGrantsQuery = z.infer<typeof ListOAuthGrantsQuerySchema>;
 
-export interface BulkRevokeOAuthGrantsPayload extends ListOAuthGrantsQuery {
-    grant_ids?: string[];
-    include_consent?: boolean;
-}
+/** Whether revoking a grant also withdraws the stored consent behind it. */
+export type RevokeOAuthGrantQuery = z.infer<typeof RevokeOAuthGrantQuerySchema>;
 
-export interface OAuthGrantRevokeResponse {
-    revoked_tokens: number;
-    revoked_consents: number;
-}
+export type OAuthGrantListResponse = z.infer<typeof OAuthGrantListResponseSchema>;
 
-export interface CreateOAuthClientPayload {
-    client_name: string;
-    client_type?: OAuthClientType;
-    redirect_uris: string[];
-    grant_types?: OAuthGrantType[];
-    response_types?: OAuthResponseType[];
-    token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
-    allowed_scopes?: string[];
-    default_scopes?: string[];
-    project_binding_mode?: OAuthProjectBindingMode;
-    fixed_project_id?: string;
-    restrict_to_owner_account?: boolean;
-    client_secret?: string;
-    metadata?: Record<string, unknown>;
-}
+export type BulkRevokeOAuthGrantsPayload = z.infer<typeof BulkRevokeOAuthGrantsPayloadSchema>;
 
-export interface UpdateOAuthClientPayload {
-    client_name?: string;
-    redirect_uris?: string[];
-    grant_types?: OAuthGrantType[];
-    response_types?: OAuthResponseType[];
-    token_endpoint_auth_method?: OAuthTokenEndpointAuthMethod;
-    allowed_scopes?: string[];
-    default_scopes?: string[];
-    status?: OAuthClientStatus;
-    project_binding_mode?: OAuthProjectBindingMode;
-    fixed_project_id?: string;
-    restrict_to_owner_account?: boolean;
-    client_secret?: string;
-    metadata?: Record<string, unknown>;
-}
+export type OAuthGrantRevokeResponse = z.infer<typeof OAuthGrantRevokeResponseSchema>;
+
+export type CreateOAuthClientPayload = z.infer<typeof CreateOAuthClientPayloadSchema>;
+
+export type UpdateOAuthClientPayload = z.infer<typeof UpdateOAuthClientPayloadSchema>;
 
 export interface OAuthAuthorizationServerMetadata {
     issuer: string;

package/src/oauth.ts

@@ -1,144 +1,60 @@
+import type { z } from 'zod';
+import type {
+    CreateOAuthProviderPayloadSchema,
+    OAuthProviderAccessTokenResponseSchema,
+    OAuthProviderAuthorizeResponseSchema,
+    OAuthProviderAuthStatusSchema,
+    OAuthProviderDataSchema,
+    OAuthProviderExchangePayloadSchema,
+    OAuthProviderSchema,
+    UpdateOAuthProviderPayloadSchema,
+} from './api-schemas/oauth.js';
+
 /**
  * OAuth Provider types for generic, project-level OAuth 2.0 integration.
  * Decoupled from MCP — can be used by MCP collections, tool activities, or any OAuth-protected API.
+ *
+ * Every type below is inferred from `./api-schemas/oauth.js`, which is the object the OpenAPI
+ * document and the request validator are both built from. `import type` throughout, so nothing here
+ * pulls zod into a bundle that only wanted the types.
  */
 
 /**
  * OAuth Provider data stored in MongoDB.
  * Represents the configuration for an OAuth 2.0 provider at the project level.
  */
-export interface OAuthProviderData {
-    /**
-     * Unique name within the project (kebab-case identifier).
-     */
-    name: string;
-
-    /**
-     * Human-readable display name.
-     */
-    display_name: string;
-
-    /**
-     * The project this OAuth provider belongs to.
-     */
-    project: string;
-
-    /**
-     * The OAuth 2.0 grant type to use.
-     * - 'authorization_code': 3-legged flow requiring user authorization (default).
-     * - 'client_credentials': 2-legged server-to-server flow using client_id + client_secret.
-     */
-    grant_type?: 'authorization_code' | 'client_credentials';
-
-    /**
-     * The OAuth 2.0 authorization endpoint URL.
-     * Only used for authorization_code flow.
-     * Optional when endpoints are discovered via .well-known (e.g. MCP servers).
-     */
-    authorization_endpoint?: string;
-
-    /**
-     * The OAuth 2.0 token endpoint URL.
-     * Optional when endpoints are discovered via .well-known (e.g. MCP servers).
-     */
-    token_endpoint?: string;
-
-    /**
-     * The OAuth client ID (always required).
-     */
-    client_id: string;
-
-    /**
-     * Whether a client_secret is configured (never exposes the actual secret).
-     */
-    has_client_secret?: boolean;
-
-    /**
-     * Default scopes to request during authorization.
-     */
-    default_scopes?: string[];
-
-    /**
-     * Whether to use PKCE (Proof Key for Code Exchange) in the authorization flow.
-     * Only applies to authorization_code flow. Defaults to true.
-     */
-    use_pkce: boolean;
-
-    /**
-     * Optional OAuth 2.0 revocation endpoint URL.
-     */
-    revocation_endpoint?: string;
-
-    created_at: string;
-    updated_at: string;
-}
+export type OAuthProviderData = z.infer<typeof OAuthProviderDataSchema>;
 
 /**
  * OAuth Provider as returned by the API (with id).
  */
-export interface OAuthProvider extends OAuthProviderData {
-    id: string;
-}
-
-export interface RevokeOAuthGrantQuery {
-    include_consent?: boolean;
-}
+export type OAuthProvider = z.infer<typeof OAuthProviderSchema>;
 
 /**
  * Payload for creating an OAuth Provider.
  * The client_secret is accepted as plaintext on create and stored encrypted.
  */
-export interface CreateOAuthProviderPayload {
-    name: string;
-    display_name: string;
-    grant_type?: 'authorization_code' | 'client_credentials';
-    authorization_endpoint?: string;
-    token_endpoint?: string;
-    client_id: string;
-    /**
-     * Optional client secret for confidential clients.
-     * Will be encrypted at rest and never returned in API responses.
-     */
-    client_secret?: string;
-    default_scopes?: string[];
-    use_pkce?: boolean;
-    revocation_endpoint?: string;
-}
+export type CreateOAuthProviderPayload = z.infer<typeof CreateOAuthProviderPayloadSchema>;
 
 /**
  * Payload for updating an OAuth Provider.
  * All fields are optional — only provided fields are updated.
  * To clear the client_secret, set it to an empty string.
  */
-export type UpdateOAuthProviderPayload = Partial<CreateOAuthProviderPayload>;
+export type UpdateOAuthProviderPayload = z.infer<typeof UpdateOAuthProviderPayloadSchema>;
 
 /**
  * OAuth authentication status for a user against an OAuth Provider.
  */
-export interface OAuthProviderAuthStatus {
-    oauth_provider_id: string;
-    oauth_provider_name: string;
-    authenticated: boolean;
-    expires_at?: string;
-    scope?: string;
-}
+export type OAuthProviderAuthStatus = z.infer<typeof OAuthProviderAuthStatusSchema>;
 
 /**
  * Response from the OAuth authorize endpoint.
  * For authorization_code flow: contains authorization_url and state for browser redirect.
  * For client_credentials flow: contains connected=true (token was fetched server-side, no redirect needed).
  */
-export interface OAuthProviderAuthorizeResponse {
-    authorization_url?: string;
-    state?: string;
-    connected?: boolean;
-}
+export type OAuthProviderAuthorizeResponse = z.infer<typeof OAuthProviderAuthorizeResponseSchema>;
 
-export interface OAuthProviderAccessTokenResponse {
-    access_token: string;
-}
+export type OAuthProviderAccessTokenResponse = z.infer<typeof OAuthProviderAccessTokenResponseSchema>;
 
-export interface OAuthProviderExchangePayload {
-    code: string;
-    state: string;
-}
+export type OAuthProviderExchangePayload = z.infer<typeof OAuthProviderExchangePayloadSchema>;

package/src/payload.ts

@@ -1,24 +1,30 @@
+import type { z } from 'zod';
+import type {
+    ComputeCollectionFacetPayloadSchema,
+    ComputeObjectFacetPayloadSchema,
+    ExportPropertiesPayloadSchema,
+    ExportPropertiesResponseSchema,
+} from './api-schemas/content.js';
+import type {
+    ComputeInteractionFacetPayloadSchema,
+    ComputeRunFacetPayloadSchema,
+    RunSearchPayloadSchema,
+    SortOptionSchema,
+    SortOrderSchema,
+} from './api-schemas/interaction.js';
+import type { ComputePromptFacetPayloadSchema } from './api-schemas/prompt.js';
 import type { FacetSpec } from './facets.js';
 import type {
-    ComplexCollectionSearchQuery,
-    ComplexSearchQuery,
     InteractionSearchQuery,
     ObjectSearchQuery,
     ObjectTypeSearchQuery,
     PromptSearchQuery,
-    RunSearchQuery,
     SimpleSearchQuery,
 } from './query.js';
-import type { ColumnLayout } from './store/store.js';
 
-export type SortOrder = 'asc' | 'desc';
+export type SortOrder = z.infer<typeof SortOrderSchema>;
 
-export interface SortOption {
-    /** Field path to sort by (e.g. 'updated_at', 'name', 'properties.title') */
-    field: string;
-    /** Sort direction. Defaults to 'desc'. */
-    order?: SortOrder;
-}
+export type SortOption = z.infer<typeof SortOptionSchema>;
 
 export interface SearchPayload {
     facets?: FacetSpec[];
@@ -60,39 +66,18 @@ export interface PromptSearchPayload extends SearchPayload {
     query?: PromptSearchQuery;
 }
 
-export interface RunSearchPayload extends SearchPayload {
-    query?: RunSearchQuery;
-}
+export type RunSearchPayload = z.infer<typeof RunSearchPayloadSchema>;
 
-export interface ComputeCollectionFacetPayload extends Omit<ComputeFacetPayload, 'query'> {
-    query?: ComplexCollectionSearchQuery;
-}
+export type ComputeCollectionFacetPayload = z.infer<typeof ComputeCollectionFacetPayloadSchema>;
 
-export interface ComputeInteractionFacetPayload extends ComputeFacetPayload {
-    query?: InteractionSearchQuery;
-}
+export type ComputeInteractionFacetPayload = z.infer<typeof ComputeInteractionFacetPayloadSchema>;
 
-export interface ComputeObjectFacetPayload extends ComputeFacetPayload {
-    query?: ComplexSearchQuery;
-}
+export type ComputeObjectFacetPayload = z.infer<typeof ComputeObjectFacetPayloadSchema>;
 
-export interface ComputePromptFacetPayload extends ComputeFacetPayload {
-    query?: PromptSearchQuery;
-}
+export type ComputePromptFacetPayload = z.infer<typeof ComputePromptFacetPayloadSchema>;
 
-export interface ComputeRunFacetPayload extends ComputeFacetPayload {
-    query?: RunSearchQuery;
-}
+export type ComputeRunFacetPayload = z.infer<typeof ComputeRunFacetPayloadSchema>;
 
-export interface ExportPropertiesPayload {
-    objectIds: string[];
-    type: string;
-    query?: ComplexSearchQuery;
-    table_layout?: ColumnLayout[];
-}
+export type ExportPropertiesPayload = z.infer<typeof ExportPropertiesPayloadSchema>;
 
-export interface ExportPropertiesResponse {
-    type: string;
-    name: string;
-    data: string;
-}
+export type ExportPropertiesResponse = z.infer<typeof ExportPropertiesResponseSchema>;

package/src/platform-event-validation.test.ts

@@ -63,6 +63,32 @@ describe('event subscription input validation', () => {
         expect(result.errors.join(' ')).toContain('timeout_ms');
     });
 
+    it('accepts a fully resolved app hook target', () => {
+        const result = getCreateEventSubscriptionValidationResult(
+            validCreate({
+                target: {
+                    type: 'app',
+                    app_id: 'content-app',
+                    installation_id: 'installation-1',
+                    hook: 'content-updated',
+                    url: 'https://gateway.example/apps/content-app/api/hooks/content-updated',
+                },
+            }),
+        );
+        expect(result.valid).toBe(true);
+    });
+
+    it('requires app hook identity and URL fields', () => {
+        const result = getCreateEventSubscriptionValidationResult(
+            validCreate({ target: { type: 'app', app_id: '', installation_id: '', hook: '', url: '' } }),
+        );
+        expect(result.valid).toBe(false);
+        expect(result.errors.join(' ')).toContain('app_id');
+        expect(result.errors.join(' ')).toContain('installation_id');
+        expect(result.errors.join(' ')).toContain('hook');
+        expect(result.errors.join(' ')).toContain('url');
+    });
+
     it('requires endpoint for workflow targets', () => {
         const result = getCreateEventSubscriptionValidationResult(
             validCreate({ target: { type: 'workflow' } as never }),

package/src/platform-event-validation.ts

@@ -163,8 +163,8 @@ function validateTarget(target: unknown, errors: string[]): void {
         return;
     }
     const type = target.type;
-    if (type !== 'workflow' && type !== 'webhook' && type !== 'agent' && type !== 'process') {
-        errors.push('target.type must be one of workflow, webhook, agent, process');
+    if (type !== 'workflow' && type !== 'webhook' && type !== 'app' && type !== 'agent' && type !== 'process') {
+        errors.push('target.type must be one of workflow, webhook, app, agent, process');
         return;
     }
     const t = target as EventDeliveryTargetInput;
@@ -204,6 +204,19 @@ function validateTarget(target: unknown, errors: string[]): void {
             }
             break;
         }
+        case 'app': {
+            for (const field of ['app_id', 'installation_id', 'hook', 'url'] as const) {
+                if (typeof t[field] !== 'string' || t[field].length === 0) {
+                    errors.push(`app target requires a non-empty "${field}"`);
+                }
+            }
+            if (t.timeout_ms !== undefined) {
+                if (!Number.isInteger(t.timeout_ms) || t.timeout_ms <= 0 || t.timeout_ms > MAX_WEBHOOK_TIMEOUT_MS) {
+                    errors.push(`app target.timeout_ms must be an integer between 1 and ${MAX_WEBHOOK_TIMEOUT_MS}`);
+                }
+            }
+            break;
+        }
         case 'process':
             if ((typeof t.process_ref !== 'string' || t.process_ref.length === 0) && !isRecord(t.process_definition)) {
                 errors.push('process target requires "process_ref" or an inline "process_definition"');