diff --git a/content/docs/references/ai/agent.mdx b/content/docs/references/ai/agent.mdx index b0409894f8..61ca266add 100644 --- a/content/docs/references/ai/agent.mdx +++ b/content/docs/references/ai/agent.mdx @@ -76,7 +76,7 @@ const result = AIKnowledge.parse(data); | **instructions** | `string` | ✅ | System Prompt / Prime Directives | | **model** | `Object` | optional | | | **lifecycle** | `Object` | optional | State machine defining the agent conversation follow and constraints | -| **surface** | `Enum<'ask' \| 'build'>` | ✅ | Product surface this agent binds ('ask' | 'build') — ADR-0063 §1 | +| **surface** | `Enum<'ask' \| 'build'>` | ✅ | Product surface this agent binds ('ask' \| 'build') — ADR-0063 §1 | | **skills** | `string[]` | optional | Skill names to attach (Agent→Skill→Tool architecture) | | **tools** | `Object[]` | optional | Direct tool references (legacy fallback) | | **knowledge** | `Object` | optional | RAG access | @@ -92,8 +92,8 @@ const result = AIKnowledge.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this agent. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/ai/model-registry.mdx b/content/docs/references/ai/model-registry.mdx index b0212ca298..855d6b37f6 100644 --- a/content/docs/references/ai/model-registry.mdx +++ b/content/docs/references/ai/model-registry.mdx @@ -18,8 +18,8 @@ Enables AI-powered ObjectStack applications to discover and use LLMs consistentl ## TypeScript Usage ```typescript -import { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistryEntry, ModelSelectionCriteria, PromptVariable } from '@objectstack/spec/ai'; -import type { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistryEntry, ModelSelectionCriteria, PromptVariable } from '@objectstack/spec/ai'; +import { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; +import type { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; // Validate data const result = ModelCapability.parse(data); @@ -111,6 +111,21 @@ const result = ModelCapability.parse(data); * `custom` +--- + +## ModelRegistry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Registry name | +| **models** | `Record` | ✅ | Model entries by ID | +| **promptTemplates** | `Record` | optional | Prompt templates by name | +| **defaultModel** | `string` | optional | Default model ID | +| **enableAutoFallback** | `boolean` | optional | Auto-fallback on errors | + + --- ## ModelRegistryEntry @@ -142,6 +157,35 @@ const result = ModelCapability.parse(data); | **excludeDeprecated** | `boolean` | ✅ | | +--- + +## PromptTemplate + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique template identifier | +| **name** | `string` | ✅ | Template name (snake_case) | +| **label** | `string` | ✅ | Display name | +| **system** | `string \| Object` | optional | System prompt — supports `{{var}`} interpolation | +| **user** | `string \| Object` | ✅ | User prompt template — supports `{{var}`} interpolation | +| **assistant** | `string` | optional | Assistant message prefix | +| **variables** | `Object[]` | optional | Template variables | +| **modelId** | `string` | optional | Recommended model ID | +| **temperature** | `number` | optional | | +| **maxTokens** | `number` | optional | | +| **topP** | `number` | optional | | +| **frequencyPenalty** | `number` | optional | | +| **presencePenalty** | `number` | optional | | +| **stopSequences** | `string[]` | optional | | +| **version** | `string` | optional | | +| **description** | `string` | optional | | +| **category** | `string` | optional | Template category (e.g., "code_generation", "support") | +| **tags** | `string[]` | optional | | +| **examples** | `Object[]` | optional | | + + --- ## PromptVariable diff --git a/content/docs/references/ai/skill.mdx b/content/docs/references/ai/skill.mdx index aeffbb6c92..75ad71370d 100644 --- a/content/docs/references/ai/skill.mdx +++ b/content/docs/references/ai/skill.mdx @@ -36,7 +36,7 @@ const result = Skill.parse(data); | **name** | `string` | ✅ | Skill unique identifier (snake_case) | | **label** | `string` | ✅ | Skill display name | | **description** | `string` | optional | Skill description | -| **surface** | `Enum<'ask' \| 'build' \| 'both'>` | ✅ | Agent surface this skill binds to ('ask' | 'build' | 'both') — ADR-0063 §3 | +| **surface** | `Enum<'ask' \| 'build' \| 'both'>` | ✅ | Agent surface this skill binds to ('ask' \| 'build' \| 'both') — ADR-0063 §3 | | **instructions** | `string` | optional | LLM instructions when skill is active | | **tools** | `string[]` | ✅ | Tool names belonging to this skill (supports trailing wildcard, e.g. `action_*`) | | **triggerPhrases** | `string[]` | optional | Phrases that activate this skill | @@ -46,8 +46,8 @@ const result = Skill.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this skill. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/ai/tool.mdx b/content/docs/references/ai/tool.mdx index be5081bd73..c7fdd70eeb 100644 --- a/content/docs/references/ai/tool.mdx +++ b/content/docs/references/ai/tool.mdx @@ -45,8 +45,8 @@ const result = Tool.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this tool. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/api/automation-api.mdx b/content/docs/references/api/automation-api.mdx index 19291864fd..2d5a8831a7 100644 --- a/content/docs/references/api/automation-api.mdx +++ b/content/docs/references/api/automation-api.mdx @@ -40,8 +40,8 @@ GET /api/automation/:name/runs/:runId — Get single execution run ## TypeScript Usage ```typescript -import { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse } from '@objectstack/spec/api'; -import type { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse } from '@objectstack/spec/api'; +import { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api'; +import type { AutomationApiErrorCode, AutomationFlowPathParams, AutomationRunPathParams, CreateFlowRequest, CreateFlowResponse, DeleteFlowRequest, DeleteFlowResponse, FlowSummary, GetFlowRequest, GetFlowResponse, GetRunRequest, GetRunResponse, ListFlowsRequest, ListFlowsResponse, ListRunsRequest, ListRunsResponse, ToggleFlowRequest, ToggleFlowResponse, TriggerFlowRequest, TriggerFlowResponse, UpdateFlowRequest, UpdateFlowResponse } from '@objectstack/spec/api'; // Validate data const result = AutomationApiErrorCode.parse(data); @@ -87,6 +87,53 @@ const result = AutomationApiErrorCode.parse(data); | **runId** | `string` | ✅ | Execution run ID | +--- + +## CreateFlowRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Machine name | +| **label** | `string` | ✅ | Flow label | +| **description** | `string` | optional | | +| **successMessage** | `string` | optional | Toast shown when a screen flow completes (defaults to a generic "Done"). | +| **errorMessage** | `string` | optional | Toast shown when a screen flow fails (defaults to the raw error). | +| **version** | `integer` | optional | Version number | +| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional | Deployment status | +| **template** | `boolean` | optional | Is logic template (Subflow) | +| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | ✅ | Flow type | +| **variables** | `Object[]` | optional | Flow variables | +| **nodes** | `Object[]` | ✅ | Flow nodes | +| **edges** | `Object[]` | ✅ | Flow connections | +| **active** | `boolean` | optional | Is active (Deprecated: use status) | +| **runAs** | `Enum<'system' \| 'user'>` | optional | Execution identity for the run: system = elevated (bypasses RLS), user = the triggering user (RLS-respecting). A schedule-triggered run has no trigger user, so under user it runs UNSCOPED (elevated) — declare system to make that explicit. | +| **errorHandling** | `Object` | optional | Flow-level error handling configuration | +| **protection** | `Object` | optional | Package author protection block — lock policy for this flow. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + + +--- + +## CreateFlowResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | The created flow definition | + + --- ## DeleteFlowRequest @@ -141,6 +188,20 @@ const result = AutomationApiErrorCode.parse(data); | **name** | `string` | ✅ | Flow machine name (snake_case) | +--- + +## GetFlowResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | Full flow definition | + + --- ## GetRunRequest @@ -281,3 +342,29 @@ const result = AutomationApiErrorCode.parse(data); --- +## UpdateFlowRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Flow machine name (snake_case) | +| **definition** | `Object` | ✅ | Partial flow definition to update | + + +--- + +## UpdateFlowResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | The updated flow definition | + + +--- + diff --git a/content/docs/references/api/export.mdx b/content/docs/references/api/export.mdx index 71a28d82f2..aa976a0997 100644 --- a/content/docs/references/api/export.mdx +++ b/content/docs/references/api/export.mdx @@ -24,8 +24,8 @@ Base path: /api/v1/data/\{object\}/export ## TypeScript Usage ```typescript -import { CreateExportJobRequest, CreateExportJobResponse, CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, ExportJobProgress, ExportJobStatus, ExportJobSummary, FieldMappingEntry, GetExportJobDownloadRequest, GetExportJobDownloadResponse, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListExportJobsRequest, ListExportJobsResponse, ListImportJobsRequest, ListImportJobsResponse, ScheduleExportResponse, UndoImportJobResponse } from '@objectstack/spec/api'; -import type { CreateExportJobRequest, CreateExportJobResponse, CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, ExportJobProgress, ExportJobStatus, ExportJobSummary, FieldMappingEntry, GetExportJobDownloadRequest, GetExportJobDownloadResponse, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListExportJobsRequest, ListExportJobsResponse, ListImportJobsRequest, ListImportJobsResponse, ScheduleExportResponse, UndoImportJobResponse } from '@objectstack/spec/api'; +import { CreateExportJobRequest, CreateExportJobResponse, CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, ExportJobProgress, ExportJobStatus, ExportJobSummary, FieldMappingEntry, GetExportJobDownloadRequest, GetExportJobDownloadResponse, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListExportJobsRequest, ListExportJobsResponse, ListImportJobsRequest, ListImportJobsResponse, ScheduleExportRequest, ScheduleExportResponse, ScheduledExport, UndoImportJobResponse } from '@objectstack/spec/api'; +import type { CreateExportJobRequest, CreateExportJobResponse, CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, ExportJobProgress, ExportJobStatus, ExportJobSummary, FieldMappingEntry, GetExportJobDownloadRequest, GetExportJobDownloadResponse, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListExportJobsRequest, ListExportJobsResponse, ListImportJobsRequest, ListImportJobsResponse, ScheduleExportRequest, ScheduleExportResponse, ScheduledExport, UndoImportJobResponse } from '@objectstack/spec/api'; // Validate data const result = CreateExportJobRequest.parse(data); @@ -518,6 +518,25 @@ Type: `Object[]` | **jobs** | `Object[]` | ✅ | Import jobs, newest first | +--- + +## ScheduleExportRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Schedule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **object** | `string` | ✅ | Object name to export | +| **format** | `Enum<'csv' \| 'json' \| 'jsonl' \| 'xlsx' \| 'parquet'>` | optional | Export file format | +| **fields** | `string[]` | optional | Fields to include | +| **filter** | `Record` | optional | Record filter criteria | +| **templateId** | `string` | optional | Export template ID for field mappings | +| **schedule** | `Object` | ✅ | Schedule timing configuration | +| **delivery** | `Object` | ✅ | Export delivery configuration | + + --- ## ScheduleExportResponse @@ -532,6 +551,31 @@ Type: `Object[]` | **data** | `Object` | ✅ | | +--- + +## ScheduledExport + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Scheduled export ID | +| **name** | `string` | ✅ | Schedule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **object** | `string` | ✅ | Object name to export | +| **format** | `Enum<'csv' \| 'json' \| 'jsonl' \| 'xlsx' \| 'parquet'>` | optional | Export file format | +| **fields** | `string[]` | optional | Fields to include | +| **filter** | `Record` | optional | Record filter criteria | +| **templateId** | `string` | optional | Export template ID for field mappings | +| **schedule** | `Object` | ✅ | Schedule timing configuration | +| **delivery** | `Object` | ✅ | Export delivery configuration | +| **enabled** | `boolean` | optional | Whether the scheduled export is active | +| **lastRunAt** | `string` | optional | Last execution timestamp | +| **nextRunAt** | `string` | optional | Next scheduled execution | +| **createdAt** | `string` | optional | Creation timestamp | +| **createdBy** | `string` | optional | User who created the schedule | + + --- ## UndoImportJobResponse diff --git a/content/docs/references/api/graphql.mdx b/content/docs/references/api/graphql.mdx index e70a165010..997b782230 100644 --- a/content/docs/references/api/graphql.mdx +++ b/content/docs/references/api/graphql.mdx @@ -126,8 +126,8 @@ status ## TypeScript Usage ```typescript -import { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api'; -import type { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api'; +import { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api'; +import type { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api'; // Validate data const result = FederationEntity.parse(data); @@ -214,6 +214,23 @@ const result = FederationEntity.parse(data); | **fields** | `string` | ✅ | Selection set of required fields (e.g., "price weight") | +--- + +## GraphQLConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Enable GraphQL API | +| **path** | `string` | optional | GraphQL endpoint path | +| **playground** | `Object` | optional | GraphQL Playground configuration | +| **schema** | `Object` | optional | Schema generation configuration | +| **dataLoaders** | `Object[]` | optional | DataLoader configurations | +| **security** | `Object` | optional | Security configuration | +| **federation** | `Object` | optional | GraphQL Federation gateway configuration | + + --- ## GraphQLDataLoaderConfig @@ -325,6 +342,28 @@ const result = FederationEntity.parse(data); | **errorMessage** | `string` | optional | Custom error message for complexity violations | +--- + +## GraphQLQueryConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Query field name (camelCase recommended) | +| **object** | `string` | ✅ | Source ObjectQL object name | +| **type** | `Enum<'get' \| 'list' \| 'search'>` | ✅ | Query type | +| **description** | `string` | optional | Query description | +| **args** | `Record` | optional | Query arguments | +| **filtering** | `Object` | optional | Filtering capabilities | +| **sorting** | `Object` | optional | Sorting capabilities | +| **pagination** | `Object` | optional | Pagination configuration | +| **fields** | `Object` | optional | Field selection configuration | +| **authRequired** | `boolean` | optional | Require authentication | +| **permissions** | `string[]` | optional | Required permissions | +| **cache** | `Object` | optional | Query caching | + + --- ## GraphQLQueryDepthLimit @@ -359,6 +398,20 @@ const result = FederationEntity.parse(data); | **includeHeaders** | `boolean` | ✅ | Include rate limit headers in response | +--- + +## GraphQLResolverConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **path** | `string` | ✅ | Resolver path (Type.field) | +| **type** | `Enum<'datasource' \| 'computed' \| 'script' \| 'proxy'>` | ✅ | Resolver implementation type | +| **implementation** | `Object` | optional | Implementation configuration | +| **cache** | `Object` | optional | Resolver caching | + + --- ## GraphQLScalarType diff --git a/content/docs/references/api/metadata.mdx b/content/docs/references/api/metadata.mdx index 3af7d1a88c..ccc6859521 100644 --- a/content/docs/references/api/metadata.mdx +++ b/content/docs/references/api/metadata.mdx @@ -50,13 +50,27 @@ the entire platform, including Hono, Next.js, and NestJS adapters. ## TypeScript Usage ```typescript -import { ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse } from '@objectstack/spec/api'; -import type { ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse } from '@objectstack/spec/api'; +import { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api'; +import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api'; // Validate data -const result = ConceptListResponse.parse(data); +const result = AppDefinitionResponse.parse(data); ``` +--- + +## AppDefinitionResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | Full App Configuration | + + --- ## ConceptListResponse @@ -355,6 +369,20 @@ Metadata query with filtering, sorting, and pagination | **namespace** | `string` | optional | Optional namespace | +--- + +## MetadataTypeInfoResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | optional | Type info | + + --- ## MetadataTypesResponse @@ -397,3 +425,17 @@ Metadata query with filtering, sorting, and pagination --- +## ObjectDefinitionResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | Full Object Schema | + + +--- + diff --git a/content/docs/references/api/package-api.mdx b/content/docs/references/api/package-api.mdx index 55501ca0e3..ed9879457b 100644 --- a/content/docs/references/api/package-api.mdx +++ b/content/docs/references/api/package-api.mdx @@ -36,8 +36,8 @@ DELETE /api/v1/packages/:packageId — Uninstall a package ## TypeScript Usage ```typescript -import { GetInstalledPackageRequest, ListInstalledPackagesRequest, PackageApiErrorCode, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeResponse, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api'; -import type { GetInstalledPackageRequest, ListInstalledPackagesRequest, PackageApiErrorCode, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeResponse, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api'; +import { GetInstalledPackageRequest, GetInstalledPackageResponse, ListInstalledPackagesRequest, ListInstalledPackagesResponse, PackageApiErrorCode, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api'; +import type { GetInstalledPackageRequest, GetInstalledPackageResponse, ListInstalledPackagesRequest, ListInstalledPackagesResponse, PackageApiErrorCode, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api'; // Validate data const result = GetInstalledPackageRequest.parse(data); @@ -54,6 +54,22 @@ const result = GetInstalledPackageRequest.parse(data); | **packageId** | `string` | ✅ | Package identifier | +--- + +## GetInstalledPackageResponse + +Get installed package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | Installed package details | + + --- ## ListInstalledPackagesRequest @@ -70,6 +86,22 @@ List installed packages request | **cursor** | `string` | optional | Cursor for pagination | +--- + +## ListInstalledPackagesResponse + +List installed packages response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | | + + --- ## PackageApiErrorCode @@ -91,6 +123,39 @@ List installed packages request * `upload_failed` +--- + +## PackageInstallRequest + +Install package request + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **manifest** | `Object` | ✅ | Package manifest to install | +| **settings** | `Record` | optional | User-provided settings at install time | +| **enableOnInstall** | `boolean` | optional | Whether to enable immediately after install | +| **platformVersion** | `string` | optional | Current platform version for compatibility verification | +| **artifactRef** | `Object` | optional | Artifact reference for marketplace installation | + + +--- + +## PackageInstallResponse + +Install package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **success** | `boolean` | ✅ | Operation success status | +| **error** | `Object` | optional | Error details if success is false | +| **meta** | `Object` | optional | Response metadata | +| **data** | `Object` | ✅ | | + + --- ## PackagePathParams @@ -133,6 +198,25 @@ Rollback package response | **data** | `Object` | ✅ | | +--- + +## PackageUpgradeRequest + +Upgrade package request + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **packageId** | `string` | ✅ | Package ID to upgrade | +| **targetVersion** | `string` | optional | Target version (defaults to latest) | +| **manifest** | `Object` | optional | New manifest for the target version | +| **createSnapshot** | `boolean` | optional | Whether to create a pre-upgrade backup snapshot | +| **mergeStrategy** | `Enum<'keep-custom' \| 'accept-incoming' \| 'three-way-merge'>` | optional | How to handle customer customizations | +| **dryRun** | `boolean` | optional | Preview upgrade without making changes | +| **skipValidation** | `boolean` | optional | Skip pre-upgrade compatibility checks | + + --- ## PackageUpgradeResponse @@ -149,6 +233,20 @@ Upgrade package response | **data** | `Object` | ✅ | | +--- + +## ResolveDependenciesRequest + +Resolve dependencies request + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **manifest** | `Object` | ✅ | Package manifest to resolve dependencies for | +| **platformVersion** | `string` | optional | Current platform version for compatibility filtering | + + --- ## ResolveDependenciesResponse diff --git a/content/docs/references/api/package-registry.mdx b/content/docs/references/api/package-registry.mdx index 1c8834813a..feafa7bf2c 100644 --- a/content/docs/references/api/package-registry.mdx +++ b/content/docs/references/api/package-registry.mdx @@ -12,8 +12,8 @@ description: Package Registry protocol schemas ## TypeScript Usage ```typescript -import { DisablePackageRequest, EnablePackageRequest, GetPackageRequest, ListPackagesRequest, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; -import type { DisablePackageRequest, EnablePackageRequest, GetPackageRequest, ListPackagesRequest, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; +import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, ListPackagesRequest, ListPackagesResponse, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; +import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, ListPackagesRequest, ListPackagesResponse, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; // Validate data const result = DisablePackageRequest.parse(data); @@ -32,6 +32,20 @@ Disable package request | **id** | `string` | ✅ | Package ID to disable | +--- + +## DisablePackageResponse + +Disable package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Disabled package details | +| **message** | `string` | optional | Disable status message | + + --- ## EnablePackageRequest @@ -45,6 +59,20 @@ Enable package request | **id** | `string` | ✅ | Package ID to enable | +--- + +## EnablePackageResponse + +Enable package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Enabled package details | +| **message** | `string` | optional | Enable status message | + + --- ## GetPackageRequest @@ -58,6 +86,50 @@ Get package request | **id** | `string` | ✅ | Package identifier | +--- + +## GetPackageResponse + +Get package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Package details | + + +--- + +## InstallPackageRequest + +Install package request + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **manifest** | `Object` | ✅ | Package manifest to install | +| **settings** | `Record` | optional | User-provided settings at install time | +| **enableOnInstall** | `boolean` | optional | Whether to enable immediately after install | +| **platformVersion** | `string` | optional | Current platform version for compatibility verification | + + +--- + +## InstallPackageResponse + +Install package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Installed package details | +| **message** | `string` | optional | Installation status message | +| **dependencyResolution** | `Object` | optional | Dependency resolution result from install analysis | + + --- ## ListPackagesRequest @@ -73,6 +145,20 @@ List packages request | **enabled** | `boolean` | optional | Filter by enabled state | +--- + +## ListPackagesResponse + +List packages response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **packages** | `Object[]` | ✅ | List of installed packages | +| **total** | `number` | ✅ | Total package count | + + --- ## UninstallPackageRequest diff --git a/content/docs/references/api/protocol.mdx b/content/docs/references/api/protocol.mdx index 437b8d010e..45d38d2d32 100644 --- a/content/docs/references/api/protocol.mdx +++ b/content/docs/references/api/protocol.mdx @@ -20,8 +20,8 @@ validation. Each entry is a canonical [ActionDescriptorSchema](ActionDescriptorS ## TypeScript Usage ```typescript -import { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationActionsResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteMetaItemRequest, DeleteMetaItemResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetViewRequest, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api'; -import type { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationActionsResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteMetaItemRequest, DeleteMetaItemResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetViewRequest, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api'; +import { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationActionsResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, CreateViewRequest, CreateViewResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteMetaItemRequest, DeleteMetaItemResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetUiViewResponse, GetViewRequest, GetViewResponse, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, ListViewsResponse, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, UpdateViewRequest, UpdateViewResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api'; +import type { AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationActionsResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, CreateViewRequest, CreateViewResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteMetaItemRequest, DeleteMetaItemResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetUiViewResponse, GetViewRequest, GetViewResponse, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, HttpFindQueryParams, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, ListViewsResponse, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, NotificationPreferences, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, UpdateViewRequest, UpdateViewResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api'; // Validate data const result = AiInsightsRequest.parse(data); @@ -246,6 +246,31 @@ const result = AiInsightsRequest.parse(data); | **count** | `number` | ✅ | Number of records created | +--- + +## CreateViewRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name (snake_case) | +| **data** | `Object` | ✅ | View definition to create | + + +--- + +## CreateViewResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name | +| **viewId** | `string` | ✅ | Created view identifier | +| **view** | `Object` | ✅ | Created view definition | + + --- ## DeleteDataRequest @@ -712,6 +737,28 @@ const result = AiInsightsRequest.parse(data); | **type** | `Enum<'list' \| 'form'>` | ✅ | View type | +--- + +## GetUiViewResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **list** | `Object` | optional | | +| **form** | `Object` | optional | | +| **listViews** | `Record` | optional | Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047) | +| **formViews** | `Record` | optional | Additional named form views | +| **protection** | `Object` | optional | Package author protection block — lock policy for this view. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + + --- ## GetViewRequest @@ -724,6 +771,18 @@ const result = AiInsightsRequest.parse(data); | **viewId** | `string` | ✅ | View identifier | +--- + +## GetViewResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name | +| **view** | `Object` | ✅ | View definition | + + --- ## GetWorkflowConfigRequest @@ -832,6 +891,18 @@ const result = AiInsightsRequest.parse(data); | **type** | `Enum<'list' \| 'form'>` | optional | Filter by view type | +--- + +## ListViewsResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name | +| **views** | `Object[]` | ✅ | Array of view definitions | + + --- ## MarkAllNotificationsReadRequest @@ -1163,6 +1234,32 @@ const result = AiInsightsRequest.parse(data); | **preferences** | `Object` | ✅ | Updated notification preferences | +--- + +## UpdateViewRequest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name (snake_case) | +| **viewId** | `string` | ✅ | View identifier | +| **data** | `Object` | ✅ | Partial view data to update | + + +--- + +## UpdateViewResponse + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object name | +| **viewId** | `string` | ✅ | Updated view identifier | +| **view** | `Object` | ✅ | Updated view definition | + + --- ## WorkflowState diff --git a/content/docs/references/automation/connector.mdx b/content/docs/references/automation/connector.mdx index 59bea827bf..2a1a7c6c09 100644 --- a/content/docs/references/automation/connector.mdx +++ b/content/docs/references/automation/connector.mdx @@ -12,8 +12,8 @@ description: Connector protocol schemas ## TypeScript Usage ```typescript -import { Connector, ConnectorTrigger } from '@objectstack/spec/automation'; -import type { Connector, ConnectorTrigger } from '@objectstack/spec/automation'; +import { Connector, ConnectorTrigger, DataSyncConfig } from '@objectstack/spec/automation'; +import type { Connector, ConnectorTrigger, DataSyncConfig } from '@objectstack/spec/automation'; // Validate data const result = Connector.parse(data); @@ -66,3 +66,32 @@ const result = Connector.parse(data); --- +## DataSyncConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Sync configuration name (snake_case) | +| **label** | `string` | optional | Sync display name | +| **description** | `string` | optional | Sync description | +| **source** | `Object` | ✅ | Data source | +| **destination** | `Object` | ✅ | Data destination | +| **direction** | `Enum<'push' \| 'pull' \| 'bidirectional'>` | optional | Sync direction | +| **syncMode** | `Enum<'full' \| 'incremental' \| 'realtime'>` | optional | Sync mode | +| **conflictResolution** | `Enum<'source_wins' \| 'destination_wins' \| 'latest_wins' \| 'manual' \| 'merge'>` | optional | Conflict resolution | +| **schedule** | `string \| Object` | optional | Cron schedule | +| **enabled** | `boolean` | optional | Sync enabled | +| **changeTrackingField** | `string` | optional | Field for change tracking | +| **batchSize** | `integer` | optional | Batch size for processing | +| **retry** | `Object` | optional | Retry configuration | +| **validation** | `Object` | optional | Validation rules | +| **errorHandling** | `Object` | optional | Error handling | +| **optimization** | `Object` | optional | Performance optimization | +| **audit** | `Object` | optional | Audit configuration | +| **tags** | `string[]` | optional | Sync tags | +| **metadata** | `Record` | optional | Custom metadata | + + +--- + diff --git a/content/docs/references/automation/control-flow.mdx b/content/docs/references/automation/control-flow.mdx new file mode 100644 index 0000000000..497ad61cbb --- /dev/null +++ b/content/docs/references/automation/control-flow.mdx @@ -0,0 +1,156 @@ +--- +title: Control Flow +description: Control Flow protocol schemas +--- + +{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} + +@module automation/control-flow + +Structured control-flow constructs (ADR-0031) — the **native + AI-authored** + +flow model: a `loop` **container**, a `parallel` **block**, and structured + +`try/catch/retry`. Unlike BPMN's gateway/boundary/token graph (kept in the + +protocol for *interop* only), these constructs are **well-formed by + +construction**, locally composable, and statically analyzable — the right + +substrate for LLM authoring (ADR-0010/0011). + +## Representation — decision: **(B) nested sub-structure** + +ADR-0031 flagged two ways to carry structured containers in the flat + +`nodes[]`+`edges[]` model: + +- **(A)** marker-delimited scoped regions (a container node + a scope-end + +marker; the body is the edges *between* them in the main graph), or + +- **(B)** the container node carries a **nested mini-flow** in its `config`. + +We adopt **(B)**. Each container holds its body as a self-contained + +[FlowRegionSchema](FlowRegionSchema) (`config.body` for `loop`, `config.branches[]` for + +`parallel`, `config.try`/`config.catch` for `try_catch`). The reasons: + +1. **Well-formed by construction** — a nested region is its *own* graph, so + +single-entry is intrinsic; there are no scope markers to balance and no + +way to "leak" an edge across a boundary. Validation is local. + +2. **The shared engine traversal stays untouched** — the container executor + +runs its own body via a scoped helper; the main DAG `traverseNext` never + +learns about scope markers (important under the multi-agent discipline + +around `engine.ts`). The container's *ordinary* out-edges remain the + +"after-loop / after-block" continuation. + +3. **Cleaner AST for AI** — ADR-0031 calls (B) "the cleaner long-term AST," + +and AI authoring is the design center. + +Existing flat-graph loops (a `loop` node with no `config.body`) keep their + +legacy behavior — the constructs are **additive**, activated only when the + +nested structure is present. + +The canonical construct type ids are [LOOP_NODE_TYPE](LOOP_NODE_TYPE) (`loop`, + +pre-existing), [PARALLEL_NODE_TYPE](PARALLEL_NODE_TYPE) (`parallel`), and + +[TRY_CATCH_NODE_TYPE](TRY_CATCH_NODE_TYPE) (`try_catch`). These are distinct from the BPMN + +interop node types (`parallel_gateway` / `join_gateway` / `boundary_event`), + +which remain author-invisible interchange representations. + + +**Source:** `packages/spec/src/automation/control-flow.zod.ts` + + +## TypeScript Usage + +```typescript +import { FlowRegion, LoopConfig, ParallelBranch, ParallelConfig, TryCatchConfig } from '@objectstack/spec/automation'; +import type { FlowRegion, LoopConfig, ParallelBranch, ParallelConfig, TryCatchConfig } from '@objectstack/spec/automation'; + +// Validate data +const result = FlowRegion.parse(data); +``` + +--- + +## FlowRegion + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **nodes** | `Object[]` | ✅ | Region body nodes (single-entry/single-exit sub-graph) | +| **edges** | `Object[]` | optional | Region body edges | + + +--- + +## LoopConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **collection** | `string` | ✅ | Template/variable resolving to the array to iterate | +| **iteratorVariable** | `string` | optional | Loop variable holding the current item | +| **indexVariable** | `string` | optional | Optional loop variable holding the current index | +| **maxIterations** | `integer` | optional | Hard cap on iterations (clamped to the engine ceiling) | +| **body** | `Object` | optional | Loop body region (omit for legacy flat-graph loops) | + + +--- + +## ParallelBranch + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Branch label | +| **nodes** | `Object[]` | ✅ | Branch body nodes | +| **edges** | `Object[]` | optional | Branch body edges | + + +--- + +## ParallelConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **branches** | `Object[]` | ✅ | Branch regions executed concurrently; implicit join at block end | + + +--- + +## TryCatchConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **try** | `Object` | ✅ | Protected region | +| **catch** | `Object` | optional | Handler region run when the try region fails | +| **errorVariable** | `string` | optional | Variable holding the caught error in the catch region | +| **retry** | `Object` | optional | Optional retry policy for the try region | + + +--- + diff --git a/content/docs/references/automation/etl.mdx b/content/docs/references/automation/etl.mdx index d28a6ed67d..fc67127810 100644 --- a/content/docs/references/automation/etl.mdx +++ b/content/docs/references/automation/etl.mdx @@ -138,8 +138,8 @@ schedule: '0 2 * * *' // Daily at 2 AM ## TypeScript Usage ```typescript -import { ETLDestination, ETLEndpointType, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; -import type { ETLDestination, ETLEndpointType, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; +import { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; +import type { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; // Validate data const result = ETLDestination.parse(data); @@ -176,6 +176,29 @@ const result = ETLDestination.parse(data); * `spreadsheet` +--- + +## ETLPipeline + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Pipeline identifier (snake_case) | +| **label** | `string` | optional | Pipeline display name | +| **description** | `string` | optional | Pipeline description | +| **source** | `Object` | ✅ | Data source | +| **destination** | `Object` | ✅ | Data destination | +| **transformations** | `Object[]` | optional | Transformation pipeline | +| **syncMode** | `Enum<'full' \| 'incremental' \| 'cdc'>` | optional | Sync mode | +| **schedule** | `string \| Object` | optional | Cron schedule expression | +| **enabled** | `boolean` | optional | Pipeline enabled status | +| **retry** | `Object` | optional | Retry configuration | +| **notifications** | `Object` | optional | Notification settings | +| **tags** | `string[]` | optional | Pipeline tags | +| **metadata** | `Record` | optional | Custom metadata | + + --- ## ETLPipelineRun diff --git a/content/docs/references/automation/execution.mdx b/content/docs/references/automation/execution.mdx index 4c46580a2c..01fba062b0 100644 --- a/content/docs/references/automation/execution.mdx +++ b/content/docs/references/automation/execution.mdx @@ -22,8 +22,8 @@ AWS Step Functions execution logs. ## TypeScript Usage ```typescript -import { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog } from '@objectstack/spec/automation'; -import type { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog } from '@objectstack/spec/automation'; +import { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog, ScheduleState } from '@objectstack/spec/automation'; +import type { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog, ScheduleState } from '@objectstack/spec/automation'; // Validate data const result = Checkpoint.parse(data); @@ -153,7 +153,34 @@ const result = Checkpoint.parse(data); | **retryAttempt** | `integer` | optional | Retry attempt number (0 = first try) | | **parentNodeId** | `string` | optional | Enclosing structured-region container node ID (loop/parallel/try_catch) | | **iteration** | `integer` | optional | Zero-based loop iteration or parallel branch index of the enclosing region | -| **regionKind** | `string` | optional | Region kind the step ran in: loop-body | parallel-branch | try | catch | +| **regionKind** | `string` | optional | Region kind the step ran in: loop-body \| parallel-branch \| try \| catch | + + +--- + +## ScheduleState + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Schedule instance ID | +| **flowName** | `string` | ✅ | Flow machine name | +| **cronExpression** | `string \| Object` | ✅ | Cron expression — cron`0 9 * * MON-FRI` | +| **timezone** | `string` | optional | IANA timezone for cron evaluation | +| **status** | `Enum<'active' \| 'paused' \| 'disabled' \| 'expired'>` | optional | Current schedule status | +| **nextRunAt** | `string` | optional | Next scheduled execution timestamp | +| **lastRunAt** | `string` | optional | Last execution timestamp | +| **lastExecutionId** | `string` | optional | Execution ID of the last run | +| **lastRunStatus** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>` | optional | Status of the last run | +| **totalRuns** | `integer` | optional | Total number of executions | +| **consecutiveFailures** | `integer` | optional | Consecutive failed executions | +| **startDate** | `string` | optional | Schedule effective start date | +| **endDate** | `string` | optional | Schedule expiration date | +| **maxRuns** | `integer` | optional | Maximum total executions before auto-disable | +| **createdAt** | `string` | ✅ | Schedule creation timestamp | +| **updatedAt** | `string` | optional | Last update timestamp | +| **createdBy** | `string` | optional | User who created the schedule | --- diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx index 7ca4b3d70f..52ae1fec90 100644 --- a/content/docs/references/automation/flow.mdx +++ b/content/docs/references/automation/flow.mdx @@ -30,13 +30,63 @@ no longer constrains authored flows — plugins extend the vocabulary. ## TypeScript Usage ```typescript -import { FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; -import type { FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; +import { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable, FlowVersionHistory } from '@objectstack/spec/automation'; +import type { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable, FlowVersionHistory } from '@objectstack/spec/automation'; // Validate data -const result = FlowNode.parse(data); +const result = Flow.parse(data); ``` +--- + +## Flow + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Machine name | +| **label** | `string` | ✅ | Flow label | +| **description** | `string` | optional | | +| **successMessage** | `string` | optional | Toast shown when a screen flow completes (defaults to a generic "Done"). | +| **errorMessage** | `string` | optional | Toast shown when a screen flow fails (defaults to the raw error). | +| **version** | `integer` | optional | Version number | +| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional | Deployment status | +| **template** | `boolean` | optional | Is logic template (Subflow) | +| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | ✅ | Flow type | +| **variables** | `Object[]` | optional | Flow variables | +| **nodes** | `Object[]` | ✅ | Flow nodes | +| **edges** | `Object[]` | ✅ | Flow connections | +| **active** | `boolean` | optional | Is active (Deprecated: use status) | +| **runAs** | `Enum<'system' \| 'user'>` | optional | Execution identity for the run: system = elevated (bypasses RLS), user = the triggering user (RLS-respecting). A schedule-triggered run has no trigger user, so under user it runs UNSCOPED (elevated) — declare system to make that explicit. | +| **errorHandling** | `Object` | optional | Flow-level error handling configuration | +| **protection** | `Object` | optional | Package author protection block — lock policy for this flow. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + + +--- + +## FlowEdge + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Edge unique ID | +| **source** | `string` | ✅ | Source Node ID | +| **target** | `string` | ✅ | Target Node ID | +| **condition** | `string \| Object` | optional | Predicate (CEL) returning boolean used for branching. | +| **type** | `Enum<'default' \| 'fault' \| 'conditional' \| 'back'>` | optional | Connection type: default (normal flow), fault (error path), conditional (expression-guarded), or back (ADR-0044 declared back-edge — traversed normally at run time, but excluded from DAG cycle validation so a revise/rework loop can re-enter an earlier node) | +| **label** | `string` | optional | Label on the connector | +| **isDefault** | `boolean` | optional | Marks this edge as the default path when no other conditions match | + + --- ## FlowNode @@ -102,3 +152,19 @@ const result = FlowNode.parse(data); --- +## FlowVersionHistory + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **flowName** | `string` | ✅ | Flow machine name | +| **version** | `integer` | ✅ | Version number | +| **definition** | `Object` | ✅ | Complete flow definition snapshot | +| **createdAt** | `string` | ✅ | When this version was created | +| **createdBy** | `string` | optional | User who created this version | +| **changeNote** | `string` | optional | Description of what changed in this version | + + +--- + diff --git a/content/docs/references/automation/index.mdx b/content/docs/references/automation/index.mdx index 90ff0cf051..b8a7de94b8 100644 --- a/content/docs/references/automation/index.mdx +++ b/content/docs/references/automation/index.mdx @@ -8,6 +8,7 @@ This section contains all protocol schemas for the automation layer of ObjectSta + diff --git a/content/docs/references/automation/meta.json b/content/docs/references/automation/meta.json index 986231e842..34625eeb7c 100644 --- a/content/docs/references/automation/meta.json +++ b/content/docs/references/automation/meta.json @@ -4,6 +4,7 @@ "approval", "bpmn-interop", "connector", + "control-flow", "etl", "execution", "flow", diff --git a/content/docs/references/automation/sync.mdx b/content/docs/references/automation/sync.mdx index 589c4b9ca6..0d703ad020 100644 --- a/content/docs/references/automation/sync.mdx +++ b/content/docs/references/automation/sync.mdx @@ -142,13 +142,29 @@ schedule: '0 * * * *' // Hourly ## TypeScript Usage ```typescript -import { DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; -import type { DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; +import { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; +import type { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; // Validate data -const result = DataSourceConfig.parse(data); +const result = DataDestinationConfig.parse(data); ``` +--- + +## DataDestinationConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | optional | ObjectStack object name | +| **connectorInstanceId** | `string` | optional | Connector instance ID | +| **operation** | `Enum<'insert' \| 'update' \| 'upsert' \| 'delete' \| 'sync'>` | ✅ | Sync operation | +| **mapping** | `Record \| Object[]` | optional | Field mappings | +| **externalResource** | `string` | optional | External resource ID | +| **matchKey** | `string[]` | optional | Match key fields | + + --- ## DataSourceConfig diff --git a/content/docs/references/cloud/environment.mdx b/content/docs/references/cloud/environment.mdx index 752b493fa2..d242727795 100644 --- a/content/docs/references/cloud/environment.mdx +++ b/content/docs/references/cloud/environment.mdx @@ -85,7 +85,7 @@ const result = Environment.parse(data); | **hostname** | `string` | optional | Canonical hostname for this environment. UNIQUE. Auto-set on creation; can be overridden for custom domains. | | **consoleUrl** | `string` | optional | Pre-computed admin Console URL for this environment | | **apiBaseUrl** | `string` | optional | Pre-computed REST API base URL for this environment | -| **visibility** | `Enum<'private' \| 'unlisted' \| 'public'>` | ✅ | Public exposure of this environment artifacts (private | unlisted | public). | +| **visibility** | `Enum<'private' \| 'unlisted' \| 'public'>` | ✅ | Public exposure of this environment artifacts (private \| unlisted \| public). | --- diff --git a/content/docs/references/data/external-lookup.mdx b/content/docs/references/data/external-lookup.mdx index 88a1dd9385..06577f05ab 100644 --- a/content/docs/references/data/external-lookup.mdx +++ b/content/docs/references/data/external-lookup.mdx @@ -52,8 +52,8 @@ Similar to Salesforce External Objects for real-time data integration. ## TypeScript Usage ```typescript -import { ExternalDataSource } from '@objectstack/spec/data'; -import type { ExternalDataSource } from '@objectstack/spec/data'; +import { ExternalDataSource, ExternalFieldMapping, ExternalLookup } from '@objectstack/spec/data'; +import type { ExternalDataSource, ExternalFieldMapping, ExternalLookup } from '@objectstack/spec/data'; // Validate data const result = ExternalDataSource.parse(data); @@ -76,3 +76,39 @@ const result = ExternalDataSource.parse(data); --- +## ExternalFieldMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **source** | `string` | ✅ | Source field name | +| **target** | `string` | ✅ | Target field name | +| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | +| **defaultValue** | `any` | optional | Default if source is null/undefined | +| **type** | `string` | optional | Field type | +| **readonly** | `boolean` | optional | Read-only field | + + +--- + +## ExternalLookup + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **fieldName** | `string` | ✅ | Field name | +| **dataSource** | `Object` | ✅ | External data source | +| **query** | `Object` | ✅ | Query configuration | +| **fieldMappings** | `Object[]` | ✅ | Field mappings | +| **caching** | `Object` | optional | Caching configuration | +| **fallback** | `Object` | optional | Fallback configuration | +| **rateLimit** | `Object` | optional | Rate limiting | +| **retry** | `Object` | optional | Retry configuration with exponential backoff | +| **transform** | `Object` | optional | Request/response transformation pipeline | +| **pagination** | `Object` | optional | Pagination configuration for external data | + + +--- + diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx index 6ab68ff49e..6a41eb6fed 100644 --- a/content/docs/references/data/field.mdx +++ b/content/docs/references/data/field.mdx @@ -14,8 +14,8 @@ Field Type Enum ## TypeScript Usage ```typescript -import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, FieldType, FileAttachmentConfig, LocationCoordinates, VectorConfig } from '@objectstack/spec/data'; -import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, FieldType, FileAttachmentConfig, LocationCoordinates, VectorConfig } from '@objectstack/spec/data'; +import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; +import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; // Validate data const result = Address.parse(data); @@ -89,6 +89,77 @@ const result = Address.parse(data); | **accuracy** | `Object` | optional | Accuracy validation configuration | +--- + +## Field + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Machine name (snake_case) | +| **label** | `string` | optional | Human readable label | +| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'user' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'composite' \| 'repeater' \| 'record' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | ✅ | Field Data Type | +| **description** | `string` | optional | Tooltip/Help text | +| **format** | `string` | optional | Format string (e.g. email, phone) | +| **columnName** | `string` | optional | Physical column name in the target datasource. Defaults to the field key when not set. | +| **required** | `boolean` | optional | Is required | +| **searchable** | `boolean` | optional | Is searchable | +| **multiple** | `boolean` | optional | Allow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image. | +| **unique** | `boolean` | optional | Is unique constraint | +| **defaultValue** | `any` | optional | Default value | +| **maxLength** | `number` | optional | Max character length | +| **minLength** | `number` | optional | Min character length | +| **precision** | `number` | optional | Total digits | +| **scale** | `number` | optional | Decimal places | +| **min** | `number` | optional | Minimum value | +| **max** | `number` | optional | Maximum value | +| **options** | `Object[]` | optional | Static options for select/multiselect | +| **reference** | `string` | optional | Target object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. | +| **referenceFilters** | `string[]` | optional | Filters applied to lookup dialogs (e.g. "active = true") | +| **deleteBehavior** | `Enum<'set_null' \| 'cascade' \| 'restrict'>` | optional | What happens if referenced record is deleted | +| **inlineEdit** | `boolean \| Enum<'grid' \| 'form'>` | optional | Edit these child records inline within the parent's form (atomic master-detail). true = auto-pick grid/form by child shape; 'grid' = editable line-item grid; 'form' = list + per-row full form. | +| **inlineTitle** | `string` | optional | Title for the inline master-detail grid | +| **inlineColumns** | `any[]` | optional | Explicit columns for the inline grid (derived from the child object when omitted) | +| **inlineAmountField** | `string` | optional | Numeric child field summed for the inline grid total | +| **relatedList** | `boolean \| string` | optional | Show this child collection as a related list on the parent's detail page (read-side mirror of inlineEdit). false = suppress; true/absent = shown (stacked under the shared "Related" tab); 'primary' = core relationship, promoted to its own tab. Prominence intent, not a layout switch (ADR-0085). | +| **relatedListTitle** | `string` | optional | Title for the detail-page related list | +| **relatedListColumns** | `any[]` | optional | Explicit columns for the detail-page related list (derived from the child object when omitted) | +| **displayField** | `string` | optional | Field shown as each candidate's label in the picker/popover (defaults to the referenced object's name/title). | +| **descriptionField** | `string` | optional | Secondary field shown under the label in the quick-select popover. | +| **lookupColumns** | `string \| Object[]` | optional | Explicit columns for the record-picker table; auto-derived from the referenced object when omitted. | +| **lookupPageSize** | `integer` | optional | Rows per page in the record-picker dialog (default 10). | +| **lookupFilters** | `Object[]` | optional | Base filters restricting which records are selectable (e.g. only active). Structured, picker-honoured form of referenceFilters. | +| **dependsOn** | `string \| Object[]` | optional | Declares that this field's available values depend on the value of other field(s) on the same record — the form gates the field until they are set and re-evaluates as they change. For `lookup`/`master_detail` it scopes the candidate query (string = same local/remote key; `{field,param}` when the remote filter key differs — the `{field,param}` form is lookup-only). For `select`/`multiselect`/`radio` the actual per-option rule lives in each option's `visibleWhen`; list the referenced fields here (string form) so the option list gates and refreshes with the parent. | +| **allowCreate** | `boolean` | optional | Allow inline quick-create from the record picker: when no match exists the user can create a record from the typed text (optimistic dataSource.create with the display field). Best for simple objects whose only required field is the display field. | +| **expression** | `string \| Object` | optional | Formula expression (CEL). e.g. F`record.amount * 0.1` | +| **returnType** | `Enum<'number' \| 'text' \| 'boolean' \| 'date'>` | optional | Inferred value type of a formula field (number/text/boolean/date) | +| **summaryOperations** | `Object` | optional | Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted. | +| **language** | `string` | optional | Programming language for syntax highlighting (e.g., javascript, python, sql) | +| **step** | `number` | optional | Step increment for slider (default: 1) | +| **currencyConfig** | `Object` | optional | Configuration for currency field type | +| **dimensions** | `integer` | optional | Vector dimensionality (e.g., 1536 for OpenAI embeddings) | +| **vectorConfig** | `Object` | optional | Configuration for vector field type (AI/ML embeddings) | +| **fileAttachmentConfig** | `Object` | optional | Configuration for file and attachment field types | +| **trackHistory** | `boolean` | optional | Render this field's value changes as human-readable entries on the record activity timeline (ADR-0052 §5b). Opt-in per field. | +| **dependencies** | `string[]` | optional | Array of field names that this field depends on (for formulas, visibility rules, etc.) | +| **group** | `string` | optional | Field group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system") | +| **visibleWhen** | `string \| Object` | optional | Predicate (CEL) — field is shown only when TRUE (else hidden). e.g. P`record.type == 'invoice'` | +| **readonlyWhen** | `string \| Object` | optional | Predicate (CEL) — field is read-only when TRUE. e.g. P`record.status == 'paid'` | +| **requiredWhen** | `string \| Object` | optional | Predicate (CEL) — field is required when TRUE. Canonical name for `conditionalRequired`. | +| **conditionalRequired** | `string \| Object` | optional | Predicate (CEL) — field is required when TRUE. Alias of `requiredWhen`. | +| **widget** | `string` | optional | Form widget override — names a registered field component (resolved as `field:`) to render this field instead of the `type` default. Degrades to the `type` renderer when unregistered. e.g. "object-ref", "filter-condition", "recipient-picker". | +| **hidden** | `boolean` | optional | Hidden from default UI | +| **readonly** | `boolean` | optional | Read-only in UI | +| **requiredPermissions** | `string[]` | optional | [ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate). | +| **system** | `boolean` | optional | Auto-injected system/audit field (e.g. created_at, updated_by, organization_id). Tools that surface system fields separately from author-declared business fields should branch on this flag. | +| **sortable** | `boolean` | optional | Whether field is sortable in list views | +| **inlineHelpText** | `string` | optional | Help text displayed below the field in forms | +| **autonumberFormat** | `string` | optional | Auto-number format: literal text + `{0000}` counter, `{YYYY}`/`{MM}`/`{DD}`/`{YYYYMMDD}` date tokens (business tz), and `{field_name}` interpolation. Counter resets per rendered prefix (e.g. AD`{YYYYMMDD}``{0000}` resets daily). | +| **index** | `boolean` | optional | Create standard database index | +| **externalId** | `boolean` | optional | Is external ID for upsert operations | + + --- ## FieldType @@ -194,6 +265,21 @@ const result = Address.parse(data); | **accuracy** | `number` | optional | Accuracy in meters | +--- + +## SelectOption + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **label** | `string` | ✅ | Display label (human-readable, any case allowed) | +| **value** | `string` | ✅ | Stored value (lowercase machine identifier) | +| **color** | `string` | optional | Color code for badges/charts | +| **default** | `boolean` | optional | Is default option | +| **visibleWhen** | `string \| Object` | optional | Per-option visibility predicate (CEL) — option is offered only when TRUE (else omitted). Same env as field visibleWhen (record + current_user). e.g. P`record.country == 'cn'` or P`'admin' in current_user.positions` | + + --- ## VectorConfig diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx index 715b35ab26..28d55aadde 100644 --- a/content/docs/references/data/object.mdx +++ b/content/docs/references/data/object.mdx @@ -14,8 +14,8 @@ API Operations Enum ## TypeScript Usage ```typescript -import { ApiMethod, Index, Lifecycle, LifecycleClass, ObjectAccessConfig, ObjectCapabilities, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; -import type { ApiMethod, Index, Lifecycle, LifecycleClass, ObjectAccessConfig, ObjectCapabilities, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; +import { ApiMethod, Index, Lifecycle, LifecycleClass, Object, ObjectAccessConfig, ObjectCapabilities, ObjectExtension, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; +import type { ApiMethod, Index, Lifecycle, LifecycleClass, Object, ObjectAccessConfig, ObjectCapabilities, ObjectExtension, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; // Validate data const result = ApiMethod.parse(data); @@ -66,7 +66,7 @@ const result = ApiMethod.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **class** | `Enum<'record' \| 'audit' \| 'telemetry' \| 'transient' \| 'event'>` | ✅ | Persistence contract: record (business truth, permanent) | audit (compliance ledger) | telemetry (high-freq log) | transient (ephemeral state) | event (bus messages). | +| **class** | `Enum<'record' \| 'audit' \| 'telemetry' \| 'transient' \| 'event'>` | ✅ | Persistence contract: record (business truth, permanent) \| audit (compliance ledger) \| telemetry (high-freq log) \| transient (ephemeral state) \| event (bus messages). | | **retention** | `Object` | optional | Age-based retention window enforced by the LifecycleService Reaper. | | **ttl** | `Object` | optional | Per-row TTL auto-expiry (transient/event classes). | | **storage** | `Object` | optional | Physical storage strategy for high-frequency telemetry (LifecycleService Rotator). | @@ -87,6 +87,64 @@ const result = ApiMethod.parse(data); * `event` +--- + +## Object + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Machine unique key (snake_case). Immutable. | +| **label** | `string` | optional | Human readable singular label (e.g. "Account") | +| **pluralLabel** | `string` | optional | Human readable plural label (e.g. "Accounts") | +| **description** | `string` | optional | Developer documentation / description | +| **icon** | `string` | optional | Icon name (Lucide/Material) for UI representation | +| **tags** | `string[]` | optional | Categorization tags (e.g. "sales", "system", "reference") | +| **active** | `boolean` | optional | Is the object active and usable | +| **isSystem** | `boolean` | optional | Is system object (protected from deletion) | +| **abstract** | `boolean` | optional | Is abstract base object (cannot be instantiated) | +| **managedBy** | `Enum<'platform' \| 'config' \| 'system' \| 'append-only' \| 'better-auth'>` | optional | Lifecycle bucket — platform (user CRUD) \| config (admin authored) \| system (engine-managed) \| append-only (audit) \| better-auth (identity). UI clients honour the resolved affordance matrix. | +| **userActions** | `Object` | optional | Per-object override of the resolved CRUD affordance matrix. | +| **systemFields** | `boolean \| Object` | optional | Opt out of, or selectively disable, registry-level system-field auto-injection. | +| **datasource** | `string` | optional | Target Datasource ID. "default" is the primary DB. | +| **external** | `Object` | optional | Remote table binding for federated (external) objects. | +| **fields** | `Record` | ✅ | Field definitions map. Keys must be snake_case identifiers. | +| **indexes** | `Object[]` | optional | Database performance indexes | +| **fieldGroups** | `Object[]` | optional | Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema. | +| **tenancy** | `Object` | optional | Multi-tenancy configuration for SaaS applications | +| **access** | `Object` | optional | [ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default). | +| **requiredPermissions** | `string[] \| Object` | optional | [ADR-0066 D3/⑤] Capabilities required to access this object (AND-gate) — `string[]` gates all CRUD, or a `{read,create,update,delete}` map gates per operation. | +| **softDelete** | `Object` | optional | Soft delete (trash/recycle bin) configuration | +| **versioning** | `Object` | optional | Record versioning and history tracking configuration | +| **lifecycle** | `Object` | optional | Data lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService. | +| **validations** | `[__schema0](./__schema0)[]` | optional | Object-level validation rules | +| **activityMilestones** | `Object[]` | optional | Declarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2). | +| **nameField** | `string` | optional | [ADR-0079] Canonical primary title field — the stored field used as the record display name (e.g. "name", "title"). Pairs with recordName. | +| **displayNameField** | `string` | optional | [DEPRECATED → nameField] Field to use as the record display name (e.g., "name", "title"). Accepted as an alias for nameField. | +| **recordName** | `Object` | optional | Record name generation configuration (Salesforce pattern) | +| **titleFormat** | `string \| Object` | optional | [DEPRECATED → nameField (ADR-0079)] Render-only title template; the server cannot return or query it, and an explicit nameField now takes precedence. Migrate a single-field title to nameField, a composite to a formula field designated as nameField. | +| **highlightFields** | `string[]` | optional | [ADR-0085] Ordered most-important fields; first entry wins where only one fits. Drives default columns, cards, previews, detail highlight strip. Renamed from compactLayout. | +| **stageField** | `string \| boolean` | optional | [ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed. | +| **listViews** | `Record` | optional | Built-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047) | +| **searchableFields** | `string[]` | optional | Fields the `$search` query matches against (ADR-0061). Canonical default for the record picker, list quick-search and global search; views may narrow it. When unset, search auto-defaults to the name/title field plus short-text fields. | +| **search** | `Object` | optional | Search engine configuration | +| **enable** | `Object` | optional | Enabled system features modules | +| **sharingModel** | `Enum<'private' \| 'public_read' \| 'public_read_write' \| 'controlled_by_parent'>` | optional | Org-Wide Default record visibility (OWD) for INTERNAL users. Canonical four only (legacy aliases removed, ADR-0090 D4): private (owner-only) \| public_read (everyone reads, owner writes) \| public_read_write (everyone reads+writes) \| controlled_by_parent (derived from the master record). A CUSTOM object that omits this resolves to private at runtime (ADR-0090 D1). | +| **externalSharingModel** | `Enum<'private' \| 'public_read' \| 'public_read_write' \| 'controlled_by_parent'>` | optional | [ADR-0090 D11] OWD for external (portal/partner) principals. Defaults to private; must be <= sharingModel in openness. | +| **publicSharing** | `Object` | optional | Public share-link policy (Notion/Figma-style link sharing) | +| **keyPrefix** | `string` | optional | Short prefix for record IDs (e.g., "001" for Account) | +| **actions** | `Object[]` | optional | Actions associated with this object (auto-populated from top-level actions via objectName) | +| **protection** | `Object` | optional | Package author protection block — lock policy for this object. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + + --- ## ObjectAccessConfig @@ -95,7 +153,7 @@ const result = ApiMethod.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **default** | `Enum<'public' \| 'private'>` | ✅ | Default exposure posture: public (covered by wildcard grants) | private (needs explicit grant; exempt from wildcard RLS). | +| **default** | `Enum<'public' \| 'private'>` | ✅ | Default exposure posture: public (covered by wildcard grants) \| private (needs explicit grant; exempt from wildcard RLS). | --- @@ -118,6 +176,24 @@ const result = ApiMethod.parse(data); | **clone** | `boolean` | ✅ | Allow record deep cloning | +--- + +## ObjectExtension + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **extend** | `string` | ✅ | Target object name (FQN) to extend | +| **fields** | `Record` | optional | Fields to add/override | +| **label** | `string` | optional | Override label for the extended object | +| **pluralLabel** | `string` | optional | Override plural label for the extended object | +| **description** | `string` | optional | Override description for the extended object | +| **validations** | `[__schema0](./__schema0)[]` | optional | Additional validation rules to merge into the target object | +| **indexes** | `Object[]` | optional | Additional indexes to merge into the target object | +| **priority** | `integer` | optional | Merge priority (higher = applied later) | + + --- ## ObjectExternalBinding diff --git a/content/docs/references/data/validation.mdx b/content/docs/references/data/validation.mdx index 378cb14a6e..f40770416d 100644 --- a/content/docs/references/data/validation.mdx +++ b/content/docs/references/data/validation.mdx @@ -108,13 +108,58 @@ severity: 'error' ## TypeScript Usage ```typescript -import { FormatValidation, JSONValidation, StateMachineValidation } from '@objectstack/spec/data'; -import type { FormatValidation, JSONValidation, StateMachineValidation } from '@objectstack/spec/data'; +import { ConditionalValidation, CrossFieldValidation, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, ValidationRule } from '@objectstack/spec/data'; +import type { ConditionalValidation, CrossFieldValidation, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, ValidationRule } from '@objectstack/spec/data'; // Validate data -const result = FormatValidation.parse(data); +const result = ConditionalValidation.parse(data); ``` +--- + +## ConditionalValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **when** | `string \| Object` | ✅ | Predicate (CEL). e.g. P`record.type == 'enterprise'` | +| **then** | `Object \| Object \| Object \| Object \| Object \| [#](./#)` | ✅ | Validation rule to apply when condition is true | +| **otherwise** | `Object \| Object \| Object \| Object \| Object \| [#](./#)` | optional | Validation rule to apply when condition is false | + + +--- + +## CrossFieldValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **condition** | `string \| Object` | ✅ | Predicate (CEL) comparing fields. e.g. P`record.end_date > record.start_date` | +| **fields** | `string[]` | ✅ | Fields involved in the validation | + + --- ## FormatValidation @@ -160,6 +205,27 @@ const result = FormatValidation.parse(data); | **schema** | `Record` | ✅ | JSON Schema object definition | +--- + +## ScriptValidation + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **condition** | `string \| Object` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0` | + + --- ## StateMachineValidation @@ -184,3 +250,151 @@ const result = FormatValidation.parse(data); --- +## ValidationRule + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +**Type:** `script` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **condition** | `string \| Object` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0` | + +--- + +#### Option 2 + +**Type:** `state_machine` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | State field (e.g. status) | +| **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | + +--- + +#### Option 3 + +**Type:** `format` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | | +| **regex** | `string` | optional | | +| **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | + +--- + +#### Option 4 + +**Type:** `cross_field` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **condition** | `string \| Object` | ✅ | Predicate (CEL) comparing fields. e.g. P`record.end_date > record.start_date` | +| **fields** | `string[]` | ✅ | Fields involved in the validation | + +--- + +#### Option 5 + +**Type:** `json_schema` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **field** | `string` | ✅ | JSON field to validate | +| **schema** | `Record` | ✅ | JSON Schema object definition | + +--- + +#### Option 6 + +**Type:** `conditional` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label for the rule listing | +| **description** | `string` | optional | Administrative notes explaining the business reason | +| **active** | `boolean` | optional | | +| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | +| **priority** | `integer` | optional | Execution priority (lower runs first, default: 100) | +| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | +| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | +| **message** | `string` | ✅ | Error message to display to the user | +| **type** | `string` | ✅ | | +| **when** | `string \| Object` | ✅ | Predicate (CEL). e.g. P`record.type == 'enterprise'` | +| **then** | `[#](./#)` | ✅ | Validation rule to apply when condition is true | +| **otherwise** | `[#](./#)` | optional | Validation rule to apply when condition is false | + +--- + + +--- + diff --git a/content/docs/references/integration/connector-auth.mdx b/content/docs/references/integration/connector-auth.mdx new file mode 100644 index 0000000000..c7d3f2fbb3 --- /dev/null +++ b/content/docs/references/integration/connector-auth.mdx @@ -0,0 +1,136 @@ +--- +title: Connector Auth +description: Connector Auth protocol schemas +--- + +{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} + + +**Source:** `packages/spec/src/integration/connector-auth.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConnectorInstanceAPIKeyAuth, ConnectorInstanceAuth, ConnectorInstanceBasicAuth, ConnectorInstanceBearerAuth, ConnectorInstanceNoAuth } from '@objectstack/spec/integration'; +import type { ConnectorInstanceAPIKeyAuth, ConnectorInstanceAuth, ConnectorInstanceBasicAuth, ConnectorInstanceBearerAuth, ConnectorInstanceNoAuth } from '@objectstack/spec/integration'; + +// Validate data +const result = ConnectorInstanceAPIKeyAuth.parse(data); +``` + +--- + +## ConnectorInstanceAPIKeyAuth + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **credentialRef** | `string` | ✅ | Secrets-layer reference resolved to the API key at materialization. Never an inline key. | +| **headerName** | `string` | optional | HTTP header carrying the key (default X-API-Key). | +| **paramName** | `string` | optional | Query parameter carrying the key (alternative to header). | + + +--- + +## ConnectorInstanceAuth + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +**Type:** `none` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | + +--- + +#### Option 2 + +**Type:** `bearer` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **credentialRef** | `string` | ✅ | Secrets-layer reference (e.g. an env-var name in the open tier) resolved to the bearer token at materialization. Never an inline token. | + +--- + +#### Option 3 + +**Type:** `api-key` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **credentialRef** | `string` | ✅ | Secrets-layer reference resolved to the API key at materialization. Never an inline key. | +| **headerName** | `string` | optional | HTTP header carrying the key (default X-API-Key). | +| **paramName** | `string` | optional | Query parameter carrying the key (alternative to header). | + +--- + +#### Option 4 + +**Type:** `basic` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **username** | `string` | ✅ | Username (not a secret; safe to keep in metadata). | +| **credentialRef** | `string` | ✅ | Secrets-layer reference resolved to the password at materialization. Never an inline password. | + +--- + + +--- + +## ConnectorInstanceBasicAuth + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **username** | `string` | ✅ | Username (not a secret; safe to keep in metadata). | +| **credentialRef** | `string` | ✅ | Secrets-layer reference resolved to the password at materialization. Never an inline password. | + + +--- + +## ConnectorInstanceBearerAuth + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **credentialRef** | `string` | ✅ | Secrets-layer reference (e.g. an env-var name in the open tier) resolved to the bearer token at materialization. Never an inline token. | + + +--- + +## ConnectorInstanceNoAuth + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | + + +--- + diff --git a/content/docs/references/integration/connector.mdx b/content/docs/references/integration/connector.mdx index 49016c4042..9612684dfd 100644 --- a/content/docs/references/integration/connector.mdx +++ b/content/docs/references/integration/connector.mdx @@ -31,6 +31,42 @@ This protocol supports multiple authentication strategies, bidirectional sync, field mapping, webhooks, and comprehensive rate limiting. +## Runtime contract — descriptor vs. registered connector (#2612) + +This schema serves TWO distinct consumers; do not conflate them: + +1. **Runtime registration (plugin-only).** The automation engine's connector + +registry — what `GET /connectors` lists and the `connector_action` flow + +node dispatches — is populated exclusively by plugins calling + +`engine.registerConnector(def, handlers)` with a handler per declared + +action (ADR-0018 §Addendum). The definition is validated against this + +schema at registration. + +2. **Declarative `connectors:` stack entries (catalog descriptors).** Stack + +metadata validated against this schema is registered as kind 'connector' + +for discovery/documentation/marketplace purposes only — it never reaches + +the runtime registry, because an action here carries no execution binding + +(deliberately: ADR-0023 rejected re-inventing OpenAPI inside this schema). + +The automation service warns at boot about declared entries with `actions` + +that lack a same-name runtime registration; mark deliberate catalog-only + +entries with `enabled: false`. Provider-bound declarative instances that + +a generic executor (connector-openapi / connector-mcp) materializes at + +boot are tracked in #2977 (ADR-0096). + Authentication is now imported from the canonical auth/config.zod.ts. ## When to Use This Layer @@ -102,8 +138,8 @@ Authentication is now imported from the canonical auth/config.zod.ts. ## TypeScript Usage ```typescript -import { CircuitBreakerConfig, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; -import type { CircuitBreakerConfig, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; +import { CircuitBreakerConfig, Connector, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; +import type { CircuitBreakerConfig, Connector, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; // Validate data const result = CircuitBreakerConfig.parse(data); @@ -127,6 +163,39 @@ Circuit breaker configuration | **fallbackStrategy** | `Enum<'cache' \| 'default_value' \| 'error' \| 'queue'>` | optional | Fallback strategy when circuit is open | +--- + +## Connector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `Enum<'saas' \| 'database' \| 'file_storage' \| 'message_queue' \| 'api' \| 'custom'>` | ✅ | Connector type | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `string` | optional | Generic-executor key that materializes this declarative entry at boot (e.g. openapi/mcp/rest). Omit for a catalog-only descriptor. Unknown provider ⇒ hard boot error (ADR-0096). | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | + + --- ## ConnectorAction @@ -201,6 +270,58 @@ Connector type * `custom` +--- + +## DataSyncConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **strategy** | `Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>` | optional | Synchronization strategy | +| **direction** | `Enum<'import' \| 'export' \| 'bidirectional'>` | optional | Sync direction | +| **schedule** | `string \| Object` | optional | Cron expression for scheduled sync — cron`0 */15 * * *` | +| **realtimeSync** | `boolean` | optional | Enable real-time sync | +| **timestampField** | `string` | optional | Field to track last modification time | +| **conflictResolution** | `Enum<'source_wins' \| 'target_wins' \| 'latest_wins' \| 'manual'>` | optional | Conflict resolution strategy | +| **batchSize** | `number` | optional | Records per batch | +| **deleteMode** | `Enum<'hard_delete' \| 'soft_delete' \| 'ignore'>` | optional | Delete handling mode | +| **filters** | `Record` | optional | Filter criteria for selective sync | + + +--- + +## DeclarativeConnectorEntry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `Enum<'saas' \| 'database' \| 'file_storage' \| 'message_queue' \| 'api' \| 'custom'>` | ✅ | Connector type | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `string` | optional | Generic-executor key that materializes this declarative entry at boot (e.g. openapi/mcp/rest). Omit for a catalog-only descriptor. Unknown provider ⇒ hard boot error (ADR-0096). | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | + + --- ## ErrorCategory diff --git a/content/docs/references/integration/mapping.mdx b/content/docs/references/integration/mapping.mdx new file mode 100644 index 0000000000..1174c93b80 --- /dev/null +++ b/content/docs/references/integration/mapping.mdx @@ -0,0 +1,40 @@ +--- +title: Mapping +description: Mapping protocol schemas +--- + +{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} + + +**Source:** `packages/spec/src/integration/mapping.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldMapping } from '@objectstack/spec/integration'; +import type { FieldMapping } from '@objectstack/spec/integration'; + +// Validate data +const result = FieldMapping.parse(data); +``` + +--- + +## FieldMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **source** | `string` | ✅ | Source field name | +| **target** | `string` | ✅ | Target field name | +| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | +| **defaultValue** | `any` | optional | Default if source is null/undefined | +| **dataType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'json' \| 'array'>` | optional | Target data type | +| **required** | `boolean` | optional | Field is required | +| **syncMode** | `Enum<'read_only' \| 'write_only' \| 'bidirectional'>` | optional | Sync mode | + + +--- + diff --git a/content/docs/references/integration/meta.json b/content/docs/references/integration/meta.json index 0fcfd87da2..ee2b6fb799 100644 --- a/content/docs/references/integration/meta.json +++ b/content/docs/references/integration/meta.json @@ -2,7 +2,9 @@ "title": "Integration Protocol", "pages": [ "connector", + "connector-auth", "http", + "mapping", "message-queue", "misc", "object-storage", diff --git a/content/docs/references/integration/misc.mdx b/content/docs/references/integration/misc.mdx index 4b83166daa..25f165bd13 100644 --- a/content/docs/references/integration/misc.mdx +++ b/content/docs/references/integration/misc.mdx @@ -12,8 +12,8 @@ description: Misc protocol schemas ## TypeScript Usage ```typescript -import { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabasePoolConfig, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubIssueTracking, GitHubProvider, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, ProducerConfig, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; -import type { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabasePoolConfig, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubIssueTracking, GitHubProvider, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, ProducerConfig, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; +import { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; +import type { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; // Validate data const result = AckMode.parse(data); @@ -79,6 +79,47 @@ Message acknowledgment mode | **pollIntervalMs** | `number` | ✅ | CDC polling interval in ms | +--- + +## DatabaseConnector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `string` | ✅ | | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `Enum<'postgresql' \| 'mysql' \| 'mariadb' \| 'mssql' \| 'oracle' \| 'mongodb' \| 'redis' \| 'cassandra' \| 'snowflake' \| 'bigquery' \| 'redshift' \| 'custom'>` | ✅ | Database provider type | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | +| **connectionConfig** | `Object` | ✅ | Database connection configuration | +| **poolConfig** | `Object` | optional | Connection pool configuration | +| **sslConfig** | `Object` | optional | SSL/TLS configuration | +| **tables** | `Object[]` | ✅ | Tables to sync | +| **cdcConfig** | `Object` | optional | CDC configuration | +| **readReplicaConfig** | `Object` | optional | Read replica configuration | +| **queryTimeoutMs** | `number` | optional | Query timeout in ms | +| **enableQueryLogging** | `boolean` | optional | Enable SQL query logging | + + --- ## DatabasePoolConfig @@ -96,6 +137,24 @@ Message acknowledgment mode | **testOnBorrow** | `boolean` | ✅ | Test connection before use | +--- + +## DatabaseTable + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Table name in ObjectStack (snake_case) | +| **label** | `string` | ✅ | Display label | +| **schema** | `string` | optional | Database schema name | +| **tableName** | `string` | ✅ | Actual table name in database | +| **primaryKey** | `string` | ✅ | Primary key column | +| **enabled** | `boolean` | optional | Enable sync for this table | +| **fieldMappings** | `Object[]` | optional | Table-specific field mappings | +| **whereClause** | `string` | optional | SQL WHERE clause for filtering | + + --- ## DeliveryGuarantee @@ -227,6 +286,49 @@ File access pattern | **customMetadata** | `Record` | optional | Custom metadata key-value pairs | +--- + +## FileStorageConnector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `string` | ✅ | | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'dropbox' \| 'box' \| 'onedrive' \| 'google_drive' \| 'sharepoint' \| 'ftp' \| 'local' \| 'custom'>` | ✅ | File storage provider type | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | +| **storageConfig** | `Object` | optional | Storage configuration | +| **buckets** | `Object[]` | ✅ | Buckets/containers to sync | +| **metadataConfig** | `Object` | optional | Metadata extraction configuration | +| **multipartConfig** | `Object` | optional | Multipart upload configuration | +| **versioningConfig** | `Object` | optional | File versioning configuration | +| **encryption** | `Object` | optional | Encryption configuration | +| **lifecyclePolicy** | `Object` | optional | Lifecycle policy | +| **contentProcessing** | `Object` | optional | Content processing configuration | +| **bufferSize** | `number` | optional | Buffer size in bytes | +| **transferAcceleration** | `boolean` | optional | Enable transfer acceleration | + + --- ## FileStorageProvider @@ -292,6 +394,48 @@ File storage provider type | **useConventionalCommits** | `boolean` | ✅ | Use conventional commits format | +--- + +## GitHubConnector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `string` | ✅ | | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `Enum<'github' \| 'github_enterprise'>` | ✅ | GitHub provider | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | +| **baseUrl** | `string` | optional | GitHub API base URL | +| **repositories** | `Object[]` | ✅ | Repositories to manage | +| **commitConfig** | `Object` | optional | Commit configuration | +| **pullRequestConfig** | `Object` | optional | Pull request configuration | +| **workflows** | `Object[]` | optional | GitHub Actions workflows | +| **releaseConfig** | `Object` | optional | Release configuration | +| **issueTracking** | `Object` | optional | Issue tracking configuration | +| **enableWebhooks** | `boolean` | optional | Enable GitHub webhooks | +| **webhookEvents** | `Enum<'push' \| 'pull_request' \| 'issues' \| 'issue_comment' \| 'release' \| 'workflow_run' \| 'deployment' \| 'deployment_status' \| 'check_run' \| 'check_suite' \| 'status'>[]` | optional | Webhook events to subscribe to | + + --- ## GitHubIssueTracking @@ -319,6 +463,23 @@ GitHub provider type * `github_enterprise` +--- + +## GitHubPullRequestConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **titleTemplate** | `string \| Object` | optional | PR title template — supports `{{var}`} interpolation | +| **bodyTemplate** | `string \| Object` | optional | PR body template — supports `{{var}`} interpolation | +| **defaultReviewers** | `string[]` | optional | Default reviewers (usernames) | +| **defaultAssignees** | `string[]` | optional | Default assignees (usernames) | +| **defaultLabels** | `string[]` | optional | Default labels | +| **draftByDefault** | `boolean` | optional | Create draft PRs by default | +| **deleteHeadBranch** | `boolean` | optional | Delete head branch after merge | + + --- ## GitHubReleaseConfig @@ -366,6 +527,48 @@ GitHub provider type | **autoDeployPreview** | `boolean` | ✅ | Auto-deploy preview branches | +--- + +## MessageQueueConnector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `string` | ✅ | | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `Enum<'rabbitmq' \| 'kafka' \| 'redis_pubsub' \| 'redis_streams' \| 'aws_sqs' \| 'aws_sns' \| 'google_pubsub' \| 'azure_service_bus' \| 'azure_event_hubs' \| 'nats' \| 'pulsar' \| 'activemq' \| 'custom'>` | ✅ | Message queue provider type | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | +| **brokerConfig** | `Object` | ✅ | Broker connection configuration | +| **topics** | `Object[]` | ✅ | Topics/queues to sync | +| **deliveryGuarantee** | `Enum<'at_most_once' \| 'at_least_once' \| 'exactly_once'>` | optional | Message delivery guarantee | +| **sslConfig** | `Object` | optional | SSL/TLS configuration | +| **saslConfig** | `Object` | optional | SASL authentication configuration | +| **schemaRegistry** | `Object` | optional | Schema registry configuration | +| **preserveOrder** | `boolean` | optional | Preserve message ordering | +| **enableMetrics** | `boolean` | optional | Enable message queue metrics | +| **enableTracing** | `boolean` | optional | Enable distributed tracing | + + --- ## ProducerConfig @@ -385,6 +588,64 @@ GitHub provider type | **transactionTimeoutMs** | `number` | optional | Transaction timeout in ms | +--- + +## SaasConnector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `string` | ✅ | | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `Enum<'salesforce' \| 'hubspot' \| 'stripe' \| 'shopify' \| 'zendesk' \| 'intercom' \| 'mailchimp' \| 'slack' \| 'microsoft_dynamics' \| 'servicenow' \| 'netsuite' \| 'custom'>` | ✅ | SaaS provider type | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | +| **baseUrl** | `string` | ✅ | API base URL | +| **apiVersion** | `Object` | optional | API version configuration | +| **objectTypes** | `Object[]` | ✅ | Syncable object types | +| **oauthSettings** | `Object` | optional | OAuth-specific configuration | +| **paginationConfig** | `Object` | optional | Pagination configuration | +| **sandboxConfig** | `Object` | optional | Sandbox environment configuration | +| **customHeaders** | `Record` | optional | Custom HTTP headers for all requests | + + +--- + +## SaasObjectType + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Object type name (snake_case) | +| **label** | `string` | ✅ | Display label | +| **apiName** | `string` | ✅ | API name in external system | +| **enabled** | `boolean` | optional | Enable sync for this object | +| **supportsCreate** | `boolean` | optional | Supports record creation | +| **supportsUpdate** | `boolean` | optional | Supports record updates | +| **supportsDelete** | `boolean` | optional | Supports record deletion | +| **fieldMappings** | `Object[]` | optional | Object-specific field mappings | + + --- ## SaasProvider @@ -463,6 +724,45 @@ SaaS provider type | **messageFilter** | `Object` | optional | Message filter criteria | +--- + +## VercelConnector + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique connector identifier | +| **label** | `string` | ✅ | Display label | +| **type** | `string` | ✅ | | +| **description** | `string` | optional | Connector description | +| **icon** | `string` | optional | Icon identifier | +| **authentication** | `Object \| Object \| Object \| Object \| Object` | optional | Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead. | +| **provider** | `Enum<'vercel'>` | ✅ | Vercel provider | +| **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi). Requires `provider`. | +| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0096). | +| **actions** | `Object[]` | optional | | +| **triggers** | `Object[]` | optional | | +| **syncConfig** | `Object` | optional | Data sync configuration | +| **fieldMappings** | `Object[]` | optional | Field mapping rules | +| **webhooks** | `Object[]` | optional | Webhook configurations | +| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | +| **retryConfig** | `Object` | optional | Retry configuration | +| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | +| **requestTimeoutMs** | `number` | optional | Request timeout in ms | +| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | +| **enabled** | `boolean` | optional | Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612). | +| **errorMapping** | `Object` | optional | Error mapping configuration | +| **health** | `Object` | optional | Health and resilience configuration | +| **metadata** | `Record` | optional | Custom connector metadata | +| **baseUrl** | `string` | optional | Vercel API base URL | +| **team** | `Object` | optional | Vercel team configuration | +| **projects** | `Object[]` | ✅ | Vercel projects | +| **monitoring** | `Object` | optional | Monitoring configuration | +| **enableWebhooks** | `boolean` | optional | Enable Vercel webhooks | +| **webhookEvents** | `Enum<'deployment.created' \| 'deployment.succeeded' \| 'deployment.failed' \| 'deployment.ready' \| 'deployment.error' \| 'deployment.canceled' \| 'deployment-checks-completed' \| 'deployment-prepared' \| 'project.created' \| 'project.removed'>[]` | optional | Webhook events to subscribe to | + + --- ## VercelFramework diff --git a/content/docs/references/kernel/feature.mdx b/content/docs/references/kernel/feature.mdx index acefce45ca..885c98a3d9 100644 --- a/content/docs/references/kernel/feature.mdx +++ b/content/docs/references/kernel/feature.mdx @@ -14,13 +14,31 @@ Feature Rollout Strategy ## TypeScript Usage ```typescript -import { FeatureStrategy } from '@objectstack/spec/kernel'; -import type { FeatureStrategy } from '@objectstack/spec/kernel'; +import { FeatureFlag, FeatureStrategy } from '@objectstack/spec/kernel'; +import type { FeatureFlag, FeatureStrategy } from '@objectstack/spec/kernel'; // Validate data -const result = FeatureStrategy.parse(data); +const result = FeatureFlag.parse(data); ``` +--- + +## FeatureFlag + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Feature key (snake_case) | +| **label** | `string` | optional | Display label | +| **description** | `string` | optional | | +| **enabled** | `boolean` | optional | Is globally enabled | +| **strategy** | `Enum<'boolean' \| 'percentage' \| 'user_list' \| 'group' \| 'custom'>` | optional | | +| **conditions** | `Object` | optional | | +| **environment** | `Enum<'dev' \| 'staging' \| 'prod' \| 'all'>` | optional | Environment validity | +| **expiresAt** | `string` | optional | Feature flag expiration date | + + --- ## FeatureStrategy diff --git a/content/docs/references/kernel/manifest.mdx b/content/docs/references/kernel/manifest.mdx index bfb745871a..59b056571e 100644 --- a/content/docs/references/kernel/manifest.mdx +++ b/content/docs/references/kernel/manifest.mdx @@ -32,13 +32,47 @@ PluginPermissionEnforcer. ## TypeScript Usage ```typescript -import { ManifestPermissions, PluginEngines, PluginIntegrity, PluginPackaging, PluginPermissions, PluginRuntime } from '@objectstack/spec/kernel'; -import type { ManifestPermissions, PluginEngines, PluginIntegrity, PluginPackaging, PluginPermissions, PluginRuntime } from '@objectstack/spec/kernel'; +import { Manifest, ManifestPermissions, PluginEngines, PluginIntegrity, PluginPackaging, PluginPermissions, PluginRuntime } from '@objectstack/spec/kernel'; +import type { Manifest, ManifestPermissions, PluginEngines, PluginIntegrity, PluginPackaging, PluginPermissions, PluginRuntime } from '@objectstack/spec/kernel'; // Validate data -const result = ManifestPermissions.parse(data); +const result = Manifest.parse(data); ``` +--- + +## Manifest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique package identifier (reverse domain style) | +| **namespace** | `string` | optional | Short namespace identifier; also the mandatory prefix of every object name (e.g. "todo" → object names "todo_task", "todo_project") | +| **defaultDatasource** | `string` | optional | Default datasource for all objects in this package | +| **version** | `string` | ✅ | Package version (semantic versioning) | +| **type** | `Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| 'module' \| 'gateway' \| 'adapter'>` | ✅ | Type of package | +| **scope** | `Enum<'cloud' \| 'system' \| 'project'>` | optional | Deployment scope: cloud \| system \| project | +| **name** | `string` | ✅ | Human-readable package name | +| **description** | `string` | optional | Package description | +| **permissions** | `string[] \| Object` | optional | Required permissions: legacy string[] or structured plugin block (ADR-0025 §3.2) | +| **objects** | `string[]` | optional | Glob patterns for ObjectQL schemas files | +| **datasources** | `string[]` | optional | Glob patterns for Datasource definitions | +| **dependencies** | `Record` | optional | Package dependencies | +| **configuration** | `Object` | optional | Plugin configuration settings | +| **contributes** | `Object` | optional | Platform contributions | +| **data** | `Object[]` | optional | Initial seed data (prefer top-level data field) | +| **capabilities** | `Object` | optional | Plugin capability declarations for interoperability | +| **extensions** | `Record` | optional | Extension points and contributions | +| **navigationContributions** | `Object[]` | optional | Navigation items this package contributes into apps owned by other packages | +| **loading** | `Object` | optional | Plugin loading and runtime behavior configuration | +| **engine** | `Object` | optional | Platform compatibility requirements (legacy; superseded by `engines`) | +| **engines** | `Object` | optional | Plugin compatibility ranges (ADR-0025 §3.2; supersedes `engine`) | +| **runtime** | `Enum<'node' \| 'sandbox' \| 'worker'>` | optional | Plugin trust tier (ADR-0025 §3.6) | +| **packaging** | `Enum<'bundled' \| 'manifest-deps'>` | optional | Dependency packaging strategy (ADR-0025 §3.3) | +| **integrity** | `Record` | optional | Per-file content digests of the plugin artifact (ADR-0025 §3.2) | + + --- ## ManifestPermissions diff --git a/content/docs/references/kernel/metadata-persistence.mdx b/content/docs/references/kernel/metadata-persistence.mdx index 119ae25ebd..5ca6808c19 100644 --- a/content/docs/references/kernel/metadata-persistence.mdx +++ b/content/docs/references/kernel/metadata-persistence.mdx @@ -12,8 +12,8 @@ description: Metadata Persistence protocol schemas ## TypeScript Usage ```typescript -import { MetadataCollectionInfo, MetadataFormat, MetadataImportOptions, MetadataLoadResult, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; -import type { MetadataCollectionInfo, MetadataFormat, MetadataImportOptions, MetadataLoadResult, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; +import { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; +import type { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; // Validate data const result = MetadataCollectionInfo.parse(data); @@ -35,6 +35,22 @@ const result = MetadataCollectionInfo.parse(data); | **location** | `string` | optional | Collection location | +--- + +## MetadataExportOptions + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **output** | `string` | ✅ | Output file path | +| **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | optional | Export format | +| **filter** | `string \| Object` | optional | Filter items to export (CEL) | +| **includeStats** | `boolean` | optional | Include metadata statistics | +| **compress** | `boolean` | optional | Compress output (gzip) | +| **prettify** | `boolean` | optional | Pretty print output | + + --- ## MetadataFormat @@ -62,6 +78,24 @@ const result = MetadataCollectionInfo.parse(data); | **transform** | `string` | optional | Transform items before import | +--- + +## MetadataLoadOptions + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **patterns** | `string[]` | optional | File glob patterns | +| **ifNoneMatch** | `string` | optional | ETag for conditional request | +| **ifModifiedSince** | `string` | optional | Only load if modified after this date | +| **validate** | `boolean` | optional | Validate against schema | +| **useCache** | `boolean` | optional | Enable caching | +| **filter** | `string \| Object` | optional | Filter predicate (CEL) | +| **limit** | `integer` | optional | Maximum items to load | +| **recursive** | `boolean` | optional | Search subdirectories | + + --- ## MetadataLoadResult diff --git a/content/docs/references/kernel/metadata-plugin.mdx b/content/docs/references/kernel/metadata-plugin.mdx index 5b73062921..ce00b845e1 100644 --- a/content/docs/references/kernel/metadata-plugin.mdx +++ b/content/docs/references/kernel/metadata-plugin.mdx @@ -72,8 +72,8 @@ cohesive plugin that "takes over" the entire platform's metadata management: ## TypeScript Usage ```typescript -import { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataQuery, MetadataQueryResult, MetadataType, MetadataValidationResult } from '@objectstack/spec/kernel'; -import type { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataQuery, MetadataQueryResult, MetadataType, MetadataValidationResult } from '@objectstack/spec/kernel'; +import { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel'; +import type { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel'; // Validate data const result = MetadataBulkRegisterRequest.parse(data); @@ -139,6 +139,42 @@ const result = MetadataBulkRegisterRequest.parse(data); | **payload** | `Record` | optional | Event-specific payload | +--- + +## MetadataPluginConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **storage** | `Object` | ✅ | Storage backend configuration | +| **customizationPolicies** | `Object[]` | optional | Default customization policies per type | +| **mergeStrategy** | `Object` | optional | Merge strategy for package upgrades | +| **additionalTypes** | `Object[]` | optional | Additional custom metadata types | +| **enableEvents** | `boolean` | optional | Emit metadata change events | +| **validateOnWrite** | `boolean` | optional | Validate metadata on write | +| **enableVersioning** | `boolean` | optional | Track metadata version history | +| **cacheMaxItems** | `integer` | optional | Max items in memory cache | +| **bootstrap** | `Enum<'eager' \| 'lazy' \| 'artifact-only'>` | optional | How metadata is primed at plugin start (eager / lazy / artifact-only) | + + +--- + +## MetadataPluginManifest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Metadata plugin ID | +| **name** | `string` | ✅ | Plugin name | +| **version** | `string` | ✅ | Plugin version | +| **type** | `string` | ✅ | Plugin type | +| **description** | `string` | optional | Plugin description | +| **capabilities** | `Object` | ✅ | Plugin capabilities | +| **config** | `Object` | optional | Plugin configuration | + + --- ## MetadataQuery @@ -208,6 +244,28 @@ const result = MetadataBulkRegisterRequest.parse(data); * `skill` +--- + +## MetadataTypeRegistryEntry + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'object' \| 'field' \| 'validation' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'position' \| 'agent' \| 'tool' \| 'skill'>` | ✅ | Metadata type identifier | +| **label** | `string` | ✅ | Display label for the metadata type | +| **description** | `string` | optional | Description of the metadata type | +| **filePatterns** | `string[]` | ✅ | Glob patterns to discover files of this type | +| **supportsOverlay** | `boolean` | optional | Whether overlay customization is supported | +| **allowOrgOverride** | `boolean` | optional | Allow per-org overlay writes via runtime metadata API | +| **allowRuntimeCreate** | `boolean` | optional | Allow runtime creation via API | +| **supportsVersioning** | `boolean` | optional | Whether version history is tracked | +| **executionPinned** | `boolean` | optional | Transaction rows reference a specific version_hash; history GC is disabled and getByHash() MUST resolve old hashes (ADR-0009) | +| **loadOrder** | `integer` | optional | Loading priority (lower = earlier) | +| **domain** | `Enum<'data' \| 'ui' \| 'automation' \| 'system' \| 'security' \| 'ai'>` | ✅ | Protocol domain | +| **actions** | `Object[]` | optional | Declarative type-level actions (e.g. datasource "Test connection"), reusing ActionSchema; merged with plugin-registered actions when emitted | + + --- ## MetadataValidationResult diff --git a/content/docs/references/kernel/package-registry.mdx b/content/docs/references/kernel/package-registry.mdx index f6c8e63929..a086580c45 100644 --- a/content/docs/references/kernel/package-registry.mdx +++ b/content/docs/references/kernel/package-registry.mdx @@ -48,8 +48,8 @@ never installs them directly. ## TypeScript Usage ```typescript -import { DisablePackageRequest, EnablePackageRequest, GetPackageRequest, ListPackagesRequest, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; -import type { DisablePackageRequest, EnablePackageRequest, GetPackageRequest, ListPackagesRequest, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; +import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; +import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, NamespaceConflictError, NamespaceRegistryEntry, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; // Validate data const result = DisablePackageRequest.parse(data); @@ -68,6 +68,20 @@ Disable package request | **id** | `string` | ✅ | Package ID to disable | +--- + +## DisablePackageResponse + +Disable package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Disabled package details | +| **message** | `string` | optional | Disable status message | + + --- ## EnablePackageRequest @@ -81,6 +95,20 @@ Enable package request | **id** | `string` | ✅ | Package ID to enable | +--- + +## EnablePackageResponse + +Enable package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Enabled package details | +| **message** | `string` | optional | Enable status message | + + --- ## GetPackageRequest @@ -94,6 +122,74 @@ Get package request | **id** | `string` | ✅ | Package identifier | +--- + +## GetPackageResponse + +Get package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Package details | + + +--- + +## InstallPackageRequest + +Install package request + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **manifest** | `Object` | ✅ | Package manifest to install | +| **settings** | `Record` | optional | User-provided settings at install time | +| **enableOnInstall** | `boolean` | optional | Whether to enable immediately after install | +| **platformVersion** | `string` | optional | Current platform version for compatibility verification | + + +--- + +## InstallPackageResponse + +Install package response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **package** | `Object` | ✅ | Installed package details | +| **message** | `string` | optional | Installation status message | +| **dependencyResolution** | `Object` | optional | Dependency resolution result from install analysis | + + +--- + +## InstalledPackage + +Installed package with runtime lifecycle state + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **manifest** | `Object` | ✅ | Full package manifest | +| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>` | optional | Package state: installed, disabled, installing, upgrading, uninstalling, or error | +| **enabled** | `boolean` | optional | Whether the package is currently enabled | +| **installedAt** | `string` | optional | Installation timestamp | +| **updatedAt** | `string` | optional | Last update timestamp | +| **installedVersion** | `string` | optional | Currently installed version for quick access | +| **previousVersion** | `string` | optional | Version before the last upgrade | +| **statusChangedAt** | `string` | optional | Status change timestamp | +| **errorMessage** | `string` | optional | Error message when status is error | +| **settings** | `Record` | optional | User-provided configuration settings | +| **upgradeHistory** | `Object[]` | optional | Version upgrade history | +| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package | + + --- ## ListPackagesRequest @@ -109,6 +205,20 @@ List packages request | **enabled** | `boolean` | optional | Filter by enabled state | +--- + +## ListPackagesResponse + +List packages response + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **packages** | `Object[]` | ✅ | List of installed packages | +| **total** | `number` | ✅ | Total package count | + + --- ## NamespaceConflictError diff --git a/content/docs/references/kernel/package-upgrade.mdx b/content/docs/references/kernel/package-upgrade.mdx index f1d3ca6423..39aa0fc77e 100644 --- a/content/docs/references/kernel/package-upgrade.mdx +++ b/content/docs/references/kernel/package-upgrade.mdx @@ -48,8 +48,8 @@ and rollback capabilities. ## TypeScript Usage ```typescript -import { MetadataChangeType, MetadataDiffItem, RollbackPackageRequest, RollbackPackageResponse, UpgradeImpactLevel, UpgradePackageResponse, UpgradePhase, UpgradePlan } from '@objectstack/spec/kernel'; -import type { MetadataChangeType, MetadataDiffItem, RollbackPackageRequest, RollbackPackageResponse, UpgradeImpactLevel, UpgradePackageResponse, UpgradePhase, UpgradePlan } from '@objectstack/spec/kernel'; +import { MetadataChangeType, MetadataDiffItem, RollbackPackageRequest, RollbackPackageResponse, UpgradeImpactLevel, UpgradePackageRequest, UpgradePackageResponse, UpgradePhase, UpgradePlan, UpgradeSnapshot } from '@objectstack/spec/kernel'; +import type { MetadataChangeType, MetadataDiffItem, RollbackPackageRequest, RollbackPackageResponse, UpgradeImpactLevel, UpgradePackageRequest, UpgradePackageResponse, UpgradePhase, UpgradePlan, UpgradeSnapshot } from '@objectstack/spec/kernel'; // Validate data const result = MetadataChangeType.parse(data); @@ -132,6 +132,25 @@ Severity of upgrade impact * `critical` +--- + +## UpgradePackageRequest + +Upgrade package request + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **packageId** | `string` | ✅ | Package ID to upgrade | +| **targetVersion** | `string` | optional | Target version (defaults to latest) | +| **manifest** | `Object` | optional | New manifest (if installing from local) | +| **createSnapshot** | `boolean` | optional | Whether to create a pre-upgrade backup snapshot | +| **mergeStrategy** | `Enum<'keep-custom' \| 'accept-incoming' \| 'three-way-merge'>` | optional | How to handle customer customizations | +| **dryRun** | `boolean` | optional | Preview upgrade without making changes | +| **skipValidation** | `boolean` | optional | Skip pre-upgrade compatibility checks | + + --- ## UpgradePackageResponse @@ -196,3 +215,25 @@ Upgrade analysis plan generated before execution --- +## UpgradeSnapshot + +Pre-upgrade state snapshot for rollback capability + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Snapshot identifier | +| **packageId** | `string` | ✅ | Package identifier | +| **fromVersion** | `string` | ✅ | Version before upgrade | +| **toVersion** | `string` | ✅ | Target upgrade version | +| **tenantId** | `string` | optional | Tenant identifier | +| **previousManifest** | `Object` | ✅ | Complete manifest of the previous package version | +| **metadataSnapshot** | `Object[]` | ✅ | Snapshot of all package metadata | +| **customizationSnapshot** | `Record[]` | optional | Snapshot of customer customizations | +| **createdAt** | `string` | ✅ | Snapshot creation timestamp | +| **expiresAt** | `string` | optional | Snapshot expiry timestamp | + + +--- + diff --git a/content/docs/references/kernel/plugin-security-advanced.mdx b/content/docs/references/kernel/plugin-security-advanced.mdx index 9553b82af2..c1fd93727e 100644 --- a/content/docs/references/kernel/plugin-security-advanced.mdx +++ b/content/docs/references/kernel/plugin-security-advanced.mdx @@ -30,8 +30,8 @@ Features: ## TypeScript Usage ```typescript -import { KernelSecurityPolicy, KernelSecurityScanResult, KernelSecurityVulnerability, PermissionAction, PermissionScope, PluginTrustLevel, ResourceType, RuntimeConfig, SandboxConfig } from '@objectstack/spec/kernel'; -import type { KernelSecurityPolicy, KernelSecurityScanResult, KernelSecurityVulnerability, PermissionAction, PermissionScope, PluginTrustLevel, ResourceType, RuntimeConfig, SandboxConfig } from '@objectstack/spec/kernel'; +import { KernelSecurityPolicy, KernelSecurityScanResult, KernelSecurityVulnerability, PermissionAction, PermissionScope, PluginPermission, PluginPermissionSet, PluginSecurityManifest, PluginTrustLevel, ResourceType, RuntimeConfig, SandboxConfig } from '@objectstack/spec/kernel'; +import type { KernelSecurityPolicy, KernelSecurityScanResult, KernelSecurityVulnerability, PermissionAction, PermissionScope, PluginPermission, PluginPermissionSet, PluginSecurityManifest, PluginTrustLevel, ResourceType, RuntimeConfig, SandboxConfig } from '@objectstack/spec/kernel'; // Validate data const result = KernelSecurityPolicy.parse(data); @@ -134,6 +134,58 @@ Scope of permission application * `plugin` +--- + +## PluginPermission + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique permission identifier | +| **resource** | `Enum<'data.object' \| 'data.record' \| 'data.field' \| 'ui.view' \| 'ui.dashboard' \| 'ui.report' \| 'system.config' \| 'system.plugin' \| 'system.api' \| 'system.service' \| 'storage.file' \| 'storage.database' \| 'network.http' \| 'network.websocket' \| 'process.spawn' \| 'process.env'>` | ✅ | Type of resource being accessed | +| **actions** | `Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'execute' \| 'manage' \| 'configure' \| 'share' \| 'export' \| 'import' \| 'admin'>[]` | ✅ | | +| **scope** | `Enum<'global' \| 'tenant' \| 'user' \| 'resource' \| 'plugin'>` | optional | Scope of permission application | +| **filter** | `Object` | optional | | +| **description** | `string` | ✅ | | +| **required** | `boolean` | optional | | +| **justification** | `string` | optional | Why this permission is needed | + + +--- + +## PluginPermissionSet + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **permissions** | `Object[]` | ✅ | | +| **groups** | `Object[]` | optional | | +| **defaultGrant** | `Enum<'prompt' \| 'allow' \| 'deny' \| 'inherit'>` | optional | | + + +--- + +## PluginSecurityManifest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **pluginId** | `string` | ✅ | | +| **trustLevel** | `Enum<'verified' \| 'trusted' \| 'community' \| 'untrusted' \| 'blocked'>` | ✅ | Trust level of the plugin | +| **permissions** | `Object` | ✅ | | +| **sandbox** | `Object` | ✅ | | +| **policy** | `Object` | optional | | +| **scanResults** | `Object[]` | optional | | +| **vulnerabilities** | `Object[]` | optional | | +| **codeSigning** | `Object` | optional | | +| **certifications** | `Object[]` | optional | | +| **securityContact** | `Object` | optional | | +| **vulnerabilityDisclosure** | `Object` | optional | | + + --- ## PluginTrustLevel diff --git a/content/docs/references/kernel/plugin-versioning.mdx b/content/docs/references/kernel/plugin-versioning.mdx index 2226c315a2..82f06932dd 100644 --- a/content/docs/references/kernel/plugin-versioning.mdx +++ b/content/docs/references/kernel/plugin-versioning.mdx @@ -28,8 +28,8 @@ Based on semantic versioning (SemVer) with extensions for: ## TypeScript Usage ```typescript -import { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DeprecationNotice, PluginCompatibilityMatrix, PluginDependencyResolutionResult, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel'; -import type { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DeprecationNotice, PluginCompatibilityMatrix, PluginDependencyResolutionResult, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel'; +import { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DeprecationNotice, MultiVersionSupport, PluginCompatibilityMatrix, PluginDependencyResolutionResult, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel'; +import type { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DeprecationNotice, MultiVersionSupport, PluginCompatibilityMatrix, PluginDependencyResolutionResult, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel'; // Validate data const result = BreakingChange.parse(data); @@ -118,6 +118,21 @@ Compatibility level between versions | **migrationPath** | `string` | optional | How to migrate to alternative | +--- + +## MultiVersionSupport + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | | +| **maxConcurrentVersions** | `integer` | optional | How many versions can run at the same time | +| **selectionStrategy** | `Enum<'latest' \| 'stable' \| 'compatible' \| 'pinned' \| 'canary' \| 'custom'>` | optional | | +| **routing** | `Object[]` | optional | | +| **rollout** | `Object` | optional | | + + --- ## PluginCompatibilityMatrix diff --git a/content/docs/references/security/permission.mdx b/content/docs/references/security/permission.mdx index 4d1063964f..024e06fc58 100644 --- a/content/docs/references/security/permission.mdx +++ b/content/docs/references/security/permission.mdx @@ -89,8 +89,8 @@ const result = AdminScope.parse(data); | **allowPurge** | `boolean` | ✅ | [RBAC-gated; operation pending M2] Permanently delete (Hard Delete/GDPR) | | **viewAllRecords** | `boolean` | ✅ | View All Data (Bypass Sharing) | | **modifyAllRecords** | `boolean` | ✅ | Modify All Data (Bypass Sharing) | -| **readScope** | `Enum<'own' \| 'own_and_reports' \| 'unit' \| 'unit_and_below' \| 'org'>` | optional | [ADR-0057 D1] Read depth: own|unit|unit_and_below|org | -| **writeScope** | `Enum<'own' \| 'own_and_reports' \| 'unit' \| 'unit_and_below' \| 'org'>` | optional | [ADR-0057 D1] Write depth: own|unit|unit_and_below|org | +| **readScope** | `Enum<'own' \| 'own_and_reports' \| 'unit' \| 'unit_and_below' \| 'org'>` | optional | [ADR-0057 D1] Read depth: own\|unit\|unit_and_below\|org | +| **writeScope** | `Enum<'own' \| 'own_and_reports' \| 'unit' \| 'unit_and_below' \| 'org'>` | optional | [ADR-0057 D1] Write depth: own\|unit\|unit_and_below\|org | --- @@ -105,7 +105,7 @@ const result = AdminScope.parse(data); | **label** | `string` | optional | Display label | | **packageId** | `string` | optional | [ADR-0086 D3] Owning package id for a package-shipped set (absent = env-authored) | | **managedBy** | `Enum<'package' \| 'platform' \| 'user'>` | optional | [ADR-0086 D3] Record provenance: package (upgrade-owned metadata) vs platform/user (env config) | -| **isDefault** | `boolean` | ✅ | [ADR-0090 D5] Install-time suggestion to bind this set to the everyone position (admin confirms; never auto-bound) | +| **isDefault** | `boolean` | ✅ | [ADR-0090 D5] App baseline for the everyone position: app-level sets are auto-bound at boot (guarded, idempotent); package-level sets become install-time suggestions an admin confirms | | **objects** | `Record` | ✅ | Entity permissions | | **fields** | `Record` | optional | Field level security | | **systemPermissions** | `string[]` | optional | System level capabilities | diff --git a/content/docs/references/security/sharing.mdx b/content/docs/references/security/sharing.mdx index ffb5e253d8..461d2187c6 100644 --- a/content/docs/references/security/sharing.mdx +++ b/content/docs/references/security/sharing.mdx @@ -16,13 +16,32 @@ The baseline security posture for an object. ## TypeScript Usage ```typescript -import { OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRuleType } from '@objectstack/spec/security'; -import type { OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRuleType } from '@objectstack/spec/security'; +import { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security'; +import type { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security'; // Validate data -const result = OWDModel.parse(data); +const result = CriteriaSharingRule.parse(data); ``` +--- + +## CriteriaSharingRule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **description** | `string` | optional | Administrative notes | +| **object** | `string` | ✅ | Target Object Name | +| **active** | `boolean` | optional | | +| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | +| **sharedWith** | `Object` | ✅ | The recipient of the shared access | +| **type** | `string` | ✅ | | +| **condition** | `string \| Object` | ✅ | Predicate (CEL). e.g. P`record.department == "Sales"` | + + --- ## OWDModel @@ -78,6 +97,55 @@ const result = OWDModel.parse(data); * `full` +--- + +## SharingRule + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +**Type:** `criteria` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **description** | `string` | optional | Administrative notes | +| **object** | `string` | ✅ | Target Object Name | +| **active** | `boolean` | optional | | +| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | +| **sharedWith** | `Object` | ✅ | The recipient of the shared access | +| **type** | `string` | ✅ | | +| **condition** | `string \| Object` | ✅ | Predicate (CEL). e.g. P`record.department == "Sales"` | + +--- + +#### Option 2 + +**Type:** `owner` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Unique rule name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **description** | `string` | optional | Administrative notes | +| **object** | `string` | ✅ | Target Object Name | +| **active** | `boolean` | optional | | +| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | +| **sharedWith** | `Object` | ✅ | The recipient of the shared access | +| **type** | `string` | ✅ | | +| **ownedBy** | `Object` | ✅ | Source group/position whose records are being shared | + +--- + + --- ## SharingRuleType diff --git a/content/docs/references/shared/expression.mdx b/content/docs/references/shared/expression.mdx index c3edf67907..63624e5152 100644 --- a/content/docs/references/shared/expression.mdx +++ b/content/docs/references/shared/expression.mdx @@ -48,13 +48,41 @@ posture and portability story differ. ## TypeScript Usage ```typescript -import { Expression, ExpressionDialect, ExpressionMeta, Predicate } from '@objectstack/spec/shared'; -import type { Expression, ExpressionDialect, ExpressionMeta, Predicate } from '@objectstack/spec/shared'; +import { CronExpressionInput, Expression, ExpressionDialect, ExpressionInput, ExpressionMeta, Predicate, PredicateInput, TemplateExpressionInput } from '@objectstack/spec/shared'; +import type { CronExpressionInput, Expression, ExpressionDialect, ExpressionInput, ExpressionMeta, Predicate, PredicateInput, TemplateExpressionInput } from '@objectstack/spec/shared'; // Validate data -const result = Expression.parse(data); +const result = CronExpressionInput.parse(data); ``` +--- + +## CronExpressionInput + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +Type: `string` + +--- + +#### Option 2 + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | +| **source** | `string` | optional | | +| **ast** | `any` | optional | | +| **meta** | `Object` | optional | | + +--- + + --- ## Expression @@ -81,6 +109,34 @@ const result = Expression.parse(data); * `template` +--- + +## ExpressionInput + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +Type: `string` + +--- + +#### Option 2 + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | +| **source** | `string` | optional | | +| **ast** | `any` | optional | | +| **meta** | `Object` | optional | | + +--- + + --- ## ExpressionMeta @@ -109,3 +165,59 @@ const result = Expression.parse(data); --- +## PredicateInput + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +Type: `string` + +--- + +#### Option 2 + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | +| **source** | `string` | optional | | +| **ast** | `any` | optional | | +| **meta** | `Object` | optional | | + +--- + + +--- + +## TemplateExpressionInput + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +Type: `string` + +--- + +#### Option 2 + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | +| **source** | `string` | optional | | +| **ast** | `any` | optional | | +| **meta** | `Object` | optional | | + +--- + + +--- + diff --git a/content/docs/references/shared/index.mdx b/content/docs/references/shared/index.mdx index b470bf8ad0..10d4b6a4ff 100644 --- a/content/docs/references/shared/index.mdx +++ b/content/docs/references/shared/index.mdx @@ -11,6 +11,7 @@ This section contains all protocol schemas for the shared layer of ObjectStack. + diff --git a/content/docs/references/shared/mapping.mdx b/content/docs/references/shared/mapping.mdx new file mode 100644 index 0000000000..1fd66457c9 --- /dev/null +++ b/content/docs/references/shared/mapping.mdx @@ -0,0 +1,173 @@ +--- +title: Mapping +description: Mapping protocol schemas +--- + +{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} + +Base Field Mapping Protocol + +Shared by: ETL, Sync, Connector, External Lookup + +This module provides the canonical field mapping schema used across + +ObjectStack for data transformation and synchronization. + +**Use Cases:** + +- ETL pipelines (data/mapping.zod.ts) + +- Data synchronization (automation/sync.zod.ts) + +- Integration connectors (integration/connector.zod.ts) + +- External lookups (data/external-lookup.zod.ts) + +@example Basic field mapping + +```typescript + +const mapping: FieldMapping = \{ + +source: 'external_user_id', + +target: 'user_id', + +\}; + +``` + +@example With transformation + +```typescript + +const mapping: FieldMapping = \{ + +source: 'user_name', + +target: 'name', + +transform: \{ type: 'cast', targetType: 'string' \}, + +defaultValue: 'Unknown' + +\}; + +``` + + +**Source:** `packages/spec/src/shared/mapping.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldMapping, TransformType } from '@objectstack/spec/shared'; +import type { FieldMapping, TransformType } from '@objectstack/spec/shared'; + +// Validate data +const result = FieldMapping.parse(data); +``` + +--- + +## FieldMapping + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **source** | `string` | ✅ | Source field name | +| **target** | `string` | ✅ | Target field name | +| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | +| **defaultValue** | `any` | optional | Default if source is null/undefined | + + +--- + +## TransformType + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +Set a constant value + +**Type:** `constant` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **value** | `any` | ✅ | Constant value to use | + +--- + +#### Option 2 + +Cast to a specific data type + +**Type:** `cast` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **targetType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date'>` | ✅ | Target data type | + +--- + +#### Option 3 + +Lookup value from another table + +**Type:** `lookup` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **table** | `string` | ✅ | Lookup table name | +| **keyField** | `string` | ✅ | Field to match on | +| **valueField** | `string` | ✅ | Field to retrieve | + +--- + +#### Option 4 + +Custom JavaScript transformation + +**Type:** `javascript` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **expression** | `string \| Object` | ✅ | JS expression (dialect="js" recommended). e.g. value.toUpperCase() | + +--- + +#### Option 5 + +Map values using a dictionary + +**Type:** `map` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **mappings** | `Record` | ✅ | Value mappings (e.g., `{"Active": "active"}`) | + +--- + + +--- + diff --git a/content/docs/references/shared/meta.json b/content/docs/references/shared/meta.json index 60747fd6af..8ef0fa19a3 100644 --- a/content/docs/references/shared/meta.json +++ b/content/docs/references/shared/meta.json @@ -6,6 +6,7 @@ "expression", "http", "identifiers", + "mapping", "metadata-persistence", "metadata-types", "protection" diff --git a/content/docs/references/shared/protection.mdx b/content/docs/references/shared/protection.mdx index 800148c09c..924c3e41f9 100644 --- a/content/docs/references/shared/protection.mdx +++ b/content/docs/references/shared/protection.mdx @@ -99,7 +99,7 @@ const result = Protection.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | ✅ | Lock policy — none | no-overlay | no-delete | full. | +| **lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | ✅ | Lock policy — none \| no-overlay \| no-delete \| full. | | **reason** | `string` | ✅ | User-visible reason shown when the lock blocks an action. | | **docsUrl** | `string` | optional | Optional URL the Studio banner links to for more context. | diff --git a/content/docs/references/system/audit.mdx b/content/docs/references/system/audit.mdx index ebf291c9e7..5af34269b9 100644 --- a/content/docs/references/system/audit.mdx +++ b/content/docs/references/system/audit.mdx @@ -30,13 +30,39 @@ Features: ## TypeScript Usage ```typescript -import { AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig } from '@objectstack/spec/system'; -import type { AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig } from '@objectstack/spec/system'; +import { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; +import type { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; // Validate data -const result = AuditEvent.parse(data); +const result = AuditConfig.parse(data); ``` +--- + +## AuditConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | +| **label** | `string` | ✅ | Display label | +| **enabled** | `boolean` | optional | Enable audit logging | +| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to audit | +| **excludeEventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to exclude | +| **minimumSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Minimum severity level | +| **storage** | `Object` | ✅ | Storage configuration | +| **retentionPolicy** | `Object` | optional | Retention policy | +| **suspiciousActivityRules** | `Object[]` | optional | Suspicious activity rules | +| **includeSensitiveData** | `boolean` | optional | Include sensitive data | +| **redactFields** | `string[]` | optional | Fields to redact | +| **logReads** | `boolean` | optional | Log read operations | +| **readSamplingRate** | `number` | optional | Read sampling rate | +| **logSystemEvents** | `boolean` | optional | Log system events | +| **customHandlers** | `Object[]` | optional | Custom event handler references | +| **compliance** | `Object` | optional | Compliance configuration | + + --- ## AuditEvent @@ -222,3 +248,22 @@ const result = AuditEvent.parse(data); --- +## SuspiciousActivityRule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Rule identifier | +| **name** | `string` | ✅ | Rule name | +| **description** | `string` | optional | Rule description | +| **enabled** | `boolean` | optional | Rule enabled status | +| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | ✅ | Event types to monitor | +| **condition** | `Object \| string \| Object` | ✅ | Detection condition — structured threshold or CEL predicate | +| **actions** | `Enum<'alert' \| 'lock_account' \| 'block_ip' \| 'require_mfa' \| 'log_critical' \| 'webhook'>[]` | ✅ | Actions to take | +| **alertSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Alert severity | +| **notifications** | `Object` | optional | Notification configuration | + + +--- + diff --git a/content/docs/references/system/book.mdx b/content/docs/references/system/book.mdx index d9169446f0..0c766631fc 100644 --- a/content/docs/references/system/book.mdx +++ b/content/docs/references/system/book.mdx @@ -168,7 +168,7 @@ Type: `string` | **doc** | `string` | optional | Doc name to reference | | **href** | `string` | optional | External link (use instead of `doc`) | | **label** | `string` | optional | Optional label override; title authority stays in the doc | -| **badge** | `string` | optional | e.g. "beta" | "new" | +| **badge** | `string` | optional | e.g. "beta" \| "new" | | **icon** | `string` | optional | | --- diff --git a/content/docs/references/system/cache.mdx b/content/docs/references/system/cache.mdx index cc11346266..a12a2813f8 100644 --- a/content/docs/references/system/cache.mdx +++ b/content/docs/references/system/cache.mdx @@ -46,8 +46,8 @@ Supports Memory, Redis, Memcached, and CDN. ## TypeScript Usage ```typescript -import { CacheAvalanchePrevention, CacheConfig, CacheConsistency, CacheInvalidation, CacheStrategy, CacheTier } from '@objectstack/spec/system'; -import type { CacheAvalanchePrevention, CacheConfig, CacheConsistency, CacheInvalidation, CacheStrategy, CacheTier } from '@objectstack/spec/system'; +import { CacheAvalanchePrevention, CacheConfig, CacheConsistency, CacheInvalidation, CacheStrategy, CacheTier, CacheWarmup, DistributedCacheConfig } from '@objectstack/spec/system'; +import type { CacheAvalanchePrevention, CacheConfig, CacheConsistency, CacheInvalidation, CacheStrategy, CacheTier, CacheWarmup, DistributedCacheConfig } from '@objectstack/spec/system'; // Validate data const result = CacheAvalanchePrevention.parse(data); @@ -151,3 +151,41 @@ Configuration for a single cache tier in the hierarchy --- +## CacheWarmup + +Cache warmup strategy + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Enable cache warmup | +| **strategy** | `Enum<'eager' \| 'lazy' \| 'scheduled'>` | optional | Warmup strategy: eager (at startup), lazy (on first access), scheduled (cron) | +| **schedule** | `string \| Object` | optional | Cron expression for scheduled warmup | +| **patterns** | `string[]` | optional | Key patterns to warm up (e.g., "user:*", "config:*") | +| **concurrency** | `number` | optional | Maximum concurrent warmup operations | + + +--- + +## DistributedCacheConfig + +Distributed cache configuration with consistency and avalanche prevention + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Enable application-level caching | +| **tiers** | `Object[]` | ✅ | Ordered cache tier hierarchy | +| **invalidation** | `Object[]` | ✅ | Cache invalidation rules | +| **prefetch** | `boolean` | optional | Enable cache prefetching | +| **compression** | `boolean` | optional | Enable data compression in cache | +| **encryption** | `boolean` | optional | Enable encryption for cached data | +| **consistency** | `Enum<'write_through' \| 'write_behind' \| 'write_around' \| 'refresh_ahead'>` | optional | Distributed cache consistency strategy | +| **avalanchePrevention** | `Object` | optional | Cache avalanche and stampede prevention | +| **warmup** | `Object` | optional | Cache warmup strategy | + + +--- + diff --git a/content/docs/references/system/disaster-recovery.mdx b/content/docs/references/system/disaster-recovery.mdx index e61d13021d..e95012df9d 100644 --- a/content/docs/references/system/disaster-recovery.mdx +++ b/content/docs/references/system/disaster-recovery.mdx @@ -40,13 +40,32 @@ encryption: \{ enabled: true, algorithm: 'AES-256-GCM' \}, ## TypeScript Usage ```typescript -import { BackupRetention, BackupStrategy, FailoverConfig, FailoverMode, RPO, RTO } from '@objectstack/spec/system'; -import type { BackupRetention, BackupStrategy, FailoverConfig, FailoverMode, RPO, RTO } from '@objectstack/spec/system'; +import { BackupConfig, BackupRetention, BackupStrategy, DisasterRecoveryPlan, FailoverConfig, FailoverMode, RPO, RTO } from '@objectstack/spec/system'; +import type { BackupConfig, BackupRetention, BackupStrategy, DisasterRecoveryPlan, FailoverConfig, FailoverMode, RPO, RTO } from '@objectstack/spec/system'; // Validate data -const result = BackupRetention.parse(data); +const result = BackupConfig.parse(data); ``` +--- + +## BackupConfig + +Backup configuration + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **strategy** | `Enum<'full' \| 'incremental' \| 'differential'>` | optional | Backup strategy | +| **schedule** | `string \| Object` | optional | Cron expression for backup schedule — cron`0 2 * * *` | +| **retention** | `Object` | ✅ | Backup retention policy | +| **destination** | `Object` | ✅ | Backup storage destination | +| **encryption** | `Object` | optional | Backup encryption settings | +| **compression** | `Object` | optional | Backup compression settings | +| **verifyAfterBackup** | `boolean` | optional | Verify backup integrity after creation | + + --- ## BackupRetention @@ -75,6 +94,27 @@ Backup strategy type * `differential` +--- + +## DisasterRecoveryPlan + +Complete disaster recovery plan configuration + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **enabled** | `boolean` | optional | Enable disaster recovery plan | +| **rpo** | `Object` | ✅ | Recovery Point Objective | +| **rto** | `Object` | ✅ | Recovery Time Objective | +| **backup** | `Object` | ✅ | Backup configuration | +| **failover** | `Object` | optional | Multi-region failover configuration | +| **replication** | `Object` | optional | Data replication settings | +| **testing** | `Object` | optional | Automated disaster recovery testing | +| **runbookUrl** | `string` | optional | URL to disaster recovery runbook/playbook | +| **contacts** | `Object[]` | optional | Emergency contact list for DR incidents | + + --- ## FailoverConfig diff --git a/content/docs/references/system/email-template.mdx b/content/docs/references/system/email-template.mdx index 3a4ccd7538..8dbb5241c9 100644 --- a/content/docs/references/system/email-template.mdx +++ b/content/docs/references/system/email-template.mdx @@ -65,8 +65,8 @@ const result = EmailTemplateDefinition.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this email template. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/system/job.mdx b/content/docs/references/system/job.mdx index 1dbd6d5b32..25eb272dc2 100644 --- a/content/docs/references/system/job.mdx +++ b/content/docs/references/system/job.mdx @@ -16,13 +16,26 @@ Schedule jobs using cron expressions ## TypeScript Usage ```typescript -import { IntervalSchedule, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy } from '@objectstack/spec/system'; -import type { IntervalSchedule, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy } from '@objectstack/spec/system'; +import { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; +import type { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; // Validate data -const result = IntervalSchedule.parse(data); +const result = CronSchedule.parse(data); ``` +--- + +## CronSchedule + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **expression** | `string \| Object` | ✅ | Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope. | +| **timezone** | `string` | optional | Timezone for cron execution (e.g., "America/New_York") | + + --- ## IntervalSchedule @@ -35,6 +48,25 @@ const result = IntervalSchedule.parse(data); | **intervalMs** | `integer` | ✅ | Interval in milliseconds | +--- + +## Job + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | optional | Unique job identifier (defaults to `name` when omitted) | +| **name** | `string` | ✅ | Job name (snake_case) | +| **label** | `string` | optional | Human-readable label | +| **description** | `string` | optional | Job description / purpose | +| **schedule** | `Object \| Object \| Object` | ✅ | Job schedule configuration | +| **handler** | `string` | ✅ | Handler function name (must match a key in `defineStack({ functions })`) | +| **retryPolicy** | `Object` | optional | Retry policy configuration | +| **timeout** | `integer` | optional | Timeout in milliseconds | +| **enabled** | `boolean` | optional | Whether the job is enabled | + + --- ## JobExecution @@ -90,3 +122,52 @@ const result = IntervalSchedule.parse(data); --- +## Schedule + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +**Type:** `cron` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **expression** | `string \| Object` | ✅ | Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope. | +| **timezone** | `string` | optional | Timezone for cron execution (e.g., "America/New_York") | + +--- + +#### Option 2 + +**Type:** `interval` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **intervalMs** | `integer` | ✅ | Interval in milliseconds | + +--- + +#### Option 3 + +**Type:** `once` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **at** | `string` | ✅ | ISO 8601 datetime when to execute | + +--- + + +--- + diff --git a/content/docs/references/system/metrics.mdx b/content/docs/references/system/metrics.mdx index ad9d8a2515..b399217170 100644 --- a/content/docs/references/system/metrics.mdx +++ b/content/docs/references/system/metrics.mdx @@ -26,8 +26,8 @@ Comprehensive metrics collection and monitoring: ## TypeScript Usage ```typescript -import { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system'; -import type { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system'; +import { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, MetricsConfig, ServiceLevelIndicator, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system'; +import type { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, MetricsConfig, ServiceLevelIndicator, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system'; // Validate data const result = HistogramBucketConfig.parse(data); @@ -193,6 +193,50 @@ Metric unit * `custom` +--- + +## MetricsConfig + +Metrics configuration + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | +| **label** | `string` | ✅ | Display label | +| **enabled** | `boolean` | optional | | +| **metrics** | `Object[]` | optional | | +| **defaultLabels** | `Record` | optional | Metric labels | +| **aggregations** | `Object[]` | optional | | +| **slis** | `Object[]` | optional | | +| **slos** | `Object[]` | optional | | +| **exports** | `Object[]` | optional | | +| **collectionInterval** | `integer` | optional | | +| **retention** | `Object` | optional | | +| **cardinalityLimits** | `Object` | optional | | + + +--- + +## ServiceLevelIndicator + +Service Level Indicator + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | SLI name (snake_case) | +| **label** | `string` | ✅ | Display label | +| **description** | `string` | optional | SLI description | +| **metric** | `string` | ✅ | Base metric name | +| **type** | `Enum<'availability' \| 'latency' \| 'throughput' \| 'error_rate' \| 'saturation' \| 'custom'>` | ✅ | SLI type | +| **successCriteria** | `Object \| string \| Object` | ✅ | Success criteria — structured or CEL predicate | +| **window** | `Object` | ✅ | Measurement window | +| **enabled** | `boolean` | optional | | + + --- ## ServiceLevelObjective diff --git a/content/docs/references/system/migration.mdx b/content/docs/references/system/migration.mdx index c669c8db80..c99d8fe426 100644 --- a/content/docs/references/system/migration.mdx +++ b/content/docs/references/system/migration.mdx @@ -12,13 +12,63 @@ description: Migration protocol schemas ## TypeScript Usage ```typescript -import { DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; -import type { DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; +import { AddFieldOperation, ChangeSet, CreateObjectOperation, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; +import type { AddFieldOperation, ChangeSet, CreateObjectOperation, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; // Validate data -const result = DeleteObjectOperation.parse(data); +const result = AddFieldOperation.parse(data); ``` +--- + +## AddFieldOperation + +Add a new field to an existing object + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **fieldName** | `string` | ✅ | Name of the field to add | +| **field** | `Object` | ✅ | Full field definition to add | + + +--- + +## ChangeSet + +A versioned set of atomic schema migration operations + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this change set | +| **name** | `string` | ✅ | Human readable name for the migration | +| **description** | `string` | optional | Detailed description of what this migration does | +| **author** | `string` | optional | Author who created this migration | +| **createdAt** | `string` | optional | ISO 8601 timestamp when the migration was created | +| **dependencies** | `Object[]` | optional | Migrations that must run before this one | +| **operations** | `Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | Ordered list of atomic migration operations | +| **rollback** | `Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | optional | Operations to reverse this migration | + + +--- + +## CreateObjectOperation + +Create a new object + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **object** | `Object` | ✅ | Full object definition to create | + + --- ## DeleteObjectOperation @@ -62,6 +112,127 @@ Dependency reference to another migration that must run first | **package** | `string` | optional | Package that owns the dependency migration | +--- + +## MigrationOperation + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +Add a new field to an existing object + +**Type:** `add_field` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **fieldName** | `string` | ✅ | Name of the field to add | +| **field** | `Object` | ✅ | Full field definition to add | + +--- + +#### Option 2 + +Modify properties of an existing field + +**Type:** `modify_field` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **fieldName** | `string` | ✅ | Name of the field to modify | +| **changes** | `Record` | ✅ | Partial field definition updates | + +--- + +#### Option 3 + +Remove a field from an existing object + +**Type:** `remove_field` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **fieldName** | `string` | ✅ | Name of the field to remove | + +--- + +#### Option 4 + +Create a new object + +**Type:** `create_object` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **object** | `Object` | ✅ | Full object definition to create | + +--- + +#### Option 5 + +Rename an existing object + +**Type:** `rename_object` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **oldName** | `string` | ✅ | Current object name | +| **newName** | `string` | ✅ | New object name | + +--- + +#### Option 6 + +Delete an existing object + +**Type:** `delete_object` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Name of the object to delete | + +--- + +#### Option 7 + +Execute a raw SQL statement + +**Type:** `execute_sql` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `string` | ✅ | | +| **sql** | `string` | ✅ | Raw SQL statement to execute | +| **description** | `string` | optional | Human-readable description of the SQL | + +--- + + --- ## ModifyFieldOperation diff --git a/content/docs/references/system/notification.mdx b/content/docs/references/system/notification.mdx index d6aadf3a1e..289636b7db 100644 --- a/content/docs/references/system/notification.mdx +++ b/content/docs/references/system/notification.mdx @@ -50,13 +50,45 @@ Supports variables for personalization and file attachments. ## TypeScript Usage ```typescript -import { NotificationChannel } from '@objectstack/spec/system'; -import type { NotificationChannel } from '@objectstack/spec/system'; +import { EmailTemplate, InAppNotification, NotificationChannel, NotificationConfig, PushNotification, SMSTemplate } from '@objectstack/spec/system'; +import type { EmailTemplate, InAppNotification, NotificationChannel, NotificationConfig, PushNotification, SMSTemplate } from '@objectstack/spec/system'; // Validate data -const result = NotificationChannel.parse(data); +const result = EmailTemplate.parse(data); ``` +--- + +## EmailTemplate + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Template identifier | +| **subject** | `string \| Object` | ✅ | Email subject — supports `{{var}`} interpolation | +| **body** | `string \| Object` | ✅ | Email body content — supports `{{var}`} interpolation | +| **bodyType** | `Enum<'text' \| 'html' \| 'markdown'>` | optional | Body content type | +| **variables** | `string[]` | optional | Template variables | +| **attachments** | `Object[]` | optional | Email attachments | + + +--- + +## InAppNotification + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **title** | `string` | ✅ | Notification title | +| **message** | `string \| Object` | ✅ | Notification message — supports `{{var}`} interpolation | +| **type** | `Enum<'info' \| 'success' \| 'warning' \| 'error'>` | ✅ | Notification type | +| **actionUrl** | `string` | optional | Action URL | +| **dismissible** | `boolean` | optional | User dismissible | +| **expiresAt** | `number` | optional | Expiration timestamp | + + --- ## NotificationChannel @@ -74,3 +106,51 @@ const result = NotificationChannel.parse(data); --- +## NotificationConfig + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Notification ID | +| **name** | `string` | ✅ | Notification name | +| **channel** | `Enum<'email' \| 'sms' \| 'push' \| 'in-app' \| 'slack' \| 'teams' \| 'webhook'>` | ✅ | Notification channel | +| **template** | `Object \| Object \| Object \| Object` | ✅ | Notification template | +| **recipients** | `Object` | ✅ | Recipients | +| **schedule** | `Object` | optional | Scheduling | +| **retryPolicy** | `Object` | optional | Retry policy | +| **tracking** | `Object` | optional | Tracking configuration | + + +--- + +## PushNotification + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **title** | `string` | ✅ | Notification title | +| **body** | `string \| Object` | ✅ | Notification body — supports `{{var}`} interpolation | +| **icon** | `string` | optional | Notification icon URL | +| **badge** | `number` | optional | Badge count | +| **data** | `Record` | optional | Custom data | +| **actions** | `Object[]` | optional | Notification actions | + + +--- + +## SMSTemplate + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Template identifier | +| **message** | `string \| Object` | ✅ | SMS message content — supports `{{var}`} interpolation | +| **maxLength** | `number` | optional | Maximum message length | +| **variables** | `string[]` | optional | Template variables | + + +--- + diff --git a/content/docs/references/system/settings-manifest.mdx b/content/docs/references/system/settings-manifest.mdx index cc5d0a34fa..017be15838 100644 --- a/content/docs/references/system/settings-manifest.mdx +++ b/content/docs/references/system/settings-manifest.mdx @@ -40,8 +40,8 @@ Resolution order (handled by `SettingsService.get`): ## TypeScript Usage ```typescript -import { ResolvedSettingValue, SettingsActionResult, SpecifierHandler, SpecifierOption, SpecifierScope, SpecifierType } from '@objectstack/spec/system'; -import type { ResolvedSettingValue, SettingsActionResult, SpecifierHandler, SpecifierOption, SpecifierScope, SpecifierType } from '@objectstack/spec/system'; +import { ResolvedSettingValue, SettingsActionResult, SettingsManifest, SettingsNamespacePayload, Specifier, SpecifierHandler, SpecifierOption, SpecifierScope, SpecifierType } from '@objectstack/spec/system'; +import type { ResolvedSettingValue, SettingsActionResult, SettingsManifest, SettingsNamespacePayload, Specifier, SpecifierHandler, SpecifierOption, SpecifierScope, SpecifierType } from '@objectstack/spec/system'; // Validate data const result = ResolvedSettingValue.parse(data); @@ -76,6 +76,82 @@ const result = ResolvedSettingValue.parse(data); | **details** | `any` | optional | Optional structured detail (renderer-defined) | +--- + +## SettingsManifest + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **namespace** | `string` | ✅ | Namespace (snake_case, globally unique) | +| **version** | `integer` | optional | Manifest schema version | +| **label** | `string` | ✅ | Display label | +| **icon** | `string` | optional | Icon (Lucide) | +| **description** | `string` | optional | Short description | +| **helpText** | `string` | optional | Markdown help text shown above specifiers | +| **scope** | `Enum<'global' \| 'tenant' \| 'user'>` | optional | Default scope for specifiers | +| **readPermission** | `string` | optional | Permission required to read | +| **writePermission** | `string` | optional | Permission required to write | +| **category** | `string` | optional | Settings hub category | +| **order** | `number` | optional | Display order | +| **specifiers** | `Object[]` | ✅ | Page contents (ordered) | +| **visible** | `string \| Object` | optional | Whole-manifest visibility | +| **featureFlag** | `string` | optional | Gate manifest visibility on a feature flag | +| **beta** | `boolean` | optional | Show a Beta chip on the page | + + +--- + +## SettingsNamespacePayload + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **manifest** | `Object` | ✅ | | +| **values** | `Record` | ✅ | Effective values keyed by specifier.key | + + +--- + +## Specifier + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'group' \| 'child_pane' \| 'info_banner' \| 'title_value' \| 'text' \| 'textarea' \| 'password' \| 'email' \| 'url' \| 'phone' \| 'number' \| 'toggle' \| 'select' \| 'radio' \| 'multiselect' \| 'slider' \| 'color' \| 'json' \| 'action_button'>` | ✅ | Specifier variant | +| **id** | `string` | optional | Stable identifier (snake_case) | +| **key** | `string` | optional | Storage key (snake_case) | +| **label** | `string` | ✅ | Display label | +| **description** | `string` | optional | Help text | +| **icon** | `string` | optional | Icon name (Lucide) | +| **default** | `any` | optional | Default value | +| **visible** | `string \| Object` | optional | Visibility expression | +| **required** | `boolean` | optional | Required field | +| **encrypted** | `boolean` | optional | Encrypt value at rest (forced true for password) | +| **scope** | `Enum<'global' \| 'tenant' \| 'user'>` | optional | Override manifest scope for this key | +| **availableScopes** | `Enum<'global' \| 'tenant' \| 'user'>[]` | optional | Scopes allowed to override this specifier | +| **lockable** | `boolean` | optional | Allow upper-scope locking of this specifier | +| **readPermission** | `string` | optional | Permission required to read this specifier | +| **writePermission** | `string` | optional | Permission required to write this specifier | +| **deprecated** | `boolean` | optional | Mark deprecated | +| **replacedBy** | `string` | optional | Replacement key (used when deprecated=true) | +| **options** | `Object[]` | optional | Options for select/radio/multiselect | +| **min** | `number` | optional | | +| **max** | `number` | optional | | +| **step** | `number` | optional | | +| **minLength** | `integer` | optional | | +| **maxLength** | `integer` | optional | | +| **pattern** | `string` | optional | Regex pattern (text only) | +| **rows** | `integer` | optional | | +| **handler** | `Object \| Object \| Object` | optional | Action handler (action_button) | +| **childNamespace** | `string` | optional | Sub-namespace (child_pane) | +| **bannerText** | `string` | optional | Markdown body (info_banner) | +| **bannerSeverity** | `Enum<'info' \| 'success' \| 'warning' \| 'error'>` | optional | | + + --- ## SpecifierHandler diff --git a/content/docs/references/system/tracing.mdx b/content/docs/references/system/tracing.mdx index bd185e56b2..fa06c7682f 100644 --- a/content/docs/references/system/tracing.mdx +++ b/content/docs/references/system/tracing.mdx @@ -26,8 +26,8 @@ Comprehensive distributed tracing based on OpenTelemetry standards: ## TypeScript Usage ```typescript -import { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceState } from '@objectstack/spec/system'; -import type { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceState } from '@objectstack/spec/system'; +import { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system'; +import type { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system'; // Validate data const result = OpenTelemetryCompatibility.parse(data); @@ -288,6 +288,25 @@ Trace propagation format * `custom` +--- + +## TraceSamplingConfig + +Trace sampling configuration + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>` | ✅ | Sampling strategy | +| **ratio** | `number` | optional | Sample ratio (0-1) | +| **rateLimit** | `number` | optional | Traces per second | +| **parentBased** | `Object` | optional | | +| **composite** | `Object[]` | optional | | +| **rules** | `Object[]` | optional | | +| **customSamplerId** | `string` | optional | Custom sampler identifier | + + --- ## TraceState @@ -303,3 +322,25 @@ Trace state --- +## TracingConfig + +Tracing configuration + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | +| **label** | `string` | ✅ | Display label | +| **enabled** | `boolean` | optional | | +| **sampling** | `Object` | optional | Trace sampling configuration | +| **propagation** | `Object` | optional | Trace context propagation | +| **openTelemetry** | `Object` | optional | OpenTelemetry compatibility configuration | +| **spanLimits** | `Object` | optional | | +| **traceIdGenerator** | `Enum<'random' \| 'uuid' \| 'custom'>` | optional | | +| **customTraceIdGeneratorId** | `string` | optional | Custom generator identifier | +| **performance** | `Object` | optional | | + + +--- + diff --git a/content/docs/references/ui/action.mdx b/content/docs/references/ui/action.mdx index a4dc70fb65..2734e0b14c 100644 --- a/content/docs/references/ui/action.mdx +++ b/content/docs/references/ui/action.mdx @@ -48,13 +48,60 @@ to the field name and is used as the request-body key). ## TypeScript Usage ```typescript -import { ActionAi, ActionLocation, ActionType } from '@objectstack/spec/ui'; -import type { ActionAi, ActionLocation, ActionType } from '@objectstack/spec/ui'; +import { Action, ActionAi, ActionLocation, ActionParam, ActionType } from '@objectstack/spec/ui'; +import type { Action, ActionAi, ActionLocation, ActionParam, ActionType } from '@objectstack/spec/ui'; // Validate data -const result = ActionAi.parse(data); +const result = Action.parse(data); ``` +--- + +## Action + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Machine name (lowercase snake_case) | +| **label** | `string` | ✅ | Display label | +| **objectName** | `string` | optional | Target object this action belongs to. When set, the action is auto-merged into the object's actions array by defineStack(). | +| **icon** | `string` | optional | Icon name | +| **locations** | `Enum<'list_toolbar' \| 'list_item' \| 'record_header' \| 'record_more' \| 'record_related' \| 'record_section' \| 'global_nav'>[]` | optional | Locations where this action is visible | +| **component** | `Enum<'action:button' \| 'action:icon' \| 'action:menu' \| 'action:group'>` | optional | Visual component override | +| **type** | `Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api' \| 'form'>` | optional | Action functionality type | +| **target** | `string` | optional | URL, Script Name, Flow ID, or API Endpoint. Supports $`{param.X}` and $`{ctx.X}` interpolation. | +| **openIn** | `Enum<'self' \| 'new-tab'>` | optional | For type:'url' — where to open `target`. 'new-tab' opens a new browser tab; 'self' navigates in place. When omitted, external/absolute URLs open in a new tab and relative URLs navigate in place. Static execution option — keep it OUT of `params` (which is user-input-collection only). | +| **body** | `Object \| Object` | optional | Action body — expression (L1) or sandboxed JS (L2). Only used when type is `script`. | +| **execute** | `string` | optional | @deprecated — Use target instead. Auto-migrated to target during parsing. | +| **params** | `Object[]` | optional | Input parameters required from user | +| **variant** | `Enum<'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'link'>` | optional | Button visual variant for styling (primary = highlighted, danger = destructive, ghost = transparent) | +| **order** | `number` | optional | Sort order within a location group (lower = higher). Promotes/demotes an action toward the record_header primary button; stable, so actions without `order` keep their registration order. | +| **confirmText** | `string` | optional | Confirmation message before execution | +| **successMessage** | `string` | optional | Success message to show after execution | +| **errorMessage** | `string` | optional | Error message to show when the action fails (overrides the raw error). | +| **refreshAfter** | `boolean` | optional | Refresh view after execution | +| **undoable** | `boolean` | optional | Offer an Undo affordance after this single-record update action succeeds. | +| **resultDialog** | `Object` | optional | Render API response in a one-shot reveal dialog (suppresses successMessage when set). | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). | +| **requiresFeature** | `Enum<'twoFactor' \| 'passkeys' \| 'magicLink' \| 'organization' \| 'multiOrgEnabled' \| 'degradedTenancy' \| 'oidcProvider' \| 'sso' \| 'ssoEnforced' \| 'deviceAuthorization' \| 'admin' \| 'phoneNumber' \| 'phoneNumberOtp'>` | optional | Public auth feature flag gating this action; lowered into `visible` at parse time. | +| **disabled** | `boolean \| string \| Object` | optional | Boolean or predicate (CEL) — action is disabled when TRUE. | +| **requiredPermissions** | `string[]` | optional | [ADR-0066 D4] Capabilities required to invoke this action (server-enforced 403 + UI hide/disable). | +| **shortcut** | `string` | optional | Keyboard shortcut to trigger this action (e.g., "Ctrl+S") | +| **bulkEnabled** | `boolean` | optional | Whether this action can be applied to multiple selected records | +| **ai** | `Object` | optional | AI exposure (opt-in). Set ai.exposed=true + ai.description to make this callable by agents. | +| **recordIdParam** | `string` | optional | Body key to inject the row id into when running from a list_item context. | +| **recordIdField** | `string` | optional | Row field whose value seeds recordIdParam. Defaults to "id". | +| **bodyShape** | `string \| Object` | optional | Body wrapping: flat (default) or `{ wrap: key }` to nest user-collected params under a key. | +| **method** | `Enum<'POST' \| 'PATCH' \| 'PUT' \| 'DELETE'>` | optional | HTTP method for type:"api" actions. Defaults to POST. | +| **bodyExtra** | `Record` | optional | Constant body fields merged into the API request (applied last; overrides user params). | +| **mode** | `Enum<'create' \| 'edit' \| 'delete' \| 'custom'>` | optional | Semantic mode of the action. | +| **opensInNewTab** | `boolean` | optional | Open the action result in a new tab. The renderer pre-opens the tab synchronously on click (popup-blocker-safe) and navigates it to the handler's redirectUrl. | +| **newTabUrl** | `string` | optional | Direct new-tab URL template (`{recordId}` placeholder). When set with opensInNewTab, the renderer navigates the pre-opened tab here immediately — no action POST. The endpoint must enforce auth itself. | +| **timeout** | `number` | optional | Maximum execution time in milliseconds for the action | +| **aria** | `Object` | optional | ARIA accessibility attributes | + + --- ## ActionAi @@ -86,6 +133,29 @@ const result = ActionAi.parse(data); * `global_nav` +--- + +## ActionParam + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | | +| **field** | `string` | optional | Snake case identifier (lowercase with underscores only) | +| **objectOverride** | `string` | optional | Snake case identifier (lowercase with underscores only) | +| **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | +| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'user' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'composite' \| 'repeater' \| 'record' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | optional | | +| **required** | `boolean` | optional | | +| **options** | `Object[]` | optional | | +| **placeholder** | `string` | optional | | +| **helpText** | `string` | optional | | +| **defaultValue** | `any` | optional | | +| **defaultFromRow** | `boolean` | optional | | +| **visible** | `string \| Object` | optional | Param visibility predicate (CEL); omits the param when false. | +| **requiresFeature** | `Enum<'twoFactor' \| 'passkeys' \| 'magicLink' \| 'organization' \| 'multiOrgEnabled' \| 'degradedTenancy' \| 'oidcProvider' \| 'sso' \| 'ssoEnforced' \| 'deviceAuthorization' \| 'admin' \| 'phoneNumber' \| 'phoneNumberOtp'>` | optional | Public auth feature flag gating this param; lowered into `visible` at parse time. | + + --- ## ActionType diff --git a/content/docs/references/ui/app.mdx b/content/docs/references/ui/app.mdx index 106aff2f00..5cefe27efe 100644 --- a/content/docs/references/ui/app.mdx +++ b/content/docs/references/ui/app.mdx @@ -34,13 +34,73 @@ Navigation item IDs are used in URLs and configuration and must be lowercase sna ## TypeScript Usage ```typescript -import { AppBranding, AppContextSelector } from '@objectstack/spec/ui'; -import type { AppBranding, AppContextSelector } from '@objectstack/spec/ui'; +import { ActionNavItem, App, AppBranding, AppContextSelector, ComponentNavItem, DashboardNavItem, GroupNavItem, NavigationArea, NavigationContribution, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui'; +import type { ActionNavItem, App, AppBranding, AppContextSelector, ComponentNavItem, DashboardNavItem, GroupNavItem, NavigationArea, NavigationContribution, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui'; // Validate data -const result = AppBranding.parse(data); +const result = ActionNavItem.parse(data); ``` +--- + +## ActionNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **actionDef** | `Object` | ✅ | Action definition to execute when clicked | + + +--- + +## App + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | App unique machine name (lowercase snake_case) | +| **label** | `string` | ✅ | App display label | +| **version** | `string` | optional | App version | +| **description** | `string` | optional | App description | +| **icon** | `string` | optional | App icon used in the App Launcher | +| **branding** | `Object` | optional | App-specific branding | +| **active** | `boolean` | optional | Whether the app is enabled | +| **isDefault** | `boolean` | optional | Is default app | +| **hidden** | `boolean` | optional | Hide from the App Switcher; the shell surfaces hidden apps via the avatar menu instead | +| **navigation** | `[__schema0](./__schema0)[]` | optional | Full navigation tree for the app sidebar | +| **areas** | `Object[]` | optional | Navigation areas for partitioning navigation by business domain | +| **contextSelectors** | `Object[]` | optional | App-level scope dropdowns whose value is injected into nav items as `{}` template vars | +| **homePageId** | `string` | optional | ID of the navigation item to serve as landing page | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this app | +| **objects** | `any[]` | optional | Objects belonging to this app | +| **apis** | `any[]` | optional | Custom APIs belonging to this app | +| **sharing** | `Object` | optional | Public sharing configuration | +| **embed** | `Object` | optional | Iframe embedding configuration | +| **mobileNavigation** | `Object` | optional | Mobile-specific navigation configuration | +| **defaultAgent** | `string` | optional | Name of the default AI agent for this app (used by the ambient chat endpoint) | +| **aria** | `Object` | optional | ARIA accessibility attributes for the application | +| **protection** | `Object` | optional | Package author protection block — lock policy for this app. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + + --- ## AppBranding @@ -74,3 +134,385 @@ const result = AppBranding.parse(data); --- +## ComponentNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **componentRef** | `string` | ✅ | Component registry key (e.g. "metadata:directory") | +| **params** | `Record` | optional | Props passed to the component | + + +--- + +## DashboardNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **dashboardName** | `string` | ✅ | Target dashboard name | + + +--- + +## GroupNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **expanded** | `boolean` | optional | Default expansion state in sidebar | + + +--- + +## NavigationArea + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique area identifier (lowercase snake_case) | +| **label** | `string` | ✅ | Area display label | +| **icon** | `string` | optional | Area icon name | +| **order** | `number` | optional | Sort order among areas (lower = first) | +| **description** | `string` | optional | Area description | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL) for this area. | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this area | +| **navigation** | `[__schema0](./__schema0)[]` | ✅ | Navigation items within this area | + + +--- + +## NavigationContribution + +A navigation contribution: a package injecting nav items into an app it does not own (ADR-0029 D7) + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **app** | `string` | ✅ | Target app name to contribute navigation into (e.g. "setup") | +| **group** | `string` | optional | Target group nav-item id to append into (e.g. "group_integrations"); omit to append at the app top level | +| **priority** | `integer` | optional | Merge priority within the target group — lower applied first (matches object extender priority) | +| **items** | `[__schema0](./__schema0)[]` | ✅ | Navigation items contributed into the target app/group | + + +--- + +## NavigationItem + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +**Type:** `object` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **viewName** | `string` | optional | Default list view to open. Defaults to "all". Ignored when `recordId` is set. | +| **recordId** | `string` | optional | Navigate directly to this record id instead of the list view. Supports template vars: `{current_user_id}`, `{current_org_id}`. | +| **recordMode** | `Enum<'view' \| 'edit'>` | optional | Open the record in view (default) or edit mode. Only meaningful when `recordId` is set. | +| **filters** | `Record` | optional | URL filter conditions — targets the /:objectName/data bare surface via filter[``]=`` params instead of a saved view. Values support template vars `{current_user_id}`, `{current_org_id}`. Mutually exclusive with recordId/viewName. | +| **children** | `[#](./#)[]` | optional | Child navigation items (e.g. specific views) | + +--- + +#### Option 2 + +**Type:** `dashboard` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **dashboardName** | `string` | ✅ | Target dashboard name | + +--- + +#### Option 3 + +**Type:** `page` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **pageName** | `string` | ✅ | Target custom page component name | +| **params** | `Record` | optional | Parameters passed to the page context | + +--- + +#### Option 4 + +**Type:** `url` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **url** | `string` | ✅ | Target external URL | +| **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | + +--- + +#### Option 5 + +**Type:** `report` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **reportName** | `string` | ✅ | Target report name | + +--- + +#### Option 6 + +**Type:** `action` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **actionDef** | `Object` | ✅ | Action definition to execute when clicked | + +--- + +#### Option 7 + +**Type:** `component` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **componentRef** | `string` | ✅ | Component registry key (e.g. "metadata:directory") | +| **params** | `Record` | optional | Props passed to the component | + +--- + +#### Option 8 + +**Type:** `group` + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **expanded** | `boolean` | optional | Default expansion state in sidebar | +| **children** | `[#](./#)[]` | ✅ | Child navigation items | + +--- + + +--- + +## ObjectNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **objectName** | `string` | ✅ | Target object name | +| **viewName** | `string` | optional | Default list view to open. Defaults to "all". Ignored when `recordId` is set. | +| **recordId** | `string` | optional | Navigate directly to this record id instead of the list view. Supports template vars: `{current_user_id}`, `{current_org_id}`. | +| **recordMode** | `Enum<'view' \| 'edit'>` | optional | Open the record in view (default) or edit mode. Only meaningful when `recordId` is set. | +| **filters** | `Record` | optional | URL filter conditions — targets the /:objectName/data bare surface via filter[``]=`` params instead of a saved view. Values support template vars `{current_user_id}`, `{current_org_id}`. Mutually exclusive with recordId/viewName. | + + +--- + +## PageNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **pageName** | `string` | ✅ | Target custom page component name | +| **params** | `Record` | optional | Parameters passed to the page context | + + +--- + +## ReportNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **reportName** | `string` | ✅ | Target report name | + + +--- + +## UrlNavItem + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | +| **label** | `string` | ✅ | Display proper label | +| **icon** | `string` | optional | Icon name | +| **order** | `number` | optional | Sort order within the same level (lower = first) | +| **badge** | `string \| number` | optional | Badge text or count displayed on the item | +| **visible** | `string \| Object` | optional | Visibility predicate (CEL). e.g. P`'org_admin' in current_user.positions` | +| **requiredPermissions** | `string[]` | optional | Permissions required to access this item | +| **requiresObject** | `string` | optional | Hide/disable this entry unless the named object is registered in the runtime | +| **requiresService** | `string` | optional | Hide/disable this entry unless the named kernel service is registered | +| **type** | `string` | ✅ | | +| **url** | `string` | ✅ | Target external URL | +| **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | + + +--- + diff --git a/content/docs/references/ui/component.mdx b/content/docs/references/ui/component.mdx index f859646173..539b251007 100644 --- a/content/docs/references/ui/component.mdx +++ b/content/docs/references/ui/component.mdx @@ -14,8 +14,8 @@ Empty Properties Schema ## TypeScript Usage ```typescript -import { AIChatWindowProps, ElementButtonProps, ElementFilterProps, ElementImageProps, ElementMetadataViewerProps, ElementNumberProps, ElementRecordPickerProps, ElementTextInputProps, ElementTextProps, PageAccordionProps, PageCardProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordPathProps, RecordRelatedListProps } from '@objectstack/spec/ui'; -import type { AIChatWindowProps, ElementButtonProps, ElementFilterProps, ElementImageProps, ElementMetadataViewerProps, ElementNumberProps, ElementRecordPickerProps, ElementTextInputProps, ElementTextProps, PageAccordionProps, PageCardProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordPathProps, RecordRelatedListProps } from '@objectstack/spec/ui'; +import { AIChatWindowProps, ElementButtonProps, ElementFilterProps, ElementFormProps, ElementImageProps, ElementMetadataViewerProps, ElementNumberProps, ElementRecordPickerProps, ElementTextInputProps, ElementTextProps, PageAccordionProps, PageCardProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordPathProps, RecordRelatedListProps } from '@objectstack/spec/ui'; +import type { AIChatWindowProps, ElementButtonProps, ElementFilterProps, ElementFormProps, ElementImageProps, ElementMetadataViewerProps, ElementNumberProps, ElementRecordPickerProps, ElementTextInputProps, ElementTextProps, PageAccordionProps, PageCardProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordPathProps, RecordRelatedListProps } from '@objectstack/spec/ui'; // Validate data const result = AIChatWindowProps.parse(data); @@ -68,6 +68,22 @@ const result = AIChatWindowProps.parse(data); | **aria** | `Object` | optional | ARIA accessibility attributes | +--- + +## ElementFormProps + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **object** | `string` | ✅ | Object for the form | +| **fields** | `string[]` | optional | Fields to display (defaults to all editable fields) | +| **mode** | `Enum<'create' \| 'edit'>` | optional | Form mode | +| **submitLabel** | `string` | optional | Submit button label | +| **onSubmit** | `string \| Object` | optional | Action expression on form submit (CEL) | +| **aria** | `Object` | optional | ARIA accessibility attributes | + + --- ## ElementImageProps @@ -91,7 +107,7 @@ const result = AIChatWindowProps.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `Enum<'state_machine' \| 'flow' \| 'permission'>` | ✅ | Metadata view kind (ADR-0051): state_machine | flow | permission | +| **type** | `Enum<'state_machine' \| 'flow' \| 'permission'>` | ✅ | Metadata view kind (ADR-0051): state_machine \| flow \| permission | | **name** | `string` | ✅ | Target metadata item name; resolved package-scoped (ADR-0048), then dependencies (ADR-0046 §3.3) | | **object** | `string` | optional | Owning object — required for object-scoped kinds: state_machine is a rule ON an object (ADR-0020), permission renders a matrix FOR one; omit for top-level flow | | **mode** | `Enum<'diagram' \| 'matrix' \| 'summary'>` | optional | Render form; defaults per type (diagram for flow/state_machine, matrix for permission) | @@ -221,8 +237,8 @@ const result = AIChatWindowProps.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `Enum<'line' \| 'card' \| 'pill'>` | ✅ | | -| **position** | `Enum<'top' \| 'left'>` | ✅ | | +| **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | | +| **position** | `Enum<'top' \| 'left'>` | optional | | | **items** | `Object[]` | ✅ | | | **aria** | `Object` | optional | ARIA accessibility attributes | diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx index 32f968a405..972959a72a 100644 --- a/content/docs/references/ui/dashboard.mdx +++ b/content/docs/references/ui/dashboard.mdx @@ -44,8 +44,8 @@ const result = Dashboard.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this dashboard. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/ui/dataset.mdx b/content/docs/references/ui/dataset.mdx index fb98a3b0bf..235afe3b46 100644 --- a/content/docs/references/ui/dataset.mdx +++ b/content/docs/references/ui/dataset.mdx @@ -72,8 +72,8 @@ const result = Dataset.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this dataset. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/ui/page.mdx b/content/docs/references/ui/page.mdx index d96ee68eec..c9cc413060 100644 --- a/content/docs/references/ui/page.mdx +++ b/content/docs/references/ui/page.mdx @@ -16,8 +16,8 @@ A named region in the template where components are dropped. ## TypeScript Usage ```typescript -import { ElementDataSource, InterfacePageConfig, PageComponentType, PageType, PageVariable } from '@objectstack/spec/ui'; -import type { ElementDataSource, InterfacePageConfig, PageComponentType, PageType, PageVariable } from '@objectstack/spec/ui'; +import { ElementDataSource, InterfacePageConfig, Page, PageComponent, PageComponentType, PageRegion, PageType, PageVariable } from '@objectstack/spec/ui'; +import type { ElementDataSource, InterfacePageConfig, Page, PageComponent, PageComponentType, PageRegion, PageType, PageVariable } from '@objectstack/spec/ui'; // Validate data const result = ElementDataSource.parse(data); @@ -59,11 +59,61 @@ Interface-level page configuration (Airtable parity) | **userActions** | `Object` | optional | User action toggles | | **addRecord** | `Object` | optional | Add record entry point configuration | | **buttons** | `string[]` | optional | Toolbar buttons — names of the source object's actions to surface in the page toolbar | -| **recordAction** | `Enum<'drawer' \| 'page' \| 'modal' \| 'none'>` | optional | How clicking a record opens its detail (drawer | page | modal | none). Default: drawer | +| **recordAction** | `Enum<'drawer' \| 'page' \| 'modal' \| 'none'>` | optional | How clicking a record opens its detail (drawer \| page \| modal \| none). Default: drawer | | **showRecordCount** | `boolean` | optional | Show record count at page bottom | | **allowPrinting** | `boolean` | optional | Allow users to print the page | +--- + +## Page + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Page unique name (lowercase snake_case) | +| **label** | `string` | ✅ | Display label (plain string; i18n keys are auto-generated by the framework) | +| **description** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | +| **icon** | `string` | optional | Page icon name | +| **type** | `Enum<'record' \| 'home' \| 'app' \| 'utility' \| 'list'>` | optional | Page type | +| **variables** | `Object[]` | optional | Local page state, exposed to expressions as `page.` and writable by interactive elements via `source` (master/detail, filtered dashboards). | +| **object** | `string` | optional | Bound object (for Record pages) | +| **template** | `string` | optional | Layout template name (e.g. "header-sidebar-main") | +| **regions** | `Object[]` | optional | Layout regions (header, main, sidebar, footer) with their components. Optional — list pages use interfaceConfig, slotted pages use slots, and an empty full page falls back to the synthesized default layout. | +| **isDefault** | `boolean` | optional | | +| **assignedProfiles** | `string[]` | optional | | +| **interfaceConfig** | `Object` | optional | Interface-level page configuration (for Airtable-style interface pages) | +| **aria** | `Object` | optional | ARIA accessibility attributes | +| **kind** | `Enum<'full' \| 'slotted' \| 'html' \| 'react' \| 'jsx'>` | optional | Page override mode. full \| slotted = structured authoring; html = author-written constrained JSX/HTML+Tailwind compiled (parsed, never executed) to the tree (ADR-0080; the legacy value 'jsx' is a deprecated alias); react = real-React source executed at render by the runtime (ADR-0081); it runs author JS, so it is gated by a host capability that defaults ON and is disabled server-side via the OS_PAGE_REACT=off env toggle. | +| **slots** | `Object` | optional | Slot override map for slotted pages | +| **source** | `string` | optional | Page source text. For kind==='html' (alias 'jsx') it is constrained JSX/HTML+Tailwind compiled to the tree by @objectstack/sdui-parser at save time (parse, never execute). For kind==='react' it is real React/JSX executed at render by @object-ui/react-runtime (trusted tier). Authoritative over `regions` in both. | +| **requires** | `string[]` | optional | Plugin namespaces the JSX source references (validated at save and load) | + + +--- + +## PageComponent + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'page:header' \| 'page:footer' \| 'page:sidebar' \| 'page:tabs' \| 'page:accordion' \| 'page:card' \| 'page:section' \| 'record:details' \| 'record:highlights' \| 'record:related_list' \| 'record:activity' \| 'record:chatter' \| 'record:path' \| 'record:alert' \| 'record:quick_actions' \| 'record:reference_rail' \| 'record:history' \| 'app:launcher' \| 'nav:menu' \| 'nav:breadcrumb' \| 'global:search' \| 'global:notifications' \| 'user:profile' \| 'ai:chat_window' \| 'ai:suggestion' \| 'element:text' \| 'element:number' \| 'element:image' \| 'element:divider' \| 'element:button' \| 'element:filter' \| 'element:form' \| 'element:record_picker' \| 'element:text_input'> \| string` | ✅ | Component Type (Standard enum or custom string) | +| **id** | `string` | optional | Unique instance ID | +| **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | +| **properties** | `Record` | optional | Component props passed to the widget. See component.zod.ts for schemas. | +| **events** | `Record` | optional | Event handlers map | +| **style** | `Record` | optional | Inline styles or utility classes | +| **className** | `string` | optional | CSS class names | +| **responsiveStyles** | `Object` | optional | Per-breakpoint scoped style maps (ADR-0065) | +| **visibleWhen** | `string \| Object` | optional | Visibility predicate (CEL) — component rendered only when TRUE. Binds `record`, `current_user`, `page.`. e.g. "page.selectedProjectId != ''" | +| **visibility** | `string \| Object` | optional | [DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Normalized to `visibleWhen` at parse. | +| **dataSource** | `Object` | optional | Per-element data binding for multi-object pages | +| **responsive** | `Object` | optional | Responsive layout configuration | +| **aria** | `Object` | optional | ARIA accessibility attributes | + + --- ## PageComponentType @@ -106,6 +156,19 @@ Interface-level page configuration (Airtable parity) * `element:text_input` +--- + +## PageRegion + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | ✅ | Region name (e.g. "sidebar", "main", "header") | +| **width** | `Enum<'small' \| 'medium' \| 'large' \| 'full'>` | optional | | +| **components** | `Object[]` | ✅ | Components in this region | + + --- ## PageType diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx index 619a47ba07..ab8e9d2417 100644 --- a/content/docs/references/ui/report.mdx +++ b/content/docs/references/ui/report.mdx @@ -66,8 +66,8 @@ const result = JoinedReportBlock.parse(data); | **protection** | `Object` | optional | Package author protection block — lock policy for this report. | | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | -| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). | -| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | | **_packageId** | `string` | optional | Owning package machine id. | | **_packageVersion** | `string` | optional | Owning package version. | | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | diff --git a/content/docs/references/ui/view.mdx b/content/docs/references/ui/view.mdx index fee7198aea..e3fd4c9d64 100644 --- a/content/docs/references/ui/view.mdx +++ b/content/docs/references/ui/view.mdx @@ -16,8 +16,8 @@ Migrated to shared/http.zod.ts. Re-exported here for backward compatibility. ## TypeScript Usage ```typescript -import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui'; -import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui'; +import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormField, FormSection, FormView, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, ListView, NavigationConfig, NavigationMode, ObjectListView, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, View, ViewData, ViewFilterRule, ViewItem, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui'; +import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormField, FormSection, FormView, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, ListView, NavigationConfig, NavigationMode, ObjectListView, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, View, ViewData, ViewFilterRule, ViewItem, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui'; // Validate data const result = AddRecordConfig.parse(data); @@ -88,6 +88,96 @@ Aggregation function for column footer summary * `max` +--- + +## FormField + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **field** | `string` | ✅ | Field name (snake_case) | +| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'user' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'composite' \| 'repeater' \| 'record' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | optional | Field type (auto-infers widget if omitted) | +| **options** | `Object[]` | optional | Options for select/multiselect/radio/checkboxes fields | +| **reference** | `string` | optional | Target object name for lookup/master_detail fields | +| **maxLength** | `number` | optional | Maximum character length (for text/textarea/email/url/phone) | +| **minLength** | `number` | optional | Minimum character length | +| **min** | `number` | optional | Minimum value (for number/currency/percent/slider) | +| **max** | `number` | optional | Maximum value | +| **precision** | `number` | optional | Total digits (for number/currency) | +| **scale** | `number` | optional | Decimal places | +| **multiple** | `boolean` | optional | Allow multiple values (for select/lookup/file/image) | +| **label** | `string` | optional | Display label override | +| **placeholder** | `string` | optional | Placeholder text | +| **helpText** | `string` | optional | Help/hint text | +| **readonly** | `boolean` | optional | Read-only override | +| **immutable** | `boolean` | optional | Editable on create, locked once the record exists (e.g. machine names). | +| **required** | `boolean` | optional | Required override | +| **hidden** | `boolean` | optional | Hidden override | +| **colSpan** | `integer` | optional | [legacy — prefer `span`] Absolute column span (1-4). Fragile when the column count is derived per surface (mobile 1 / modal 2 / page 3-4): a fixed span only lines up at the width the author imagined. The renderer clamps it to the current column count. Prefer `span`. | +| **span** | `Enum<'auto' \| 'full'>` | optional | Relative field width. 'auto' (default — omit it): the renderer sizes the field from its widget type × the current column count (wide widgets like textarea/richtext/json/file/subform take the whole row). 'full': whole row at any column count. Prefer this over the absolute `colSpan`. | +| **widget** | `string` | optional | Custom widget/component name (overrides type-based inference) | +| **language** | `string` | optional | Code editor language (for type=code) | +| **fields** | `[#](./#)[]` | optional | Sub-fields for composite/repeater/record types | +| **keyField** | `Object` | optional | Key column config for record-typed fields | +| **dependsOn** | `string` | optional | Parent field name for cascading | +| **visibleWhen** | `string \| Object` | optional | Visibility predicate (CEL) — field shown only when TRUE. Root: `record`+`current_user` (runtime forms) or `data` (metadata forms). e.g. P`record.priority == 'urgent'` | +| **visibleOn** | `string \| Object` | optional | [DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Normalized to `visibleWhen` at parse. | +| **disclosure** | `Enum<'inline' \| 'popover'>` | optional | Composite rendering: inline bordered box (default) or a summary line + gear popover (progressive disclosure). | + + +--- + +## FormSection + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Stable section identifier for i18n lookup (snake_case) | +| **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | +| **description** | `string` | optional | Optional description rendered under the section header. | +| **collapsible** | `boolean` | optional | | +| **collapsed** | `boolean` | optional | | +| **visibleWhen** | `string \| Object` | optional | Visibility predicate (CEL) — section shown only when TRUE. Root: `record`+`current_user` (runtime forms) or `data` (metadata forms). | +| **visibleOn** | `string \| Object` | optional | [DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Hides the whole section when false. Normalized to `visibleWhen` at parse. | +| **columns** | `Enum<'1' \| '2' \| '3' \| '4'> \| number \| number \| number \| number` | optional | | +| **fields** | `string \| [__schema0](./__schema0)[]` | ✅ | | + + +--- + +## FormView + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **type** | `Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>` | optional | | +| **layout** | `Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>` | optional | Field layout direction | +| **columns** | `integer` | optional | Number of columns for the form body | +| **title** | `string` | optional | Form title | +| **description** | `string` | optional | Form description | +| **defaultTab** | `string` | optional | Initially active tab (tabbed forms) | +| **tabPosition** | `Enum<'top' \| 'bottom' \| 'left' \| 'right'>` | optional | Tab strip position (tabbed forms) | +| **allowSkip** | `boolean` | optional | Allow skipping steps (wizard forms) | +| **showStepIndicator** | `boolean` | optional | Show the step indicator (wizard forms) | +| **splitDirection** | `Enum<'horizontal' \| 'vertical'>` | optional | Split orientation (split forms) | +| **splitSize** | `number` | optional | Primary split panel size, % (split forms) | +| **splitResizable** | `boolean` | optional | Whether the split is resizable (split forms) | +| **drawerSide** | `Enum<'top' \| 'bottom' \| 'left' \| 'right'>` | optional | Drawer side (drawer forms) | +| **drawerWidth** | `string` | optional | [DEPRECATED → size buckets] Drawer width, e.g. "480px". A pixel width cannot be chosen without knowing the client viewport — the renderer derives it. | +| **modalSize** | `Enum<'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'>` | optional | Modal size (modal forms) | +| **data** | `Object \| Object \| Object \| Object` | optional | Data source configuration (defaults to "object" provider) | +| **sections** | `Object[]` | optional | | +| **groups** | `Object[]` | optional | | +| **subforms** | `Object[]` | optional | Inline master-detail child collections | +| **defaultSort** | `Object[]` | optional | Default sort order for related list views within this form | +| **sharing** | `Object` | optional | Public sharing configuration for this form | +| **submitBehavior** | `Object \| Object \| Object \| Object` | optional | Post-submit behavior | +| **aria** | `Object` | optional | ARIA accessibility attributes for the form view | + + --- ## GalleryConfig @@ -224,6 +314,64 @@ List chart view configuration | **action** | `string` | optional | Registered Action ID to execute when clicked | +--- + +## ListView + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Internal view name (lowercase snake_case) | +| **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | +| **type** | `Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>` | optional | | +| **data** | `Object \| Object \| Object \| Object` | optional | Data source configuration (defaults to "object" provider) | +| **columns** | `string[] \| Object[]` | ✅ | Fields to display as columns | +| **filter** | `Object[]` | optional | Filter criteria (JSON Rules) | +| **sort** | `string \| Object[]` | optional | | +| **searchableFields** | `string[]` | optional | Fields enabled for search | +| **filterableFields** | `string[]` | optional | Legacy shorthand for userFilters.fields — bare field names enabled for end-user filtering. Prefer userFilters | +| **userFilters** | `Object` | optional | End-user quick-filter bar: dropdown/toggle fields or tab presets. Omit to let the renderer derive filters from select/boolean fields | +| **resizable** | `boolean` | optional | Enable column resizing | +| **striped** | `boolean` | optional | Striped row styling | +| **bordered** | `boolean` | optional | Show borders | +| **compactToolbar** | `boolean` | optional | Collapse Group/Color/Density/Hide-fields into a single View settings popover | +| **selection** | `Object` | optional | Row selection configuration | +| **navigation** | `Object` | optional | Configuration for item click navigation (page, drawer, modal, etc.) | +| **pagination** | `Object` | optional | Pagination configuration | +| **kanban** | `Object` | optional | | +| **calendar** | `Object` | optional | | +| **gantt** | `Record` | optional | | +| **gallery** | `Object` | optional | Gallery/card view configuration | +| **timeline** | `Object` | optional | Timeline view configuration | +| **chart** | `Object` | optional | List chart view configuration | +| **tree** | `Record` | optional | | +| **description** | `string` | optional | View description for documentation/tooltips | +| **sharing** | `Object` | optional | View sharing and access configuration | +| **rowHeight** | `Enum<'compact' \| 'short' \| 'medium' \| 'tall' \| 'extra_tall'>` | optional | Row height / density setting | +| **grouping** | `Object` | optional | Group records by one or more fields | +| **rowColor** | `Object` | optional | Color rows based on field value | +| **hiddenFields** | `string[]` | optional | Fields to hide in this specific view | +| **fieldOrder** | `string[]` | optional | Explicit field display order for this view | +| **rowActions** | `string[]` | optional | Actions available for individual row items | +| **bulkActions** | `string[]` | optional | Actions available when multiple rows are selected | +| **bulkActionDefs** | `Record[]` | optional | Rich bulk action definitions (schema-driven, executed via BulkActionDialog) | +| **virtualScroll** | `boolean` | optional | Enable virtual scrolling for large datasets | +| **conditionalFormatting** | `Object[]` | optional | Conditional formatting rules for list rows | +| **inlineEdit** | `boolean` | optional | Allow inline editing of records directly in the list view | +| **exportOptions** | `Enum<'csv' \| 'xlsx' \| 'pdf' \| 'json'>[]` | optional | Available export format options | +| **userActions** | `Object` | optional | User action toggles for the view toolbar | +| **appearance** | `Object` | optional | Appearance and visualization configuration | +| **tabs** | `Object[]` | optional | Tab definitions for multi-tab view interface | +| **addRecord** | `Object` | optional | Add record entry point configuration | +| **showRecordCount** | `boolean` | optional | Show record count at the bottom of the list | +| **allowPrinting** | `boolean` | optional | Allow users to print the view | +| **emptyState** | `Object` | optional | Empty state configuration when no records found | +| **aria** | `Object` | optional | ARIA accessibility attributes for the list view | +| **responsive** | `Object` | optional | Responsive layout configuration | +| **performance** | `Object` | optional | Performance optimization settings | + + --- ## NavigationConfig @@ -255,6 +403,64 @@ List chart view configuration * `none` +--- + +## ObjectListView + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **name** | `string` | optional | Internal view name (lowercase snake_case) | +| **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | +| **type** | `Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>` | optional | | +| **data** | `Object \| Object \| Object \| Object` | optional | Data source configuration (defaults to "object" provider) | +| **columns** | `string[] \| Object[]` | ✅ | Fields to display as columns | +| **filter** | `Object[]` | optional | Filter criteria (JSON Rules) | +| **sort** | `string \| Object[]` | optional | | +| **searchableFields** | `string[]` | optional | Fields enabled for search | +| **filterableFields** | `string[]` | optional | Legacy shorthand for userFilters.fields — bare field names enabled for end-user filtering. Prefer userFilters | +| **resizable** | `boolean` | optional | Enable column resizing | +| **striped** | `boolean` | optional | Striped row styling | +| **bordered** | `boolean` | optional | Show borders | +| **compactToolbar** | `boolean` | optional | Collapse Group/Color/Density/Hide-fields into a single View settings popover | +| **selection** | `Object` | optional | Row selection configuration | +| **navigation** | `Object` | optional | Configuration for item click navigation (page, drawer, modal, etc.) | +| **pagination** | `Object` | optional | Pagination configuration | +| **kanban** | `Object` | optional | | +| **calendar** | `Object` | optional | | +| **gantt** | `Record` | optional | | +| **gallery** | `Object` | optional | Gallery/card view configuration | +| **timeline** | `Object` | optional | Timeline view configuration | +| **chart** | `Object` | optional | List chart view configuration | +| **tree** | `Record` | optional | | +| **description** | `string` | optional | View description for documentation/tooltips | +| **sharing** | `Object` | optional | View sharing and access configuration | +| **rowHeight** | `Enum<'compact' \| 'short' \| 'medium' \| 'tall' \| 'extra_tall'>` | optional | Row height / density setting | +| **grouping** | `Object` | optional | Group records by one or more fields | +| **rowColor** | `Object` | optional | Color rows based on field value | +| **hiddenFields** | `string[]` | optional | Fields to hide in this specific view | +| **fieldOrder** | `string[]` | optional | Explicit field display order for this view | +| **rowActions** | `string[]` | optional | Actions available for individual row items | +| **bulkActions** | `string[]` | optional | Actions available when multiple rows are selected | +| **bulkActionDefs** | `Record[]` | optional | Rich bulk action definitions (schema-driven, executed via BulkActionDialog) | +| **virtualScroll** | `boolean` | optional | Enable virtual scrolling for large datasets | +| **conditionalFormatting** | `Object[]` | optional | Conditional formatting rules for list rows | +| **inlineEdit** | `boolean` | optional | Allow inline editing of records directly in the list view | +| **exportOptions** | `Enum<'csv' \| 'xlsx' \| 'pdf' \| 'json'>[]` | optional | Available export format options | +| **userActions** | `Object` | optional | User action toggles for the view toolbar | +| **appearance** | `Object` | optional | Appearance and visualization configuration | +| **tabs** | `Object[]` | optional | Tab definitions for multi-tab view interface | +| **addRecord** | `Object` | optional | Add record entry point configuration | +| **showRecordCount** | `boolean` | optional | Show record count at the bottom of the list | +| **allowPrinting** | `boolean` | optional | Allow users to print the view | +| **emptyState** | `Object` | optional | Empty state configuration when no records found | +| **aria** | `Object` | optional | ARIA accessibility attributes for the list view | +| **responsive** | `Object` | optional | Responsive layout configuration | +| **performance** | `Object` | optional | Performance optimization settings | +| **userFilters** | `Object` | optional | | + + --- ## ObjectUserFilters @@ -404,6 +610,28 @@ End-user quick-filter configuration (Airtable "User filters" parity) | **showAllRecords** | `boolean` | optional | Show an "All records" tab before the presets (tabs element) | +--- + +## View + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **list** | `Object` | optional | | +| **form** | `Object` | optional | | +| **listViews** | `Record` | optional | Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047) | +| **formViews** | `Record` | optional | Additional named form views | +| **protection** | `Object` | optional | Package author protection block — lock policy for this view. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + + --- ## ViewData @@ -474,6 +702,69 @@ View filter rule | **value** | `string \| number \| boolean \| null \| string \| number[]` | optional | Filter value | +--- + +## ViewItem + +### Union Options + +This schema accepts one of the following structures: + +#### Option 1 + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **viewKind** | `string` | ✅ | | +| **config** | `Object` | ✅ | List-family view configuration. | +| **name** | `string` | ✅ | Globally-unique view id, `.`. | +| **object** | `string` | ✅ | Bound object name — the foreign key used to aggregate views. | +| **label** | `string` | optional | Display label (supports i18n). | +| **isDefault** | `boolean` | optional | Whether this is the object's default view in the switcher. | +| **order** | `integer` | optional | Sort order within the object's view switcher / left rail. | +| **scope** | `Enum<'package' \| 'shared' \| 'personal'>` | optional | Identity layer (defaults to `package` for source-loaded views). | +| **owner** | `string` | optional | Owner user id — set when `scope` is `personal`. | +| **hidden** | `boolean` | optional | Hidden from the switcher (per-user / per-org declutter). | +| **protection** | `Object` | optional | Package author protection block — lock policy for this view. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + +--- + +#### Option 2 + +### Properties + +| Property | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| **viewKind** | `string` | ✅ | | +| **config** | `Object` | ✅ | Form view configuration. | +| **name** | `string` | ✅ | Globally-unique view id, `.`. | +| **object** | `string` | ✅ | Bound object name — the foreign key used to aggregate views. | +| **label** | `string` | optional | Display label (supports i18n). | +| **isDefault** | `boolean` | optional | Whether this is the object's default view in the switcher. | +| **order** | `integer` | optional | Sort order within the object's view switcher / left rail. | +| **scope** | `Enum<'package' \| 'shared' \| 'personal'>` | optional | Identity layer (defaults to `package` for source-loaded views). | +| **owner** | `string` | optional | Owner user id — set when `scope` is `personal`. | +| **hidden** | `boolean` | optional | Hidden from the switcher (per-user / per-org declutter). | +| **protection** | `Object` | optional | Package author protection block — lock policy for this view. | +| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). | +| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. | +| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). | +| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package \| org \| env-forced). | +| **_packageId** | `string` | optional | Owning package machine id. | +| **_packageVersion** | `string` | optional | Owning package version. | +| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. | + +--- + + --- diff --git a/packages/spec/json-schema.manifest.json b/packages/spec/json-schema.manifest.json new file mode 100644 index 0000000000..0eb394cc19 --- /dev/null +++ b/packages/spec/json-schema.manifest.json @@ -0,0 +1,1833 @@ +{ + "description": "Ratchet manifest of every JSON Schema emitted by scripts/build-schemas.ts. Auto-appended when new schemas are added (commit the change). A listed schema that a build no longer emits fails gen:schema — remove a key ONLY for a deliberate retirement. See #2978.", + "schemas": [ + "ai/AIKnowledge", + "ai/AIModelConfig", + "ai/AITool", + "ai/AIUsageRecord", + "ai/Agent", + "ai/BlueprintApp", + "ai/BlueprintDashboard", + "ai/BlueprintField", + "ai/BlueprintNavItem", + "ai/BlueprintObject", + "ai/BlueprintSeed", + "ai/BlueprintView", + "ai/BlueprintWidgetCondition", + "ai/CodeContent", + "ai/ConversationAnalytics", + "ai/ConversationContext", + "ai/ConversationMessage", + "ai/ConversationSession", + "ai/ConversationSummary", + "ai/EmbeddingModel", + "ai/FileContent", + "ai/FileKnowledgeSource", + "ai/FunctionCall", + "ai/HttpKnowledgeSource", + "ai/ImageContent", + "ai/KnowledgeChunk", + "ai/KnowledgeDocument", + "ai/KnowledgeHit", + "ai/KnowledgeRefreshPolicy", + "ai/KnowledgeSource", + "ai/KnowledgeSourceKind", + "ai/MCPApprovalPolicy", + "ai/MCPServerRef", + "ai/MCPToolBinding", + "ai/MCPTransport", + "ai/MessageContent", + "ai/MessageContentType", + "ai/MessagePruningEvent", + "ai/MessageRole", + "ai/ModelCapability", + "ai/ModelConfig", + "ai/ModelLimits", + "ai/ModelPricing", + "ai/ModelProvider", + "ai/ModelRegistry", + "ai/ModelRegistryEntry", + "ai/ModelSelectionCriteria", + "ai/ObjectKnowledgeSource", + "ai/PromptTemplate", + "ai/PromptVariable", + "ai/Skill", + "ai/SkillTriggerCondition", + "ai/SolutionBlueprint", + "ai/SolutionBlueprintStrict", + "ai/StructuredOutputConfig", + "ai/StructuredOutputFormat", + "ai/TextContent", + "ai/TokenBudgetConfig", + "ai/TokenBudgetStrategy", + "ai/TokenUsage", + "ai/TokenUsageStats", + "ai/Tool", + "ai/ToolCall", + "ai/ToolCategory", + "ai/TransformPipelineStep", + "ai/VectorStore", + "ai/VectorStoreProvider", + "api/AckMessage", + "api/AddReactionRequest", + "api/AddReactionResponse", + "api/AiInsightsRequest", + "api/AiInsightsResponse", + "api/AiNlqRequest", + "api/AiNlqResponse", + "api/AiSuggestRequest", + "api/AiSuggestResponse", + "api/AnalyticsEndpoint", + "api/AnalyticsMetadataResponse", + "api/AnalyticsQueryRequest", + "api/AnalyticsResultResponse", + "api/AnalyticsSqlResponse", + "api/ApiChangelogEntry", + "api/ApiDiscoveryQuery", + "api/ApiDiscoveryResponse", + "api/ApiDocumentationConfig", + "api/ApiEndpoint", + "api/ApiEndpointRegistration", + "api/ApiError", + "api/ApiMapping", + "api/ApiMetadata", + "api/ApiParameter", + "api/ApiProtocolType", + "api/ApiRegistry", + "api/ApiRegistryEntry", + "api/ApiResponse", + "api/ApiRoutes", + "api/ApiTestCollection", + "api/ApiTestRequest", + "api/ApiTestingUiConfig", + "api/ApiTestingUiType", + "api/AppDefinitionResponse", + "api/AuthEndpoint", + "api/AuthFeaturesConfig", + "api/AuthProvider", + "api/AuthProviderInfo", + "api/AutomationActionsResponse", + "api/AutomationApiErrorCode", + "api/AutomationFlowPathParams", + "api/AutomationRunPathParams", + "api/AutomationTriggerRequest", + "api/AutomationTriggerResponse", + "api/BasePresence", + "api/BaseResponse", + "api/BatchConfig", + "api/BatchDataRequest", + "api/BatchDataResponse", + "api/BatchEndpointsConfig", + "api/BatchLoadingStrategy", + "api/BatchOperationResult", + "api/BatchOperationType", + "api/BatchOptions", + "api/BatchRecord", + "api/BatchUpdateRequest", + "api/BatchUpdateResponse", + "api/BulkRequest", + "api/BulkResponse", + "api/CacheControl", + "api/CacheDirective", + "api/CacheInvalidationRequest", + "api/CacheInvalidationResponse", + "api/CacheInvalidationTarget", + "api/Callback", + "api/ChangelogEntry", + "api/CheckPermissionRequest", + "api/CheckPermissionResponse", + "api/CodeGenerationTemplate", + "api/CompleteChunkedUploadRequest", + "api/CompleteChunkedUploadResponse", + "api/CompleteUploadRequest", + "api/ConceptListResponse", + "api/ConflictResolutionStrategy", + "api/CreateDataRequest", + "api/CreateDataResponse", + "api/CreateExportJobRequest", + "api/CreateExportJobResponse", + "api/CreateFeedItemRequest", + "api/CreateFeedItemResponse", + "api/CreateFlowRequest", + "api/CreateFlowResponse", + "api/CreateImportJobRequest", + "api/CreateImportJobResponse", + "api/CreateManyDataRequest", + "api/CreateManyDataResponse", + "api/CreateRequest", + "api/CreateViewRequest", + "api/CreateViewResponse", + "api/CrudEndpointPattern", + "api/CrudEndpointsConfig", + "api/CrudOperation", + "api/CursorMessage", + "api/CursorPosition", + "api/DataEvent", + "api/DataEventType", + "api/DataLoaderConfig", + "api/DeduplicationStrategy", + "api/DeleteDataRequest", + "api/DeleteDataResponse", + "api/DeleteFeedItemRequest", + "api/DeleteFeedItemResponse", + "api/DeleteFlowRequest", + "api/DeleteFlowResponse", + "api/DeleteManyDataRequest", + "api/DeleteManyDataResponse", + "api/DeleteManyRequest", + "api/DeleteMetaItemRequest", + "api/DeleteMetaItemResponse", + "api/DeleteResponse", + "api/DeleteViewRequest", + "api/DeleteViewResponse", + "api/DeviceRequestResponse", + "api/DeviceTokenResponse", + "api/DisablePackageRequest", + "api/DisablePackageResponse", + "api/Discovery", + "api/DispatcherConfig", + "api/DispatcherErrorCode", + "api/DispatcherErrorResponse", + "api/DispatcherRoute", + "api/DocumentState", + "api/ETag", + "api/EditMessage", + "api/EditOperation", + "api/EditOperationType", + "api/EmailPasswordConfigPublic", + "api/EnablePackageRequest", + "api/EnablePackageResponse", + "api/EndpointRegistry", + "api/EnhancedApiError", + "api/ErrorCategory", + "api/ErrorHandlingConfig", + "api/ErrorMessage", + "api/ErrorResponse", + "api/EventFilter", + "api/EventFilterCondition", + "api/EventMessage", + "api/EventPattern", + "api/EventSubscription", + "api/ExportFormat", + "api/ExportImportTemplate", + "api/ExportJobProgress", + "api/ExportJobStatus", + "api/ExportJobSummary", + "api/ExportRequest", + "api/FederationEntity", + "api/FederationEntityKey", + "api/FederationExternalField", + "api/FederationGateway", + "api/FederationProvides", + "api/FederationRequires", + "api/FeedApiErrorCode", + "api/FeedItemPathParams", + "api/FeedListFilterType", + "api/FeedPathParams", + "api/FeedUnsubscribeRequest", + "api/FieldError", + "api/FieldMappingEntry", + "api/FileTypeValidation", + "api/FileUploadResponse", + "api/FilterOperator", + "api/FindDataRequest", + "api/FindDataResponse", + "api/FlowSummary", + "api/GeneratedApiDocumentation", + "api/GeneratedEndpoint", + "api/GetAnalyticsMetaRequest", + "api/GetAuthConfigResponse", + "api/GetChangelogRequest", + "api/GetChangelogResponse", + "api/GetDataRequest", + "api/GetDataResponse", + "api/GetDiscoveryRequest", + "api/GetDiscoveryResponse", + "api/GetEffectivePermissionsRequest", + "api/GetEffectivePermissionsResponse", + "api/GetExportJobDownloadRequest", + "api/GetExportJobDownloadResponse", + "api/GetFeedRequest", + "api/GetFeedResponse", + "api/GetFieldLabelsRequest", + "api/GetFieldLabelsResponse", + "api/GetFlowRequest", + "api/GetFlowResponse", + "api/GetInstalledPackageRequest", + "api/GetInstalledPackageResponse", + "api/GetLocalesRequest", + "api/GetLocalesResponse", + "api/GetMetaItemCachedRequest", + "api/GetMetaItemCachedResponse", + "api/GetMetaItemRequest", + "api/GetMetaItemResponse", + "api/GetMetaItemsRequest", + "api/GetMetaItemsResponse", + "api/GetMetaTypesRequest", + "api/GetMetaTypesResponse", + "api/GetNotificationPreferencesRequest", + "api/GetNotificationPreferencesResponse", + "api/GetObjectPermissionsRequest", + "api/GetObjectPermissionsResponse", + "api/GetPackageRequest", + "api/GetPackageResponse", + "api/GetPresenceRequest", + "api/GetPresenceResponse", + "api/GetPresignedUrlRequest", + "api/GetRunRequest", + "api/GetRunResponse", + "api/GetTranslationsRequest", + "api/GetTranslationsResponse", + "api/GetUiViewRequest", + "api/GetUiViewResponse", + "api/GetViewRequest", + "api/GetViewResponse", + "api/GetWorkflowConfigRequest", + "api/GetWorkflowConfigResponse", + "api/GetWorkflowStateRequest", + "api/GetWorkflowStateResponse", + "api/GraphQLConfig", + "api/GraphQLDataLoaderConfig", + "api/GraphQLDirectiveConfig", + "api/GraphQLDirectiveLocation", + "api/GraphQLMutationConfig", + "api/GraphQLPersistedQuery", + "api/GraphQLQueryAdapter", + "api/GraphQLQueryComplexity", + "api/GraphQLQueryConfig", + "api/GraphQLQueryDepthLimit", + "api/GraphQLRateLimit", + "api/GraphQLResolverConfig", + "api/GraphQLScalarType", + "api/GraphQLSubscriptionConfig", + "api/GraphQLTypeConfig", + "api/HandlerStatus", + "api/HttpFindQueryParams", + "api/HttpMethod", + "api/HttpStatusCode", + "api/IdRequest", + "api/ImportJobProgress", + "api/ImportJobResults", + "api/ImportJobStatus", + "api/ImportJobSummary", + "api/ImportMapping", + "api/ImportRequest", + "api/ImportResponse", + "api/ImportRowResult", + "api/ImportValidationConfig", + "api/ImportValidationMode", + "api/ImportValidationResult", + "api/ImportWriteMode", + "api/InitiateChunkedUploadRequest", + "api/InitiateChunkedUploadResponse", + "api/InstallPackageRequest", + "api/InstallPackageResponse", + "api/ListExportJobsRequest", + "api/ListExportJobsResponse", + "api/ListFlowsRequest", + "api/ListFlowsResponse", + "api/ListImportJobsRequest", + "api/ListImportJobsResponse", + "api/ListInstalledPackagesRequest", + "api/ListInstalledPackagesResponse", + "api/ListNotificationsRequest", + "api/ListNotificationsResponse", + "api/ListPackagesRequest", + "api/ListPackagesResponse", + "api/ListRecordResponse", + "api/ListRunsRequest", + "api/ListRunsResponse", + "api/ListViewsRequest", + "api/ListViewsResponse", + "api/LoginRequest", + "api/LoginType", + "api/MarkAllNotificationsReadRequest", + "api/MarkAllNotificationsReadResponse", + "api/MarkNotificationsReadRequest", + "api/MarkNotificationsReadResponse", + "api/MetadataBulkRegisterRequest", + "api/MetadataBulkResponse", + "api/MetadataBulkUnregisterRequest", + "api/MetadataCacheRequest", + "api/MetadataCacheResponse", + "api/MetadataDeleteResponse", + "api/MetadataDependenciesResponse", + "api/MetadataDependentsResponse", + "api/MetadataEffectiveResponse", + "api/MetadataEndpointsConfig", + "api/MetadataEvent", + "api/MetadataEventType", + "api/MetadataExistsResponse", + "api/MetadataExportRequest", + "api/MetadataExportResponse", + "api/MetadataImportRequest", + "api/MetadataImportResponse", + "api/MetadataItemResponse", + "api/MetadataListResponse", + "api/MetadataNamesResponse", + "api/MetadataOverlayResponse", + "api/MetadataOverlaySaveRequest", + "api/MetadataQueryRequest", + "api/MetadataQueryResponse", + "api/MetadataRegisterRequest", + "api/MetadataTypeInfoResponse", + "api/MetadataTypesResponse", + "api/MetadataValidateRequest", + "api/MetadataValidateResponse", + "api/ModificationResult", + "api/Notification", + "api/NotificationPreferences", + "api/ODataConfig", + "api/ODataError", + "api/ODataFilterFunction", + "api/ODataFilterOperator", + "api/ODataMetadata", + "api/ODataQuery", + "api/ODataQueryAdapter", + "api/ODataResponse", + "api/ObjectDefinitionResponse", + "api/ObjectQLReference", + "api/OpenApi31Extensions", + "api/OpenApiGenerationConfig", + "api/OpenApiSecurityScheme", + "api/OpenApiServer", + "api/OpenApiSpec", + "api/OperatorMapping", + "api/PackageApiErrorCode", + "api/PackageInstallRequest", + "api/PackageInstallResponse", + "api/PackagePathParams", + "api/PackageRollbackRequest", + "api/PackageRollbackResponse", + "api/PackageUpgradeRequest", + "api/PackageUpgradeResponse", + "api/PinFeedItemRequest", + "api/PinFeedItemResponse", + "api/PingMessage", + "api/PongMessage", + "api/PresenceMessage", + "api/PresenceState", + "api/PresenceStatus", + "api/PresenceUpdate", + "api/PresignedUrlResponse", + "api/QueryAdapterConfig", + "api/QueryAdapterTarget", + "api/QueryOptimizationConfig", + "api/RealtimeConfig", + "api/RealtimeConnectRequest", + "api/RealtimeConnectResponse", + "api/RealtimeDisconnectRequest", + "api/RealtimeDisconnectResponse", + "api/RealtimeEvent", + "api/RealtimeEventType", + "api/RealtimePresence", + "api/RealtimeRecordAction", + "api/RealtimeSubscribeRequest", + "api/RealtimeSubscribeResponse", + "api/RealtimeUnsubscribeRequest", + "api/RealtimeUnsubscribeResponse", + "api/RecordData", + "api/RefreshTokenRequest", + "api/RegisterDeviceRequest", + "api/RegisterDeviceResponse", + "api/RegisterRequest", + "api/RemoveReactionRequest", + "api/RemoveReactionResponse", + "api/RequestValidationConfig", + "api/ResolveDependenciesRequest", + "api/ResolveDependenciesResponse", + "api/ResponseEnvelopeConfig", + "api/RestApiConfig", + "api/RestApiEndpoint", + "api/RestApiPluginConfig", + "api/RestApiRouteCategory", + "api/RestApiRouteRegistration", + "api/RestQueryAdapter", + "api/RestServerConfig", + "api/RetryStrategy", + "api/RouteCategory", + "api/RouteCoverageEntry", + "api/RouteCoverageReport", + "api/RouteDefinition", + "api/RouteGenerationConfig", + "api/RouteHealthEntry", + "api/RouteHealthReport", + "api/RouterConfig", + "api/SaveMetaItemRequest", + "api/SaveMetaItemResponse", + "api/ScheduleExportRequest", + "api/ScheduleExportResponse", + "api/ScheduledExport", + "api/SchemaDefinition", + "api/SearchFeedRequest", + "api/SearchFeedResponse", + "api/ServiceInfo", + "api/ServiceStatus", + "api/Session", + "api/SessionResponse", + "api/SessionUser", + "api/SetPresenceRequest", + "api/SetPresenceResponse", + "api/SimpleCursorPosition", + "api/SimplePresenceState", + "api/SingleRecordResponse", + "api/StandardErrorCode", + "api/StarFeedItemRequest", + "api/StarFeedItemResponse", + "api/SubgraphConfig", + "api/SubscribeMessage", + "api/SubscribeRequest", + "api/SubscribeResponse", + "api/Subscription", + "api/SubscriptionEvent", + "api/ToggleFlowRequest", + "api/ToggleFlowResponse", + "api/TransportProtocol", + "api/TriggerFlowRequest", + "api/TriggerFlowResponse", + "api/UndoImportJobResponse", + "api/UninstallPackageApiRequest", + "api/UninstallPackageApiResponse", + "api/UninstallPackageRequest", + "api/UninstallPackageResponse", + "api/UnpinFeedItemRequest", + "api/UnpinFeedItemResponse", + "api/UnregisterDeviceRequest", + "api/UnregisterDeviceResponse", + "api/UnstarFeedItemRequest", + "api/UnstarFeedItemResponse", + "api/UnsubscribeMessage", + "api/UnsubscribeRequest", + "api/UnsubscribeResponse", + "api/UpdateDataRequest", + "api/UpdateDataResponse", + "api/UpdateFeedItemRequest", + "api/UpdateFeedItemResponse", + "api/UpdateFlowRequest", + "api/UpdateFlowResponse", + "api/UpdateManyDataRequest", + "api/UpdateManyDataResponse", + "api/UpdateManyRequest", + "api/UpdateNotificationPreferencesRequest", + "api/UpdateNotificationPreferencesResponse", + "api/UpdateRequest", + "api/UpdateViewRequest", + "api/UpdateViewResponse", + "api/UploadArtifactRequest", + "api/UploadArtifactResponse", + "api/UploadChunkRequest", + "api/UploadChunkResponse", + "api/UploadProgress", + "api/UserProfileResponse", + "api/ValidationMode", + "api/VersionDefinition", + "api/VersionNegotiationResponse", + "api/VersionStatus", + "api/VersioningConfig", + "api/VersioningStrategy", + "api/WebSocketConfig", + "api/WebSocketEvent", + "api/WebSocketMessage", + "api/WebSocketMessageType", + "api/WebSocketPresenceStatus", + "api/WebSocketServerConfig", + "api/WebhookConfig", + "api/WebhookEvent", + "api/WellKnownCapabilities", + "api/WorkflowState", + "api/WorkflowTransitionRequest", + "api/WorkflowTransitionResponse", + "automation/ActionCategory", + "automation/ActionDescriptor", + "automation/ActionParadigm", + "automation/ActionRef", + "automation/ApprovalDecision", + "automation/ApprovalEscalation", + "automation/ApprovalNodeApprover", + "automation/ApprovalNodeConfig", + "automation/ApproverType", + "automation/AuthField", + "automation/Authentication", + "automation/AuthenticationType", + "automation/BpmnDiagnostic", + "automation/BpmnElementMapping", + "automation/BpmnExportOptions", + "automation/BpmnImportOptions", + "automation/BpmnInteropResult", + "automation/BpmnUnmappedStrategy", + "automation/BpmnVersion", + "automation/Checkpoint", + "automation/ConcurrencyPolicy", + "automation/ConflictResolution", + "automation/Connector", + "automation/ConnectorCategory", + "automation/ConnectorInstance", + "automation/ConnectorOperation", + "automation/ConnectorTrigger", + "automation/DataDestinationConfig", + "automation/DataSourceConfig", + "automation/DataSyncConfig", + "automation/ETLDestination", + "automation/ETLEndpointType", + "automation/ETLPipeline", + "automation/ETLPipelineRun", + "automation/ETLRunStatus", + "automation/ETLSource", + "automation/ETLSyncMode", + "automation/ETLTransformation", + "automation/ETLTransformationType", + "automation/Event", + "automation/ExecutionError", + "automation/ExecutionErrorSeverity", + "automation/ExecutionLog", + "automation/ExecutionStatus", + "automation/ExecutionStepLog", + "automation/Flow", + "automation/FlowEdge", + "automation/FlowNode", + "automation/FlowNodeAction", + "automation/FlowRegion", + "automation/FlowVariable", + "automation/FlowVersionHistory", + "automation/GuardRef", + "automation/LoopConfig", + "automation/NodeExecutorDescriptor", + "automation/OAuth2Config", + "automation/OperationParameter", + "automation/OperationType", + "automation/ParallelBranch", + "automation/ParallelConfig", + "automation/RetryPolicy", + "automation/ScheduleState", + "automation/StateMachine", + "automation/StateNode", + "automation/SyncDirection", + "automation/SyncExecutionResult", + "automation/SyncExecutionStatus", + "automation/SyncMode", + "automation/Transition", + "automation/TryCatchConfig", + "automation/WaitEventType", + "automation/WaitExecutorConfig", + "automation/WaitResumePayload", + "automation/WaitTimeoutBehavior", + "automation/Webhook", + "automation/WebhookReceiver", + "automation/WebhookTriggerType", + "cloud/AnalyticsTimeRange", + "cloud/AppDiscoveryRequest", + "cloud/AppDiscoveryResponse", + "cloud/AppSubscription", + "cloud/ArtifactDownloadResponse", + "cloud/ArtifactReference", + "cloud/CreateListingRequest", + "cloud/CreatePackageRequest", + "cloud/CreatePackageVersionRequest", + "cloud/CuratedCollection", + "cloud/Environment", + "cloud/EnvironmentCredential", + "cloud/EnvironmentCredentialStatus", + "cloud/EnvironmentDriver", + "cloud/EnvironmentMember", + "cloud/EnvironmentPackageInstallation", + "cloud/EnvironmentPackageStatus", + "cloud/EnvironmentRole", + "cloud/EnvironmentStatus", + "cloud/EnvironmentType", + "cloud/EnvironmentVisibility", + "cloud/FeaturedListing", + "cloud/InstallPackageToEnvironmentRequest", + "cloud/InstalledAppSummary", + "cloud/ListEnvironmentPackagesResponse", + "cloud/ListInstalledAppsRequest", + "cloud/ListInstalledAppsResponse", + "cloud/ListReviewsRequest", + "cloud/ListReviewsResponse", + "cloud/ListingActionRequest", + "cloud/ListingStatus", + "cloud/MarketplaceCategory", + "cloud/MarketplaceHealthMetrics", + "cloud/MarketplaceInstallRequest", + "cloud/MarketplaceInstallResponse", + "cloud/MarketplaceListing", + "cloud/MarketplaceSearchRequest", + "cloud/MarketplaceSearchResponse", + "cloud/Package", + "cloud/PackageCategory", + "cloud/PackageDependency", + "cloud/PackageInstallation", + "cloud/PackageInstallationStatus", + "cloud/PackageLocale", + "cloud/PackageManifest", + "cloud/PackagePublisher", + "cloud/PackageSubmission", + "cloud/PackageTranslation", + "cloud/PackageTranslations", + "cloud/PackageVersion", + "cloud/PackageVersionStatus", + "cloud/PackageVisibility", + "cloud/PolicyAction", + "cloud/PolicyViolationType", + "cloud/PricingModel", + "cloud/ProvisionEnvironmentRequest", + "cloud/ProvisionEnvironmentResponse", + "cloud/ProvisionOrganizationRequest", + "cloud/ProvisionOrganizationResponse", + "cloud/ProvisionTenantRequest", + "cloud/ProvisionTenantResponse", + "cloud/PublishPackageVersionRequest", + "cloud/Publisher", + "cloud/PublisherProfile", + "cloud/PublisherVerification", + "cloud/PublishingAnalyticsRequest", + "cloud/PublishingAnalyticsResponse", + "cloud/RecommendationReason", + "cloud/RecommendedApp", + "cloud/RejectionReason", + "cloud/ReleaseChannel", + "cloud/ReviewCriterion", + "cloud/ReviewDecision", + "cloud/ReviewModerationStatus", + "cloud/RollbackEnvironmentPackageRequest", + "cloud/Sha256Digest", + "cloud/SubmissionReview", + "cloud/SubmitReviewRequest", + "cloud/SubscriptionStatus", + "cloud/TemplateManifest", + "cloud/TenantContext", + "cloud/TenantDatabase", + "cloud/TenantDatabaseStatus", + "cloud/TenantIdentificationSource", + "cloud/TenantPlan", + "cloud/TenantRoutingConfig", + "cloud/TimeSeriesPoint", + "cloud/TrendingListing", + "cloud/UpdateListingRequest", + "cloud/UpdatePackageRequest", + "cloud/UpdatePackageVersionRequest", + "cloud/UpgradeEnvironmentPackageRequest", + "cloud/UserReview", + "cloud/VersionRelease", + "data/Address", + "data/AggregationFunction", + "data/AggregationMetricType", + "data/AggregationNode", + "data/AggregationPipeline", + "data/AggregationStage", + "data/AnalyticsQuery", + "data/ApiMethod", + "data/BaseEngineOptions", + "data/ComputedFieldCache", + "data/ConditionalValidation", + "data/ConsistencyLevel", + "data/CrossFieldValidation", + "data/Cube", + "data/CubeJoin", + "data/CurrencyConfig", + "data/CurrencyValue", + "data/DataEngineAggregateOptions", + "data/DataEngineAggregateRequest", + "data/DataEngineBatchRequest", + "data/DataEngineCountOptions", + "data/DataEngineCountRequest", + "data/DataEngineDeleteOptions", + "data/DataEngineDeleteRequest", + "data/DataEngineExecuteRequest", + "data/DataEngineFilter", + "data/DataEngineFindOneRequest", + "data/DataEngineFindRequest", + "data/DataEngineInsertOptions", + "data/DataEngineInsertRequest", + "data/DataEngineQueryOptions", + "data/DataEngineRequest", + "data/DataEngineSort", + "data/DataEngineUpdateOptions", + "data/DataEngineUpdateRequest", + "data/DataEngineVectorFindRequest", + "data/DataQualityRules", + "data/DataTypeMapping", + "data/Datasource", + "data/DatasourceCapabilities", + "data/DateGranularity", + "data/DateMacroPlaceholder", + "data/DateMacroToken", + "data/Dimension", + "data/DimensionType", + "data/Document", + "data/DocumentTemplate", + "data/DocumentValidationSchema", + "data/DocumentVersion", + "data/DriverCapabilities", + "data/DriverConfig", + "data/DriverDefinition", + "data/DriverOptions", + "data/DriverType", + "data/ESignatureConfig", + "data/EngineAggregateOptions", + "data/EngineCountOptions", + "data/EngineDeleteOptions", + "data/EngineQueryOptions", + "data/EngineUpdateOptions", + "data/EqualityOperator", + "data/ExpressionBody", + "data/ExternalCatalog", + "data/ExternalColumn", + "data/ExternalDataSource", + "data/ExternalDatasourceSettings", + "data/ExternalFieldMapping", + "data/ExternalLookup", + "data/ExternalTable", + "data/FeedActor", + "data/FeedFilterMode", + "data/FeedItem", + "data/FeedItemType", + "data/FeedVisibility", + "data/Field", + "data/FieldChangeEntry", + "data/FieldMapping", + "data/FieldNode", + "data/FieldReference", + "data/FieldType", + "data/FileAttachmentConfig", + "data/FilterCondition", + "data/FormatValidation", + "data/FullTextSearch", + "data/GroupByNode", + "data/HookBody", + "data/HookBodyCapability", + "data/HookContext", + "data/HookEvent", + "data/Index", + "data/JSONValidation", + "data/JoinNode", + "data/JoinStrategy", + "data/JoinType", + "data/Lifecycle", + "data/LifecycleClass", + "data/LocationCoordinates", + "data/Mapping", + "data/Mention", + "data/Metric", + "data/ModeSchema", + "data/NoSQLDataTypeMapping", + "data/NoSQLDatabaseType", + "data/NoSQLDriverConfig", + "data/NoSQLIndex", + "data/NoSQLIndexType", + "data/NoSQLOperationType", + "data/NoSQLQueryOptions", + "data/NoSQLTransactionOptions", + "data/NotificationChannel", + "data/Object", + "data/ObjectAccessConfig", + "data/ObjectCapabilities", + "data/ObjectDependencyGraph", + "data/ObjectDependencyNode", + "data/ObjectExtension", + "data/ObjectExternalBinding", + "data/ObjectFieldGroup", + "data/ObjectOwnershipEnum", + "data/ObjectRequiredPermissions", + "data/PerOperationRequiredPermissions", + "data/PoolConfig", + "data/Query", + "data/QueryFilter", + "data/Reaction", + "data/RecordSubscription", + "data/ReferenceResolution", + "data/ReferenceResolutionError", + "data/ReplicationConfig", + "data/SQLDialect", + "data/SQLDriverConfig", + "data/SSLConfig", + "data/ScriptBody", + "data/ScriptValidation", + "data/SearchConfig", + "data/Seed", + "data/SeedIdentity", + "data/SeedLoadResult", + "data/SeedLoaderConfig", + "data/SeedLoaderRequest", + "data/SeedLoaderResult", + "data/SeedMode", + "data/SelectOption", + "data/SetOperator", + "data/ShardingConfig", + "data/SoftDeleteConfig", + "data/SortNode", + "data/SpecialOperator", + "data/StateMachineValidation", + "data/StringOperator", + "data/SubscriptionEventType", + "data/TenancyConfig", + "data/TimeUpdateInterval", + "data/TransformType", + "data/ValidationRule", + "data/VectorConfig", + "data/VersioningConfig", + "data/WindowFunction", + "data/WindowFunctionNode", + "data/WindowSpec", + "identity/Account", + "identity/ApiKey", + "identity/EvalUser", + "identity/Invitation", + "identity/InvitationStatus", + "identity/Member", + "identity/Organization", + "identity/Position", + "identity/SCIMAddress", + "identity/SCIMBulkOperation", + "identity/SCIMBulkRequest", + "identity/SCIMBulkResponse", + "identity/SCIMBulkResponseOperation", + "identity/SCIMEmail", + "identity/SCIMEnterpriseUser", + "identity/SCIMError", + "identity/SCIMGroup", + "identity/SCIMGroupReference", + "identity/SCIMListResponse", + "identity/SCIMMemberReference", + "identity/SCIMMeta", + "identity/SCIMName", + "identity/SCIMPatchOperation", + "identity/SCIMPatchRequest", + "identity/SCIMPhoneNumber", + "identity/SCIMUser", + "identity/Session", + "identity/User", + "identity/VerificationToken", + "integration/AckMode", + "integration/ApiVersionConfig", + "integration/BuildConfig", + "integration/CdcConfig", + "integration/CircuitBreakerConfig", + "integration/ConflictResolution", + "integration/Connector", + "integration/ConnectorAction", + "integration/ConnectorHealth", + "integration/ConnectorInstanceAPIKeyAuth", + "integration/ConnectorInstanceAuth", + "integration/ConnectorInstanceBasicAuth", + "integration/ConnectorInstanceBearerAuth", + "integration/ConnectorInstanceNoAuth", + "integration/ConnectorStatus", + "integration/ConnectorTrigger", + "integration/ConnectorType", + "integration/ConsumerConfig", + "integration/DataSyncConfig", + "integration/DatabaseConnector", + "integration/DatabasePoolConfig", + "integration/DatabaseProvider", + "integration/DatabaseTable", + "integration/DeclarativeConnectorEntry", + "integration/DeliveryGuarantee", + "integration/DeploymentConfig", + "integration/DlqConfig", + "integration/DomainConfig", + "integration/EdgeFunctionConfig", + "integration/EnvironmentVariables", + "integration/ErrorCategory", + "integration/ErrorMappingConfig", + "integration/ErrorMappingRule", + "integration/FieldMapping", + "integration/FileAccessPattern", + "integration/FileFilterConfig", + "integration/FileMetadataConfig", + "integration/FileStorageConnector", + "integration/FileStorageProvider", + "integration/FileVersioningConfig", + "integration/GitHubActionsWorkflow", + "integration/GitHubCommitConfig", + "integration/GitHubConnector", + "integration/GitHubIssueTracking", + "integration/GitHubProvider", + "integration/GitHubPullRequestConfig", + "integration/GitHubReleaseConfig", + "integration/GitHubRepository", + "integration/GitRepositoryConfig", + "integration/HealthCheckConfig", + "integration/MessageFormat", + "integration/MessageQueueConnector", + "integration/MessageQueueProvider", + "integration/MultipartUploadConfig", + "integration/ProducerConfig", + "integration/RateLimitConfig", + "integration/RateLimitStrategy", + "integration/RetryConfig", + "integration/RetryStrategy", + "integration/SaasConnector", + "integration/SaasObjectType", + "integration/SaasProvider", + "integration/SslConfig", + "integration/StorageBucket", + "integration/SyncStrategy", + "integration/TopicQueue", + "integration/VercelConnector", + "integration/VercelFramework", + "integration/VercelMonitoring", + "integration/VercelProject", + "integration/VercelProvider", + "integration/VercelTeam", + "integration/WebhookConfig", + "integration/WebhookEvent", + "integration/WebhookSignatureAlgorithm", + "kernel/ActivationEvent", + "kernel/AdvancedPluginLifecycleConfig", + "kernel/ArtifactChecksum", + "kernel/ArtifactFileEntry", + "kernel/ArtifactSignature", + "kernel/BreakingChange", + "kernel/CLICommandContribution", + "kernel/CapabilityConformanceLevel", + "kernel/ClusterCapabilityConfig", + "kernel/ClusterDriver", + "kernel/ClusterTenantIsolation", + "kernel/CompatibilityLevel", + "kernel/CompatibilityMatrixEntry", + "kernel/CustomizationOrigin", + "kernel/CustomizationPolicy", + "kernel/DeadLetterQueueEntry", + "kernel/DependencyConflict", + "kernel/DependencyGraph", + "kernel/DependencyGraphNode", + "kernel/DependencyResolutionResult", + "kernel/DependencyStatusEnum", + "kernel/DeprecationNotice", + "kernel/DevFixtureConfig", + "kernel/DevPluginConfig", + "kernel/DevPluginPreset", + "kernel/DevServiceOverride", + "kernel/DevToolsConfig", + "kernel/DisablePackageRequest", + "kernel/DisablePackageResponse", + "kernel/DistributedStateConfig", + "kernel/DynamicLoadRequest", + "kernel/DynamicLoadingConfig", + "kernel/DynamicPluginOperation", + "kernel/DynamicPluginResult", + "kernel/DynamicUnloadRequest", + "kernel/EnablePackageRequest", + "kernel/EnablePackageResponse", + "kernel/Event", + "kernel/EventBusConfig", + "kernel/EventClusterOptions", + "kernel/EventDeliverySemantics", + "kernel/EventHandler", + "kernel/EventLogEntry", + "kernel/EventMessageQueueConfig", + "kernel/EventMetadata", + "kernel/EventPersistence", + "kernel/EventPhase", + "kernel/EventPriority", + "kernel/EventQueueConfig", + "kernel/EventReplayConfig", + "kernel/EventRoute", + "kernel/EventScope", + "kernel/EventSourcingConfig", + "kernel/EventTypeDefinition", + "kernel/EventWebhookConfig", + "kernel/ExecutionContext", + "kernel/ExtensionPoint", + "kernel/FeatureFlag", + "kernel/FeatureStrategy", + "kernel/FieldChange", + "kernel/GetPackageRequest", + "kernel/GetPackageResponse", + "kernel/GracefulDegradation", + "kernel/HealthStatus", + "kernel/HookRegisteredEvent", + "kernel/HookTriggeredEvent", + "kernel/HotReloadConfig", + "kernel/InstallPackageRequest", + "kernel/InstallPackageResponse", + "kernel/InstalledPackage", + "kernel/KernelContext", + "kernel/KernelEventBase", + "kernel/KernelReadyEvent", + "kernel/KernelSecurityPolicy", + "kernel/KernelSecurityScanResult", + "kernel/KernelSecurityVulnerability", + "kernel/KernelShutdownEvent", + "kernel/ListPackagesRequest", + "kernel/ListPackagesResponse", + "kernel/Manifest", + "kernel/ManifestPermissions", + "kernel/MergeConflict", + "kernel/MergeResult", + "kernel/MergeStrategyConfig", + "kernel/MetadataBulkRegisterRequest", + "kernel/MetadataBulkResult", + "kernel/MetadataCategoryEnum", + "kernel/MetadataChangeOperation", + "kernel/MetadataChangeType", + "kernel/MetadataCollectionInfo", + "kernel/MetadataDependency", + "kernel/MetadataDiffItem", + "kernel/MetadataEvent", + "kernel/MetadataExportOptions", + "kernel/MetadataFallbackStrategy", + "kernel/MetadataFormat", + "kernel/MetadataImportOptions", + "kernel/MetadataLoadOptions", + "kernel/MetadataLoadResult", + "kernel/MetadataLoaderContract", + "kernel/MetadataLock", + "kernel/MetadataLockSource", + "kernel/MetadataManagerConfig", + "kernel/MetadataOverlay", + "kernel/MetadataPluginConfig", + "kernel/MetadataPluginManifest", + "kernel/MetadataProvenance", + "kernel/MetadataQuery", + "kernel/MetadataQueryResult", + "kernel/MetadataSaveOptions", + "kernel/MetadataSaveResult", + "kernel/MetadataStats", + "kernel/MetadataType", + "kernel/MetadataTypeRegistryEntry", + "kernel/MetadataValidationResult", + "kernel/MetadataWatchEvent", + "kernel/MultiVersionSupport", + "kernel/NamespaceConflictError", + "kernel/NamespaceRegistryEntry", + "kernel/OclifPluginConfig", + "kernel/OpsDomainModule", + "kernel/OpsFilePath", + "kernel/OpsPluginStructure", + "kernel/PackageArtifact", + "kernel/PackageDependency", + "kernel/PackageDependencyConflict", + "kernel/PackageDependencyResolutionResult", + "kernel/PackageStatusEnum", + "kernel/PermissionAction", + "kernel/PermissionScope", + "kernel/PluginCaching", + "kernel/PluginCapability", + "kernel/PluginCapabilityManifest", + "kernel/PluginCodeSplitting", + "kernel/PluginCompatibilityMatrix", + "kernel/PluginDependency", + "kernel/PluginDependencyResolution", + "kernel/PluginDependencyResolutionResult", + "kernel/PluginDiscoveryConfig", + "kernel/PluginDiscoverySource", + "kernel/PluginDynamicImport", + "kernel/PluginEngines", + "kernel/PluginErrorEvent", + "kernel/PluginEventBase", + "kernel/PluginHealthCheck", + "kernel/PluginHealthReport", + "kernel/PluginHealthStatus", + "kernel/PluginHotReload", + "kernel/PluginInitialization", + "kernel/PluginInstallConfig", + "kernel/PluginIntegrity", + "kernel/PluginInterface", + "kernel/PluginLifecycleEventType", + "kernel/PluginLifecyclePhaseEvent", + "kernel/PluginLoadingConfig", + "kernel/PluginLoadingEvent", + "kernel/PluginLoadingState", + "kernel/PluginLoadingStrategy", + "kernel/PluginMetadata", + "kernel/PluginPackaging", + "kernel/PluginPerformanceMonitoring", + "kernel/PluginPermission", + "kernel/PluginPermissionSet", + "kernel/PluginPermissions", + "kernel/PluginPreloadConfig", + "kernel/PluginProvenance", + "kernel/PluginQualityMetrics", + "kernel/PluginRegisteredEvent", + "kernel/PluginRegistryEntry", + "kernel/PluginRuntime", + "kernel/PluginSandboxing", + "kernel/PluginSearchFilters", + "kernel/PluginSecurityManifest", + "kernel/PluginSource", + "kernel/PluginStartupResult", + "kernel/PluginStateSnapshot", + "kernel/PluginStatistics", + "kernel/PluginTrustLevel", + "kernel/PluginTrustScore", + "kernel/PluginUpdateStrategy", + "kernel/PluginVendor", + "kernel/PluginVersionMetadata", + "kernel/PreviewModeConfig", + "kernel/ProtocolFeature", + "kernel/ProtocolReference", + "kernel/ProtocolVersion", + "kernel/RealTimeNotificationConfig", + "kernel/RequiredAction", + "kernel/ResolvedDependency", + "kernel/ResourceType", + "kernel/RollbackPackageRequest", + "kernel/RollbackPackageResponse", + "kernel/RuntimeConfig", + "kernel/RuntimeMode", + "kernel/SBOM", + "kernel/SBOMEntry", + "kernel/SandboxConfig", + "kernel/ScopeConfig", + "kernel/ScopeInfo", + "kernel/SecurityPolicy", + "kernel/SecurityScanResult", + "kernel/SecurityVulnerability", + "kernel/SemanticVersion", + "kernel/ServiceClusterAnnotations", + "kernel/ServiceClusterScope", + "kernel/ServiceFactoryRegistration", + "kernel/ServiceLeaderStrategy", + "kernel/ServiceMetadata", + "kernel/ServiceRegisteredEvent", + "kernel/ServiceRegistryConfig", + "kernel/ServiceScopeType", + "kernel/ServiceUnregisteredEvent", + "kernel/StartupOptions", + "kernel/StartupOrchestrationResult", + "kernel/TenantRuntimeContext", + "kernel/UninstallPackageRequest", + "kernel/UninstallPackageResponse", + "kernel/UpgradeContext", + "kernel/UpgradeImpactLevel", + "kernel/UpgradePackageRequest", + "kernel/UpgradePackageResponse", + "kernel/UpgradePhase", + "kernel/UpgradePlan", + "kernel/UpgradeSnapshot", + "kernel/ValidationError", + "kernel/ValidationResult", + "kernel/ValidationWarning", + "kernel/VersionConstraint", + "kernel/VulnerabilitySeverity", + "qa/TestAction", + "qa/TestActionType", + "qa/TestAssertion", + "qa/TestAssertionType", + "qa/TestContext", + "qa/TestScenario", + "qa/TestStep", + "qa/TestSuite", + "security/AccessMatrix", + "security/AccessMatrixEntry", + "security/AdminScope", + "security/AuthzPosture", + "security/CapabilityDeclaration", + "security/CriteriaSharingRule", + "security/ExplainDecision", + "security/ExplainLayer", + "security/ExplainMatchedRule", + "security/ExplainOperation", + "security/ExplainRecordAttribution", + "security/ExplainRequest", + "security/FieldPermission", + "security/OWDModel", + "security/ObjectAccessScope", + "security/ObjectPermission", + "security/OwnerSharingRule", + "security/PermissionSet", + "security/RLSEvaluationResult", + "security/RLSOperation", + "security/RLSUserContext", + "security/RowLevelSecurityPolicy", + "security/ShareRecipientType", + "security/SharingLevel", + "security/SharingRule", + "security/SharingRuleType", + "security/Territory", + "security/TerritoryModel", + "security/TerritoryType", + "shared/AggregationFunctionEnum", + "shared/AppName", + "shared/BaseMetadataRecord", + "shared/CacheStrategyEnum", + "shared/CorsConfig", + "shared/CronExpressionInput", + "shared/EventName", + "shared/Expression", + "shared/ExpressionDialect", + "shared/ExpressionInput", + "shared/ExpressionMeta", + "shared/FieldMapping", + "shared/FieldName", + "shared/FlowName", + "shared/HttpMethod", + "shared/HttpRequest", + "shared/IsolationLevelEnum", + "shared/MetadataFormat", + "shared/MutationEventEnum", + "shared/ObjectName", + "shared/Predicate", + "shared/PredicateInput", + "shared/Protection", + "shared/RateLimitConfig", + "shared/RoleName", + "shared/SnakeCaseIdentifier", + "shared/SortDirectionEnum", + "shared/SortItem", + "shared/StaticMount", + "shared/SystemIdentifier", + "shared/TemplateExpressionInput", + "shared/TransformType", + "shared/ViewName", + "studio/ActionContribution", + "studio/ActionLocation", + "studio/ActivationEvent", + "studio/CommandContribution", + "studio/ERDiagramConfig", + "studio/ERLayoutAlgorithm", + "studio/ERNodeDisplay", + "studio/FieldEditorConfig", + "studio/FieldGroup", + "studio/FieldPropertySection", + "studio/FlowBuilderConfig", + "studio/FlowCanvasEdge", + "studio/FlowCanvasEdgeStyle", + "studio/FlowCanvasNode", + "studio/FlowLayoutAlgorithm", + "studio/FlowLayoutDirection", + "studio/FlowNodeRenderDescriptor", + "studio/FlowNodeShape", + "studio/MetadataIconContribution", + "studio/MetadataViewerContribution", + "studio/ObjectDesignerConfig", + "studio/ObjectDesignerDefaultView", + "studio/ObjectFilter", + "studio/ObjectListDisplayMode", + "studio/ObjectManagerConfig", + "studio/ObjectPreviewConfig", + "studio/ObjectPreviewTab", + "studio/ObjectSortField", + "studio/PanelContribution", + "studio/PanelLocation", + "studio/RelationshipDisplay", + "studio/RelationshipMapperConfig", + "studio/SidebarGroupContribution", + "studio/StudioPluginContributions", + "studio/StudioPluginManifest", + "studio/ViewMode", + "system/AccessControlConfig", + "system/AddFieldOperation", + "system/AdvancedAuthConfig", + "system/AnalyzerConfig", + "system/AppCompatibilityCheck", + "system/AppInstallRequest", + "system/AppInstallResult", + "system/AppManifest", + "system/AppTranslationBundle", + "system/AuditConfig", + "system/AuditEvent", + "system/AuditEventActor", + "system/AuditEventChange", + "system/AuditEventFilter", + "system/AuditEventSeverity", + "system/AuditEventTarget", + "system/AuditEventType", + "system/AuditRetentionPolicy", + "system/AuditStorageConfig", + "system/AuthConfig", + "system/AuthPluginConfig", + "system/AuthProviderConfig", + "system/AwarenessEvent", + "system/AwarenessSession", + "system/AwarenessUpdate", + "system/AwarenessUserState", + "system/BackupConfig", + "system/BackupRetention", + "system/BackupStrategy", + "system/BatchProgress", + "system/Book", + "system/BookAudience", + "system/BookGroup", + "system/BookInclude", + "system/BookNode", + "system/BucketConfig", + "system/CRDTMergeResult", + "system/CRDTState", + "system/CRDTType", + "system/CacheAvalanchePrevention", + "system/CacheConfig", + "system/CacheConsistency", + "system/CacheInvalidation", + "system/CacheStrategy", + "system/CacheTier", + "system/CacheWarmup", + "system/ChangeImpact", + "system/ChangePriority", + "system/ChangeRequest", + "system/ChangeSchema", + "system/ChangeSet", + "system/ChangeStatus", + "system/ChangeType", + "system/CollaborationMode", + "system/CollaborationSession", + "system/CollaborationSessionConfig", + "system/CollaborativeCursor", + "system/ComplianceAuditRequirement", + "system/ComplianceEncryptionRequirement", + "system/ComplianceFramework", + "system/ConsoleDestinationConfig", + "system/ConsumerConfig", + "system/CoreServiceName", + "system/CounterOperation", + "system/CoverageBreakdownEntry", + "system/CreateObjectOperation", + "system/CronSchedule", + "system/CursorColorPreset", + "system/CursorSelection", + "system/CursorStyle", + "system/CursorUpdate", + "system/DataClassification", + "system/DataClassificationPolicy", + "system/DatabaseLevelIsolationStrategy", + "system/DatabaseProvider", + "system/DeadLetterQueue", + "system/DeleteObjectOperation", + "system/DeployBundle", + "system/DeployDiff", + "system/DeployManifest", + "system/DeployStatusEnum", + "system/DeployValidationIssue", + "system/DeployValidationResult", + "system/DisasterRecoveryPlan", + "system/DistributedCacheConfig", + "system/Doc", + "system/EmailAddressConfig", + "system/EmailAndPasswordConfig", + "system/EmailProvider", + "system/EmailServiceConfig", + "system/EmailTemplate", + "system/EmailTemplateDefinition", + "system/EmailTemplateDefinitionCategory", + "system/EmailTemplateDefinitionVariable", + "system/EmailVerificationConfig", + "system/EncryptionAlgorithm", + "system/EncryptionConfig", + "system/EnvironmentArtifact", + "system/EnvironmentArtifactChecksum", + "system/EnvironmentArtifactFunction", + "system/EnvironmentArtifactFunctionLanguageEnum", + "system/EnvironmentArtifactHashAlgorithmEnum", + "system/EnvironmentArtifactManifest", + "system/EnvironmentArtifactMetadata", + "system/EnvironmentArtifactPayloadRef", + "system/EnvironmentArtifactRequirement", + "system/ExecuteSqlOperation", + "system/ExtendedLogLevel", + "system/ExternalServiceDestinationConfig", + "system/FacetConfig", + "system/FailoverConfig", + "system/FailoverMode", + "system/Feature", + "system/FieldEncryption", + "system/FieldTranslation", + "system/FileDestinationConfig", + "system/FileMetadata", + "system/GCounter", + "system/HistogramBucketConfig", + "system/HttpDestinationConfig", + "system/HttpServerConfig", + "system/InAppNotification", + "system/Incident", + "system/IncidentCategory", + "system/IncidentNotificationMatrix", + "system/IncidentNotificationRule", + "system/IncidentResponsePhase", + "system/IncidentResponsePolicy", + "system/IncidentSeverity", + "system/IncidentStatus", + "system/IntervalSchedule", + "system/Job", + "system/JobExecution", + "system/JobExecutionStatus", + "system/KernelServiceMap", + "system/KeyManagementProvider", + "system/KeyRotationPolicy", + "system/LWWRegister", + "system/LevelIsolationStrategySchema", + "system/License", + "system/LicenseMetricType", + "system/LifecycleAction", + "system/LifecyclePolicyConfig", + "system/LifecyclePolicyRule", + "system/Locale", + "system/LogDestination", + "system/LogDestinationType", + "system/LogEnrichmentConfig", + "system/LogEntry", + "system/LogFormat", + "system/LogLevel", + "system/LoggerConfig", + "system/LoggingConfig", + "system/MaskingVisibilityRule", + "system/MessageFormat", + "system/MessageQueueConfig", + "system/MessageQueueProvider", + "system/MetadataCollectionInfo", + "system/MetadataDiffResult", + "system/MetadataExportOptions", + "system/MetadataFallbackStrategy", + "system/MetadataFormat", + "system/MetadataHistoryQueryOptions", + "system/MetadataHistoryQueryResult", + "system/MetadataHistoryRecord", + "system/MetadataHistoryRetentionPolicy", + "system/MetadataImportOptions", + "system/MetadataLoadOptions", + "system/MetadataLoadResult", + "system/MetadataLoaderContract", + "system/MetadataManagerConfig", + "system/MetadataRecord", + "system/MetadataSaveOptions", + "system/MetadataSaveResult", + "system/MetadataScope", + "system/MetadataSource", + "system/MetadataState", + "system/MetadataStats", + "system/MetadataWatchEvent", + "system/MetricAggregationConfig", + "system/MetricAggregationType", + "system/MetricDataPoint", + "system/MetricDefinition", + "system/MetricExportConfig", + "system/MetricLabels", + "system/MetricType", + "system/MetricUnit", + "system/MetricsConfig", + "system/MiddlewareConfig", + "system/MiddlewareType", + "system/MigrationDependency", + "system/MigrationOperation", + "system/MigrationPlan", + "system/MigrationStatement", + "system/ModifyFieldOperation", + "system/MultipartUploadConfig", + "system/MutualTLSConfig", + "system/NotificationChannel", + "system/NotificationConfig", + "system/ORSet", + "system/ORSetElement", + "system/OTComponent", + "system/OTOperation", + "system/OTOperationType", + "system/OTTransformResult", + "system/ObjectMetadata", + "system/ObjectStorageConfig", + "system/ObjectTranslationData", + "system/ObjectTranslationNode", + "system/OidcProviderConfig", + "system/OidcProvidersConfig", + "system/OnceSchedule", + "system/OpenTelemetryCompatibility", + "system/OtelExporterType", + "system/PNCounter", + "system/PackagePublishResult", + "system/Plan", + "system/PresignedUrlConfig", + "system/ProvisioningStep", + "system/PushNotification", + "system/QueueConfig", + "system/QuotaEnforcementResult", + "system/RPO", + "system/RTO", + "system/RegistryConfig", + "system/RegistrySyncPolicy", + "system/RegistryUpstream", + "system/RemoveFieldOperation", + "system/RenameObjectOperation", + "system/ResolvedSettingValue", + "system/RetryPolicy", + "system/RollbackPlan", + "system/RouteHandlerMetadata", + "system/RowLevelIsolationStrategy", + "system/SMSTemplate", + "system/SamplingDecision", + "system/SamplingStrategyType", + "system/Schedule", + "system/SearchConfig", + "system/SearchIndexConfig", + "system/SearchProvider", + "system/SecurityContextConfig", + "system/SecurityEventCorrelation", + "system/ServerCapabilities", + "system/ServerEvent", + "system/ServerEventType", + "system/ServerStatus", + "system/ServiceConfig", + "system/ServiceCriticality", + "system/ServiceLevelIndicator", + "system/ServiceLevelObjective", + "system/ServiceStatus", + "system/SettingsActionResult", + "system/SettingsChangeEvent", + "system/SettingsManifest", + "system/SettingsNamespacePayload", + "system/SocialProviderConfig", + "system/Span", + "system/SpanAttributeValue", + "system/SpanAttributes", + "system/SpanEvent", + "system/SpanKind", + "system/SpanLink", + "system/SpanStatus", + "system/Specifier", + "system/SpecifierHandler", + "system/SpecifierOption", + "system/SpecifierScope", + "system/SpecifierType", + "system/StorageAcl", + "system/StorageClass", + "system/StorageConnection", + "system/StorageProvider", + "system/StorageScope", + "system/StructuredLogEntry", + "system/SupplierAssessmentStatus", + "system/SupplierRiskLevel", + "system/SupplierSecurityAssessment", + "system/SupplierSecurityPolicy", + "system/SupplierSecurityRequirement", + "system/SuspiciousActivityRule", + "system/Task", + "system/TaskExecutionResult", + "system/TaskPriority", + "system/TaskRetryPolicy", + "system/TaskStatus", + "system/Tenant", + "system/TenantConnectionConfig", + "system/TenantIsolationConfig", + "system/TenantIsolationLevel", + "system/TenantPlan", + "system/TenantProvisioningRequest", + "system/TenantProvisioningResult", + "system/TenantProvisioningStatusEnum", + "system/TenantQuota", + "system/TenantRegion", + "system/TenantSecurityPolicy", + "system/TenantUsage", + "system/TextCRDTOperation", + "system/TextCRDTState", + "system/TimeSeries", + "system/TimeSeriesDataPoint", + "system/TopicConfig", + "system/TraceContext", + "system/TraceContextPropagation", + "system/TraceFlags", + "system/TracePropagationFormat", + "system/TraceSamplingConfig", + "system/TraceState", + "system/TracingConfig", + "system/TrainingCategory", + "system/TrainingCompletionStatus", + "system/TrainingCourse", + "system/TrainingPlan", + "system/TrainingRecord", + "system/TranslationBundle", + "system/TranslationConfig", + "system/TranslationCoverageResult", + "system/TranslationData", + "system/TranslationDiffItem", + "system/TranslationDiffStatus", + "system/TranslationFileOrganization", + "system/UserActivityStatus", + "system/VectorClock", + "system/WorkerStats", + "ui/AIChatWindowProps", + "ui/Action", + "ui/ActionAi", + "ui/ActionLocation", + "ui/ActionNavItem", + "ui/ActionParam", + "ui/ActionType", + "ui/AddRecordConfig", + "ui/Animation", + "ui/AnimationTrigger", + "ui/App", + "ui/AppBranding", + "ui/AppContextSelector", + "ui/AppearanceConfig", + "ui/AriaProps", + "ui/BorderRadius", + "ui/BreakpointColumnMap", + "ui/BreakpointName", + "ui/BreakpointOrderMap", + "ui/Breakpoints", + "ui/CalendarConfig", + "ui/ChartAnnotation", + "ui/ChartAxis", + "ui/ChartConfig", + "ui/ChartInteraction", + "ui/ChartSeries", + "ui/ChartType", + "ui/ColorPalette", + "ui/ColumnSummary", + "ui/ComponentAnimation", + "ui/ComponentNavItem", + "ui/ConflictResolution", + "ui/Dashboard", + "ui/DashboardHeader", + "ui/DashboardHeaderAction", + "ui/DashboardNavItem", + "ui/DashboardWidget", + "ui/Dataset", + "ui/DatasetDimension", + "ui/DatasetMeasure", + "ui/DateFormat", + "ui/DensityMode", + "ui/DerivedMeasureOp", + "ui/DndConfig", + "ui/DragConstraint", + "ui/DragHandle", + "ui/DragItem", + "ui/DropEffect", + "ui/DropZone", + "ui/EasingFunction", + "ui/ElementButtonProps", + "ui/ElementDataSource", + "ui/ElementFilterProps", + "ui/ElementFormProps", + "ui/ElementImageProps", + "ui/ElementMetadataViewerProps", + "ui/ElementNumberProps", + "ui/ElementRecordPickerProps", + "ui/ElementTextInputProps", + "ui/ElementTextProps", + "ui/EmbedConfig", + "ui/EvictionPolicy", + "ui/FocusManagement", + "ui/FocusTrapConfig", + "ui/FormField", + "ui/FormSection", + "ui/FormView", + "ui/GalleryConfig", + "ui/GanttConfig", + "ui/GanttQuickFilter", + "ui/GestureConfig", + "ui/GestureType", + "ui/GlobalFilter", + "ui/GlobalFilterOptionsFrom", + "ui/GroupNavItem", + "ui/GroupingConfig", + "ui/GroupingField", + "ui/HttpMethod", + "ui/HttpRequest", + "ui/I18nLabel", + "ui/I18nObject", + "ui/InterfacePageConfig", + "ui/JoinedReportBlock", + "ui/KanbanConfig", + "ui/KeyboardNavigationConfig", + "ui/KeyboardShortcut", + "ui/ListChartConfig", + "ui/ListColumn", + "ui/ListView", + "ui/LocaleConfig", + "ui/LongPressGestureConfig", + "ui/MotionConfig", + "ui/NavigationArea", + "ui/NavigationConfig", + "ui/NavigationContribution", + "ui/NavigationItem", + "ui/NavigationMode", + "ui/Notification", + "ui/NotificationAction", + "ui/NotificationConfig", + "ui/NotificationPosition", + "ui/NotificationSeverity", + "ui/NotificationType", + "ui/NumberFormat", + "ui/ObjectListView", + "ui/ObjectNavItem", + "ui/ObjectUserFilters", + "ui/OfflineCacheConfig", + "ui/OfflineConfig", + "ui/OfflineStrategy", + "ui/Page", + "ui/PageAccordionProps", + "ui/PageCardProps", + "ui/PageComponent", + "ui/PageComponentType", + "ui/PageHeaderProps", + "ui/PageNavItem", + "ui/PageRegion", + "ui/PageTabsProps", + "ui/PageTransition", + "ui/PageType", + "ui/PageVariable", + "ui/PaginationConfig", + "ui/PerformanceConfig", + "ui/PersistStorage", + "ui/PinchGestureConfig", + "ui/PluralRule", + "ui/Portal", + "ui/PortalActionNavItem", + "ui/PortalAnonymousEntry", + "ui/PortalAnonymousRoute", + "ui/PortalAuthMode", + "ui/PortalDashboardNavItem", + "ui/PortalLayout", + "ui/PortalNavItem", + "ui/PortalRateLimit", + "ui/PortalSeo", + "ui/PortalTheme", + "ui/PortalUrlNavItem", + "ui/PortalViewNavItem", + "ui/RecordActivityProps", + "ui/RecordChatterProps", + "ui/RecordDetailsProps", + "ui/RecordHighlightsField", + "ui/RecordHighlightsProps", + "ui/RecordPathProps", + "ui/RecordRelatedListProps", + "ui/Report", + "ui/ReportChart", + "ui/ReportColumn", + "ui/ReportGrouping", + "ui/ReportNavItem", + "ui/ReportType", + "ui/ResponsiveConfig", + "ui/ResponsiveStyles", + "ui/RowColorConfig", + "ui/RowHeight", + "ui/SelectionConfig", + "ui/Shadow", + "ui/SharingConfig", + "ui/Spacing", + "ui/StyleMap", + "ui/SwipeDirection", + "ui/SwipeGestureConfig", + "ui/SyncConfig", + "ui/Theme", + "ui/ThemeMode", + "ui/TimelineConfig", + "ui/TouchInteraction", + "ui/TouchTargetConfig", + "ui/TransitionConfig", + "ui/TransitionPreset", + "ui/TreeConfig", + "ui/Typography", + "ui/UrlNavItem", + "ui/UserActionsConfig", + "ui/UserFilterField", + "ui/UserFilters", + "ui/View", + "ui/ViewData", + "ui/ViewFilterRule", + "ui/ViewItem", + "ui/ViewItemName", + "ui/ViewKind", + "ui/ViewScope", + "ui/ViewSharing", + "ui/ViewTab", + "ui/VisualizationType", + "ui/WcagContrastLevel", + "ui/WidgetActionType", + "ui/WidgetColorVariant", + "ui/WidgetEvent", + "ui/WidgetLifecycle", + "ui/WidgetManifest", + "ui/WidgetProperty", + "ui/WidgetSource", + "ui/ZIndex" + ] +} diff --git a/packages/spec/scripts/build-docs.ts b/packages/spec/scripts/build-docs.ts index 36207a02d5..38dae6bf65 100644 --- a/packages/spec/scripts/build-docs.ts +++ b/packages/spec/scripts/build-docs.ts @@ -213,7 +213,13 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod for (const [key, prop] of Object.entries(props) as [string, any][]) { const typeStr = formatType(prop).replace(/\|/g, '\\|'); const isReq = required.has(key) ? '✅' : 'optional'; - let desc = escapeMdxDescription((prop.description || '').replace(/\n/g, ' ')); + // Escape for the GFM table cell last: backslashes first (so an existing + // `\|` in a description can't decay into an escaped backslash + live + // pipe), then pipes — an unescaped `|` (even inside a code span) + // splits the cell. + const desc = escapeMdxDescription((prop.description || '').replace(/\n/g, ' ')) + .replace(/\\/g, '\\\\') + .replace(/\|/g, '\\|'); t += `| **${key}** | \`${typeStr}\` | ${isReq} | ${desc} |\n`; } return t + '\n'; diff --git a/packages/spec/scripts/build-schemas.ts b/packages/spec/scripts/build-schemas.ts index 0dcee55d07..78a3d4553c 100644 --- a/packages/spec/scripts/build-schemas.ts +++ b/packages/spec/scripts/build-schemas.ts @@ -33,6 +33,10 @@ const Protocol: Record> = { }; const OUT_DIR = path.resolve(__dirname, '../json-schema'); +// Ratchet manifest: the committed record of every schema key this script has +// ever emitted. json-schema/ itself is a gitignored build artifact, so this +// file is the durable "last time" — see the disappearance check below (#2978). +const MANIFEST_PATH = path.resolve(__dirname, '../json-schema.manifest.json'); const SPEC_VERSION = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf-8')).version; const SCHEMA_BASE_URL = `https://schema.objectstack.io/v${SPEC_VERSION}`; @@ -146,6 +150,7 @@ ensureDir(OUT_DIR); console.log(`Generating JSON Schemas to ${OUT_DIR}...`); let count = 0; +let inputModeCount = 0; let skippedCount = 0; let errorCount = 0; @@ -187,28 +192,57 @@ for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) { // Check if it looks like a Zod Schema if (value instanceof z.ZodType) { const schemaName = key.endsWith('Schema') ? key.replace('Schema', '') : key; - + try { - // Convert to JSON Schema using Zod v4's built-in toJSONSchema() - const jsonSchema = z.toJSONSchema(value, { - target: 'draft-2020-12', - }); + // Convert to JSON Schema using Zod v4's built-in toJSONSchema(). + // Default is the output (post-parse) shape. When that fails because + // the schema contains a `.transform` (e.g. ExpressionInputSchema's + // string→envelope shorthand), fall back to the *input* shape: these + // JSON Schemas describe what authors write, and the input side of a + // transform pipe is plain data, so it IS representable. Without this + // fallback, adding a transform anywhere silently unpublishes the + // schema (that's how PageTabsProps vanished in #2967 — see #2978). + let jsonSchema: Record; + let io: 'output' | 'input' = 'output'; + try { + jsonSchema = z.toJSONSchema(value, { + target: 'draft-2020-12', + }) as Record; + } catch (outputError) { + if (!isKnownUnsupported(outputError)) throw outputError; + io = 'input'; + // Throws again for types unrepresentable in either direction + // (functions, Date, BigInt, custom) — caught by the outer skip. + jsonSchema = z.toJSONSchema(value, { + target: 'draft-2020-12', + io: 'input', + }) as Record; + } // Add $id URL and version metadata for IDE autocomplete and schema resolution const categorySlug = namespaceName.toLowerCase(); - (jsonSchema as Record)['$id'] = `${SCHEMA_BASE_URL}/${categorySlug}/${schemaName}.json`; - (jsonSchema as Record)['x-spec-version'] = SPEC_VERSION; + jsonSchema['$id'] = `${SCHEMA_BASE_URL}/${categorySlug}/${schemaName}.json`; + jsonSchema['x-spec-version'] = SPEC_VERSION; + if (io === 'input') { + // Flag that this schema describes the author-time (pre-parse) + // shape — parse-time transforms/defaults are not applied in it. + jsonSchema['x-io'] = 'input'; + } const fileName = `${schemaName}.json`; const filePath = path.join(categoryDir, fileName); writeFileWithRetry(filePath, JSON.stringify(jsonSchema, null, 2)); - generatedSchemas.set(`${categorySlug}/${schemaName}`, jsonSchema as Record); - console.log(` ✓ ${namespaceName.toLowerCase()}/${fileName}`); + generatedSchemas.set(`${categorySlug}/${schemaName}`, jsonSchema); + console.log(` ✓ ${namespaceName.toLowerCase()}/${fileName}${io === 'input' ? ' (input shape)' : ''}`); count++; + if (io === 'input') inputModeCount++; } catch (error) { if (isKnownUnsupported(error)) { - // Functions, transforms, Date types etc. have no JSON Schema representation — skip gracefully + // Functions, Date types etc. have no JSON Schema representation in + // either io direction — skip gracefully. The ratchet below still + // fails the build if a skip makes a previously-published schema + // disappear. const msg = error instanceof Error ? error.message : String(error); console.warn(` ⊘ ${namespaceName}.${key}: ${msg} (skipped)`); skippedCount++; @@ -223,9 +257,9 @@ for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) { } console.log(`\n─── Summary ───`); -console.log(` Generated: ${count}`); +console.log(` Generated: ${count}${inputModeCount > 0 ? ` (${inputModeCount} as input shape)` : ''}`); if (skippedCount > 0) { - console.log(` Skipped: ${skippedCount} (unsupported types: function, transform, date)`); + console.log(` Skipped: ${skippedCount} (unsupported types: function, date, bigint, custom)`); } if (errorCount > 0) { @@ -234,6 +268,63 @@ if (errorCount > 0) { process.exit(1); } +// ─── Ratchet: a published schema must never silently disappear ──────── +// json-schema/ is a public contract surface (IDE validation, gen:docs input, +// $id URLs under schema.objectstack.io). The manifest is the committed record +// of every schema key ever emitted; a key present there but absent from this +// run means a code change unpublished a schema — fail loudly instead of +// letting gen:docs quietly delete its reference docs (#2978). Deliberate +// removals must delete the key from the manifest in the same PR. +interface SchemaManifest { + description?: string; + schemas: string[]; +} + +let manifest: SchemaManifest | null = null; +try { + manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8')) as SchemaManifest; +} catch (error) { + // A missing manifest just means first run (bootstrap below); anything else + // (unreadable, invalid JSON) must fail rather than silently drop the ratchet. + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { + console.error(`\n❌ Failed to read ${MANIFEST_PATH}: ${error}`); + process.exit(1); + } +} + +const generatedKeys = new Set(generatedSchemas.keys()); +const missing = (manifest?.schemas ?? []).filter((key) => !generatedKeys.has(key)); +if (missing.length > 0) { + console.error(`\n❌ ${missing.length} previously published schema(s) disappeared from this build:`); + for (const key of missing) { + console.error(` - json-schema/${key}.json`); + } + console.error( + `\n A schema listed in json-schema.manifest.json was not emitted. This usually means a\n` + + ` Zod change made it unrepresentable (e.g. an added .transform in "output" AND "input"\n` + + ` io modes) or an export was renamed/removed. Fix the schema, or — if the removal is\n` + + ` deliberate — delete the key(s) from packages/spec/json-schema.manifest.json in the\n` + + ` same PR. Silently unpublishing a schema deletes its reference docs on the next\n` + + ` gen:docs run (see #2978).`, + ); + process.exit(1); +} + +const added = [...generatedKeys].filter((key) => !(manifest?.schemas ?? []).includes(key)); +if (!manifest || added.length > 0) { + const updated: SchemaManifest = { + description: + 'Ratchet manifest of every JSON Schema emitted by scripts/build-schemas.ts. ' + + 'Auto-appended when new schemas are added (commit the change). A listed schema that a ' + + 'build no longer emits fails gen:schema — remove a key ONLY for a deliberate retirement. See #2978.', + schemas: [...generatedKeys].sort(), + }; + fs.writeFileSync(MANIFEST_PATH, JSON.stringify(updated, null, 2) + '\n'); + console.log( + `\n📒 json-schema.manifest.json ${manifest ? `updated (+${added.length} schema(s))` : `created (${generatedKeys.size} schemas)`} — commit it.`, + ); +} + // ─── Generate Bundled Schema ───────────────────────────────────────── // Single-file bundled schema containing all generated schemas for IDE autocomplete