From 0897ad5329c4047d31c8ad7ee561abf151a93885 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 17 Jul 2026 21:03:32 +0800 Subject: [PATCH] docs(generator): fix reference $ref links and opaque Object types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 243 generated reference pages carried ~92 links to a page that never existed (`[__schema0](./__schema0)`), 6 self-links to `(./#)`, and every inline object rendered as an opaque `Object`. Root causes, all in build-docs.ts: - `formatType` turned `$ref` into `./`, but pages are named after the *zod file* — so no `$ref` link could ever resolve. Named refs now resolve through the schemaCategoryMap/schemaZodFileMap that scanCategories() already built (dead code until now) to `/docs/references//#`, and fall back to plain text rather than a 404 when no page exists. - `__schemaN` refs are Zod-hoisted inline schemas with no page at all; they are now expanded structurally, with a cycle guard (these schemas are recursive — a node contains nodes — and naive inlining blows the stack). - `$ref: "#"` (self-reference) now links to the section's own anchor. - Inline objects render their shape one level deep (`{ label: string; value: string; color?: string; … }`) instead of `Object`; const variants render their literal, so discriminated unions read as `'a' | 'b'` rather than `Object | Object`. - JSDoc `{@link ../automation/sync.zod.ts}` linked to a repo path that 404s on the site; source paths now rewrite to their docs route, and a bare `@see` renders as "See also:" prose instead of a stray tag. - Property type cells escape backslashes before pipes, matching the neighbouring `desc` escaping (and its comment) — CodeQL's js/incomplete-sanitization on the old order. Counts after regenerating: __schemaN links 92 → 0, (./#) 6 → 0, zod.ts links → 0. Passes the new `--check` gate from #3134. Co-Authored-By: Claude Fable 5 --- content/docs/references/ai/agent.mdx | 18 +- content/docs/references/ai/conversation.mdx | 40 +-- .../docs/references/ai/knowledge-source.mdx | 20 +- content/docs/references/ai/mcp.mdx | 2 +- content/docs/references/ai/model-registry.mdx | 26 +- content/docs/references/ai/skill.mdx | 4 +- .../docs/references/ai/solution-blueprint.mdx | 28 +- content/docs/references/ai/tool.mdx | 2 +- content/docs/references/ai/usage.mdx | 2 +- content/docs/references/api/analytics.mdx | 20 +- .../docs/references/api/auth-endpoints.mdx | 30 +-- content/docs/references/api/auth.mdx | 12 +- .../docs/references/api/automation-api.mdx | 66 ++--- content/docs/references/api/batch.mdx | 20 +- content/docs/references/api/connector.mdx | 4 +- content/docs/references/api/contract.mdx | 50 ++-- content/docs/references/api/discovery.mdx | 14 +- content/docs/references/api/dispatcher.mdx | 6 +- content/docs/references/api/documentation.mdx | 48 ++-- content/docs/references/api/endpoint.mdx | 8 +- content/docs/references/api/errors.mdx | 8 +- content/docs/references/api/export.mdx | 62 ++--- content/docs/references/api/feed-api.mdx | 92 +++---- content/docs/references/api/graphql.mdx | 98 +++---- content/docs/references/api/http-cache.mdx | 12 +- .../docs/references/api/metadata-plugin.mdx | 2 +- content/docs/references/api/metadata.mdx | 108 ++++---- content/docs/references/api/object.mdx | 4 +- content/docs/references/api/odata.mdx | 12 +- content/docs/references/api/package-api.mdx | 58 ++-- .../docs/references/api/package-registry.mdx | 14 +- .../docs/references/api/plugin-rest-api.mdx | 34 +-- content/docs/references/api/protocol.mdx | 112 ++++---- content/docs/references/api/query-adapter.mdx | 28 +- .../docs/references/api/realtime-shared.mdx | 4 +- content/docs/references/api/realtime.mdx | 4 +- content/docs/references/api/registry.mdx | 36 +-- content/docs/references/api/rest-server.mdx | 38 +-- content/docs/references/api/router.mdx | 6 +- content/docs/references/api/storage.mdx | 38 +-- content/docs/references/api/versioning.mdx | 2 +- content/docs/references/api/websocket.mdx | 80 +++--- .../docs/references/automation/approval.mdx | 4 +- .../references/automation/bpmn-interop.mdx | 6 +- .../docs/references/automation/connector.mdx | 24 +- .../references/automation/control-flow.mdx | 26 +- content/docs/references/automation/etl.mdx | 30 +-- .../docs/references/automation/execution.mdx | 8 +- content/docs/references/automation/flow.mdx | 26 +- .../references/automation/state-machine.mdx | 20 +- content/docs/references/automation/sync.mdx | 18 +- .../automation/trigger-registry.mdx | 20 +- .../docs/references/automation/webhook.mdx | 6 +- content/docs/references/cloud/app-store.mdx | 18 +- .../references/cloud/developer-portal.mdx | 12 +- .../references/cloud/environment-package.mdx | 2 +- content/docs/references/cloud/environment.mdx | 6 +- .../references/cloud/marketplace-admin.mdx | 2 +- content/docs/references/cloud/marketplace.mdx | 16 +- .../docs/references/cloud/package-version.mdx | 2 +- content/docs/references/cloud/package.mdx | 6 +- .../references/cloud/template-manifest.mdx | 6 +- content/docs/references/cloud/tenant.mdx | 2 +- content/docs/references/data/analytics.mdx | 14 +- content/docs/references/data/data-engine.mdx | 140 +++++----- content/docs/references/data/datasource.mdx | 16 +- content/docs/references/data/document.mdx | 12 +- content/docs/references/data/driver-nosql.mdx | 22 +- content/docs/references/data/driver-sql.mdx | 10 +- content/docs/references/data/driver.mdx | 4 +- .../docs/references/data/external-catalog.mdx | 6 +- .../docs/references/data/external-lookup.mdx | 22 +- content/docs/references/data/feed.mdx | 8 +- content/docs/references/data/field.mdx | 34 +-- content/docs/references/data/filter.mdx | 2 +- content/docs/references/data/hook-body.mdx | 8 +- content/docs/references/data/hook.mdx | 4 +- content/docs/references/data/mapping.mdx | 6 +- content/docs/references/data/object.mdx | 64 ++--- content/docs/references/data/query.mdx | 34 +-- content/docs/references/data/seed-loader.mdx | 24 +- content/docs/references/data/validation.mdx | 44 +-- .../docs/references/identity/eval-user.mdx | 2 +- content/docs/references/identity/scim.mdx | 46 ++-- .../references/integration/connector-auth.mdx | 16 +- .../docs/references/integration/connector.mdx | 72 ++--- content/docs/references/integration/http.mdx | 2 +- .../docs/references/integration/mapping.mdx | 2 +- content/docs/references/integration/misc.mdx | 250 +++++++++--------- .../docs/references/kernel/cli-extension.mdx | 2 +- content/docs/references/kernel/context.mdx | 6 +- .../kernel/dependency-resolution.mdx | 4 +- content/docs/references/kernel/dev-plugin.mdx | 6 +- .../references/kernel/execution-context.mdx | 2 +- content/docs/references/kernel/feature.mdx | 2 +- content/docs/references/kernel/manifest.mdx | 18 +- .../kernel/metadata-customization.mdx | 8 +- .../references/kernel/metadata-loader.mdx | 8 +- .../kernel/metadata-persistence.mdx | 8 +- .../references/kernel/metadata-plugin.mdx | 36 +-- content/docs/references/kernel/misc.mdx | 42 +-- .../references/kernel/package-artifact.mdx | 6 +- .../references/kernel/package-registry.mdx | 20 +- .../references/kernel/package-upgrade.mdx | 14 +- .../references/kernel/plugin-capability.mdx | 24 +- .../kernel/plugin-lifecycle-advanced.mdx | 38 +-- .../kernel/plugin-lifecycle-events.mdx | 2 +- .../docs/references/kernel/plugin-loading.mdx | 48 ++-- .../references/kernel/plugin-registry.mdx | 26 +- .../docs/references/kernel/plugin-runtime.mdx | 12 +- .../kernel/plugin-security-advanced.mdx | 66 ++--- .../references/kernel/plugin-security.mdx | 68 ++--- .../references/kernel/plugin-structure.mdx | 2 +- .../references/kernel/plugin-validator.mdx | 4 +- .../references/kernel/plugin-versioning.mdx | 36 +-- .../references/kernel/service-registry.mdx | 4 +- .../kernel/startup-orchestrator.mdx | 6 +- .../docs/references/kernel/state-machine.mdx | 2 +- content/docs/references/qa/testing.mdx | 14 +- content/docs/references/security/explain.mdx | 16 +- .../docs/references/security/permission.mdx | 8 +- content/docs/references/security/rls.mdx | 4 +- content/docs/references/security/sharing.mdx | 24 +- content/docs/references/shared/expression.mdx | 14 +- content/docs/references/shared/mapping.mdx | 14 +- content/docs/references/shared/protection.mdx | 6 +- .../docs/references/studio/flow-builder.mdx | 8 +- .../references/studio/object-designer.mdx | 22 +- content/docs/references/studio/plugin.mdx | 14 +- .../docs/references/system/app-install.mdx | 2 +- content/docs/references/system/audit.mdx | 26 +- .../docs/references/system/auth-config.mdx | 20 +- content/docs/references/system/book.mdx | 16 +- content/docs/references/system/cache.mdx | 26 +- .../references/system/change-management.mdx | 18 +- .../docs/references/system/collaboration.mdx | 76 +++--- .../docs/references/system/deploy-bundle.mdx | 10 +- .../references/system/disaster-recovery.mdx | 28 +- content/docs/references/system/doc.mdx | 2 +- .../docs/references/system/email-config.mdx | 2 +- .../docs/references/system/email-template.mdx | 6 +- content/docs/references/system/encryption.mdx | 4 +- .../system/environment-artifact.mdx | 24 +- .../docs/references/system/http-server.mdx | 18 +- .../references/system/incident-response.mdx | 8 +- content/docs/references/system/job.mdx | 20 +- content/docs/references/system/logging.mdx | 48 ++-- .../docs/references/system/message-queue.mdx | 8 +- .../references/system/metadata-loader.mdx | 8 +- .../system/metadata-persistence.mdx | 12 +- content/docs/references/system/metrics.mdx | 46 ++-- content/docs/references/system/migration.mdx | 42 +-- .../docs/references/system/notification.mdx | 24 +- .../docs/references/system/object-storage.mdx | 18 +- .../docs/references/system/provisioning.mdx | 2 +- .../references/system/registry-config.mdx | 16 +- .../docs/references/system/search-engine.mdx | 8 +- .../references/system/security-context.mdx | 12 +- .../references/system/settings-manifest.mdx | 22 +- .../references/system/supplier-security.mdx | 6 +- content/docs/references/system/tenant.mdx | 58 ++-- content/docs/references/system/tracing.mdx | 40 +-- content/docs/references/system/training.mdx | 4 +- .../docs/references/system/translation.mdx | 50 ++-- content/docs/references/system/worker.mdx | 14 +- content/docs/references/ui/action.mdx | 22 +- content/docs/references/ui/animation.mdx | 12 +- content/docs/references/ui/app.mdx | 98 +++---- content/docs/references/ui/chart.mdx | 12 +- content/docs/references/ui/component.mdx | 62 ++--- content/docs/references/ui/dashboard.mdx | 36 +-- content/docs/references/ui/dataset.mdx | 14 +- content/docs/references/ui/dnd.mdx | 6 +- content/docs/references/ui/i18n.mdx | 4 +- content/docs/references/ui/keyboard.mdx | 6 +- content/docs/references/ui/notification.mdx | 2 +- content/docs/references/ui/offline.mdx | 4 +- content/docs/references/ui/page.mdx | 42 +-- content/docs/references/ui/portal.mdx | 52 ++-- content/docs/references/ui/report.mdx | 26 +- content/docs/references/ui/responsive.mdx | 6 +- content/docs/references/ui/theme.mdx | 36 +-- content/docs/references/ui/touch.mdx | 12 +- content/docs/references/ui/view.mdx | 190 ++++++------- content/docs/references/ui/widget.mdx | 24 +- packages/spec/scripts/build-docs.ts | 140 ++++++++-- 186 files changed, 2357 insertions(+), 2253 deletions(-) diff --git a/content/docs/references/ai/agent.mdx b/content/docs/references/ai/agent.mdx index 61ca266add..bd63714351 100644 --- a/content/docs/references/ai/agent.mdx +++ b/content/docs/references/ai/agent.mdx @@ -74,22 +74,22 @@ const result = AIKnowledge.parse(data); | **avatar** | `string` | optional | | | **role** | `string` | ✅ | The persona/role (e.g. "Senior Support Engineer") | | **instructions** | `string` | ✅ | System Prompt / Prime Directives | -| **model** | `Object` | optional | | -| **lifecycle** | `Object` | optional | State machine defining the agent conversation follow and constraints | +| **model** | `{ provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>; model: string; temperature: number; maxTokens?: number; … }` | optional | | +| **lifecycle** | `{ id: string; description?: string; contextSchema?: Record; initial: string; … }` | optional | State machine defining the agent conversation follow and constraints | | **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 | +| **tools** | `{ type: Enum<'action' \| 'flow' \| 'query' \| 'vector_search'>; name: string; description?: string }[]` | optional | Direct tool references (legacy fallback) | +| **knowledge** | `{ topics: string[]; indexes: string[] }` | optional | RAG access | | **active** | `boolean` | ✅ | | | **access** | `string[]` | optional | Who can chat with this agent | | **permissions** | `string[]` | optional | Required permission-set capabilities | | **tenantId** | `string` | optional | Tenant/Organization ID | | **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ | [EXPERIMENTAL — NOT ENFORCED, #1901] Intended listing scope. No runtime consumer yet; use access/permissions for real gating. | -| **planning** | `Object` | optional | Autonomous reasoning and planning configuration | -| **memory** | `Object` | optional | Agent memory management | -| **guardrails** | `Object` | optional | Safety guardrails for the agent | -| **structuredOutput** | `Object` | optional | Structured output format and validation configuration | -| **protection** | `Object` | optional | Package author protection block — lock policy for this agent. | +| **planning** | `{ strategy: Enum<'react' \| 'plan_and_execute' \| 'reflexion' \| 'tree_of_thought'>; maxIterations: integer; allowReplan: boolean }` | optional | Autonomous reasoning and planning configuration | +| **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | Agent memory management | +| **guardrails** | `{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }` | optional | Safety guardrails for the agent | +| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>; schema?: Record; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | Structured output format and validation configuration | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | diff --git a/content/docs/references/ai/conversation.mdx b/content/docs/references/ai/conversation.mdx index be7c66c117..9a0d4ae870 100644 --- a/content/docs/references/ai/conversation.mdx +++ b/content/docs/references/ai/conversation.mdx @@ -33,7 +33,7 @@ const result = CodeContent.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'code'` | ✅ | | | **text** | `string` | ✅ | Code snippet | | **language** | `string` | ✅ | | | **metadata** | `Record` | optional | | @@ -93,12 +93,12 @@ const result = CodeContent.parse(data); | **id** | `string` | ✅ | Unique message ID | | **timestamp** | `string` | ✅ | ISO 8601 timestamp | | **role** | `Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>` | ✅ | | -| **content** | `Object \| Object \| Object \| Object[]` | ✅ | Message content (multimodal array) | -| **functionCall** | `Object` | optional | Legacy function call | -| **toolCalls** | `Object[]` | optional | Tool calls | +| **content** | `{ type: 'text'; text: string; metadata?: Record } \| { type: 'image'; imageUrl: string; detail: Enum<'low' \| 'high' \| 'auto'>; metadata?: Record } \| { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } \| { type: 'code'; text: string; language: string; metadata?: Record }[]` | ✅ | Message content (multimodal array) | +| **functionCall** | `{ name: string; arguments: string; result?: string }` | optional | Legacy function call | +| **toolCalls** | `{ id: string; type: Enum<'function'>; function: object }[]` | optional | Tool calls | | **toolCallId** | `string` | optional | Tool call ID this message responds to | | **name** | `string` | optional | Name of the function/user | -| **tokens** | `Object` | optional | Token usage for this message | +| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Token usage for this message | | **cost** | `number` | optional | Cost for this message in USD | | **pinned** | `boolean` | ✅ | Prevent removal during pruning | | **importance** | `number` | optional | Importance score for pruning | @@ -116,12 +116,12 @@ const result = CodeContent.parse(data); | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique session ID | | **name** | `string` | optional | Session name/title | -| **context** | `Object` | ✅ | | +| **context** | `{ sessionId: string; userId?: string; agentId?: string; object?: string; … }` | ✅ | | | **modelId** | `string` | optional | AI model ID | -| **tokenBudget** | `Object` | ✅ | | -| **messages** | `Object[]` | ✅ | | -| **tokens** | `Object` | optional | | -| **totalTokens** | `Object` | optional | Total tokens across all messages | +| **tokenBudget** | `{ maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens: integer; … }` | ✅ | | +| **messages** | `{ id: string; timestamp: string; role: Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>; content: { type: 'text'; text: string; metadata?: Record } \| { type: 'image'; imageUrl: string; detail: Enum<'low' \| 'high' \| 'auto'>; metadata?: Record } \| { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } \| { type: 'code'; text: string; language: string; metadata?: Record }[]; … }[]` | ✅ | | +| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer; budgetLimit: integer; … }` | optional | | +| **totalTokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Total tokens across all messages | | **totalCost** | `number` | optional | Total cost for this session in USD | | **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | ✅ | | | **createdAt** | `string` | ✅ | ISO 8601 timestamp | @@ -143,7 +143,7 @@ const result = CodeContent.parse(data); | **originalTokens** | `integer` | ✅ | Original token count | | **summaryTokens** | `integer` | ✅ | Summary token count | | **tokensSaved** | `integer` | ✅ | Tokens saved | -| **messageRange** | `Object` | ✅ | Range of messages summarized | +| **messageRange** | `{ startIndex: integer; endIndex: integer }` | ✅ | Range of messages summarized | | **generatedAt** | `string` | ✅ | ISO 8601 timestamp | | **modelId** | `string` | optional | Model used for summarization | @@ -156,7 +156,7 @@ const result = CodeContent.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'file'` | ✅ | | | **fileUrl** | `string` | ✅ | File attachment URL | | **mimeType** | `string` | ✅ | MIME type | | **fileName** | `string` | optional | | @@ -184,7 +184,7 @@ const result = CodeContent.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'image'` | ✅ | | | **imageUrl** | `string` | ✅ | Image URL | | **detail** | `Enum<'low' \| 'high' \| 'auto'>` | ✅ | | | **metadata** | `Record` | optional | | @@ -206,7 +206,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'text'` | ✅ | | | **text** | `string` | ✅ | Text content | | **metadata** | `Record` | optional | | @@ -220,7 +220,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'image'` | ✅ | | | **imageUrl** | `string` | ✅ | Image URL | | **detail** | `Enum<'low' \| 'high' \| 'auto'>` | ✅ | | | **metadata** | `Record` | optional | | @@ -235,7 +235,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'file'` | ✅ | | | **fileUrl** | `string` | ✅ | File attachment URL | | **mimeType** | `string` | ✅ | MIME type | | **fileName** | `string` | optional | | @@ -251,7 +251,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'code'` | ✅ | | | **text** | `string` | ✅ | Code snippet | | **language** | `string` | ✅ | | | **metadata** | `Record` | optional | | @@ -281,7 +281,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **timestamp** | `string` | ✅ | Event timestamp | -| **prunedMessages** | `Object[]` | ✅ | | +| **prunedMessages** | `{ messageId: string; role: Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>; tokens: integer; importance?: number }[]` | ✅ | | | **tokensFreed** | `integer` | ✅ | | | **messagesRemoved** | `integer` | ✅ | | | **remainingTokens** | `integer` | ✅ | | @@ -309,7 +309,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'text'` | ✅ | | | **text** | `string` | ✅ | Text content | | **metadata** | `Record` | optional | | @@ -380,7 +380,7 @@ This schema accepts one of the following structures: | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Tool call ID | | **type** | `Enum<'function'>` | ✅ | | -| **function** | `Object` | ✅ | | +| **function** | `{ name: string; arguments: string; result?: string }` | ✅ | | --- diff --git a/content/docs/references/ai/knowledge-source.mdx b/content/docs/references/ai/knowledge-source.mdx index 072db25b1d..2e2f7e0812 100644 --- a/content/docs/references/ai/knowledge-source.mdx +++ b/content/docs/references/ai/knowledge-source.mdx @@ -43,7 +43,7 @@ const result = FileKnowledgeSource.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'file'` | ✅ | | | **prefix** | `string` | ✅ | Storage prefix | | **mimeTypes** | `string[]` | optional | | @@ -56,7 +56,7 @@ const result = FileKnowledgeSource.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'http'` | ✅ | | | **urls** | `string[]` | ✅ | | | **userAgent** | `string` | optional | | @@ -86,10 +86,10 @@ const result = FileKnowledgeSource.parse(data); | **description** | `string` | optional | | | **adapter** | `string` | ✅ | Adapter id | | **adapterConfig** | `Record` | optional | | -| **source** | `Object \| Object \| Object` | ✅ | | -| **embedding** | `Object` | optional | | -| **vectorStore** | `Object` | optional | | -| **refresh** | `Object` | optional | | +| **source** | `{ kind: 'object'; object: string; contentFields: string[]; metadataFields?: string[]; … } \| { kind: 'file'; prefix: string; mimeTypes?: string[] } \| { kind: 'http'; urls: string[]; userAgent?: string }` | ✅ | | +| **embedding** | `{ provider: Enum<'openai' \| 'cohere' \| 'azure_openai' \| 'huggingface' \| 'local' \| 'custom'>; model: string; dimensions: integer; endpoint?: string; … }` | optional | | +| **vectorStore** | `{ provider: Enum<'pgvector' \| 'chroma' \| 'qdrant' \| 'pinecone' \| 'weaviate' \| 'milvus' \| 'redis' \| 'opensearch' \| 'elasticsearch' \| 'custom'>; collection: string; endpoint?: string; secretRef?: string; … }` | optional | | +| **refresh** | `{ onRecordChange?: boolean; cron?: string }` | optional | | | **aiExposed** | `boolean` | optional | | @@ -107,7 +107,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'object'` | ✅ | | | **object** | `string` | ✅ | Short object name to index | | **contentFields** | `string[]` | ✅ | Fields contributing to document content | | **metadataFields** | `string[]` | optional | | @@ -121,7 +121,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'file'` | ✅ | | | **prefix** | `string` | ✅ | Storage prefix | | **mimeTypes** | `string[]` | optional | | @@ -133,7 +133,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'http'` | ✅ | | | **urls** | `string[]` | ✅ | | | **userAgent** | `string` | optional | | @@ -148,7 +148,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'object'` | ✅ | | | **object** | `string` | ✅ | Short object name to index | | **contentFields** | `string[]` | ✅ | Fields contributing to document content | | **metadataFields** | `string[]` | optional | | diff --git a/content/docs/references/ai/mcp.mdx b/content/docs/references/ai/mcp.mdx index 7ceef85de9..1b32bccff0 100644 --- a/content/docs/references/ai/mcp.mdx +++ b/content/docs/references/ai/mcp.mdx @@ -23,7 +23,7 @@ server (so an agent can mount its tools). 2. **MCPToolBinding** — how an MCP tool from a referenced server -is exposed as an ObjectStack [AIToolDefinition](AIToolDefinition) (alias, +is exposed as an ObjectStack `AIToolDefinition` (alias, visibility, approval policy). diff --git a/content/docs/references/ai/model-registry.mdx b/content/docs/references/ai/model-registry.mdx index 855d6b37f6..2b33904f4e 100644 --- a/content/docs/references/ai/model-registry.mdx +++ b/content/docs/references/ai/model-registry.mdx @@ -54,9 +54,9 @@ const result = ModelCapability.parse(data); | **name** | `string` | ✅ | Model display name | | **version** | `string` | ✅ | Model version (e.g., "gpt-4-turbo-2024-04-09") | | **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ | | -| **capabilities** | `Object` | ✅ | | -| **limits** | `Object` | ✅ | | -| **pricing** | `Object` | optional | | +| **capabilities** | `{ textGeneration: boolean; textEmbedding: boolean; imageGeneration: boolean; imageUnderstanding: boolean; … }` | ✅ | | +| **limits** | `{ maxTokens: integer; contextWindow: integer; maxOutputTokens?: integer; rateLimit?: object }` | ✅ | | +| **pricing** | `{ currency: string; inputCostPer1kTokens?: number; outputCostPer1kTokens?: number; embeddingCostPer1kTokens?: number }` | optional | | | **endpoint** | `string` | optional | Custom API endpoint | | **apiKey** | `string` | optional | API key (Warning: Prefer secretRef) | | **secretRef** | `string` | optional | Reference to stored secret (e.g. system:openai_api_key) | @@ -78,7 +78,7 @@ const result = ModelCapability.parse(data); | **maxTokens** | `integer` | ✅ | Maximum tokens per request | | **contextWindow** | `integer` | ✅ | Context window size | | **maxOutputTokens** | `integer` | optional | Maximum output tokens | -| **rateLimit** | `Object` | optional | | +| **rateLimit** | `{ requestsPerMinute?: integer; tokensPerMinute?: integer }` | optional | | --- @@ -120,8 +120,8 @@ const result = ModelCapability.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Registry name | -| **models** | `Record` | ✅ | Model entries by ID | -| **promptTemplates** | `Record` | optional | Prompt templates by name | +| **models** | `Record; priority?: integer; fallbackModels?: string[]; … }>` | ✅ | Model entries by ID | +| **promptTemplates** | `Record; source?: string; ast?: any; meta?: object }; … }>` | optional | Prompt templates by name | | **defaultModel** | `string` | optional | Default model ID | | **enableAutoFallback** | `boolean` | optional | Auto-fallback on errors | @@ -134,11 +134,11 @@ const result = ModelCapability.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **model** | `Object` | ✅ | | +| **model** | `{ id: string; name: string; version: string; provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>; … }` | ✅ | | | **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>` | ✅ | | | **priority** | `integer` | ✅ | Priority for model selection | | **fallbackModels** | `string[]` | optional | Fallback model IDs | -| **healthCheck** | `Object` | optional | | +| **healthCheck** | `{ enabled: boolean; intervalSeconds: integer; lastChecked?: string; status: Enum<'healthy' \| 'unhealthy' \| 'unknown'> }` | optional | | --- @@ -168,10 +168,10 @@ const result = ModelCapability.parse(data); | **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 | +| **system** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | System prompt — supports `{{var}`} interpolation | +| **user** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | User prompt template — supports `{{var}`} interpolation | | **assistant** | `string` | optional | Assistant message prefix | -| **variables** | `Object[]` | optional | Template variables | +| **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; defaultValue?: any; … }[]` | optional | Template variables | | **modelId** | `string` | optional | Recommended model ID | | **temperature** | `number` | optional | | | **maxTokens** | `number` | optional | | @@ -183,7 +183,7 @@ const result = ModelCapability.parse(data); | **description** | `string` | optional | | | **category** | `string` | optional | Template category (e.g., "code_generation", "support") | | **tags** | `string[]` | optional | | -| **examples** | `Object[]` | optional | | +| **examples** | `{ input: Record; output: string }[]` | optional | | --- @@ -199,7 +199,7 @@ const result = ModelCapability.parse(data); | **required** | `boolean` | ✅ | | | **defaultValue** | `any` | optional | | | **description** | `string` | optional | | -| **validation** | `Object` | optional | | +| **validation** | `{ minLength?: number; maxLength?: number; pattern?: string; enum?: any[] }` | optional | | --- diff --git a/content/docs/references/ai/skill.mdx b/content/docs/references/ai/skill.mdx index 75ad71370d..63021f602b 100644 --- a/content/docs/references/ai/skill.mdx +++ b/content/docs/references/ai/skill.mdx @@ -40,10 +40,10 @@ const result = Skill.parse(data); | **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 | -| **triggerConditions** | `Object[]` | optional | Programmatic activation conditions | +| **triggerConditions** | `{ field: string; operator: Enum<'eq' \| 'neq' \| 'in' \| 'not_in' \| 'contains'>; value: string \| string[] }[]` | optional | Programmatic activation conditions | | **permissions** | `string[]` | optional | Required permissions or roles | | **active** | `boolean` | ✅ | Whether the skill is enabled | -| **protection** | `Object` | optional | Package author protection block — lock policy for this skill. | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | diff --git a/content/docs/references/ai/solution-blueprint.mdx b/content/docs/references/ai/solution-blueprint.mdx index 5a4870b29f..17f37014f3 100644 --- a/content/docs/references/ai/solution-blueprint.mdx +++ b/content/docs/references/ai/solution-blueprint.mdx @@ -13,7 +13,7 @@ The structured-output target an AI agent emits for a *high-level* goal list. It is a **simplified proposal shape** — deliberately lighter than the -full [ObjectSchema](ObjectSchema) / [ViewSchema](ViewSchema) / [DashboardSchema](DashboardSchema). +full `ObjectSchema` / `ViewSchema` / `DashboardSchema`. The `apply_blueprint` tool expands each entry into a proper metadata body @@ -52,7 +52,7 @@ const result = BlueprintApp.parse(data); | **name** | `string` | ✅ | App machine name (snake_case) | | **label** | `string` | optional | App display label | | **icon** | `string` | optional | Lucide icon for the App Launcher | -| **nav** | `Object[]` | optional | Navigation entries; omit to auto-surface every created object and dashboard | +| **nav** | `{ type: Enum<'object' \| 'dashboard'>; target: string; label?: string; icon?: string }[]` | optional | Navigation entries; omit to auto-surface every created object and dashboard | --- @@ -65,7 +65,7 @@ const result = BlueprintApp.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Dashboard machine name (snake_case) | | **label** | `string` | optional | Human-readable dashboard label | -| **widgets** | `Object[]` | optional | Widgets to place on the dashboard | +| **widgets** | `{ id: string; title?: string; object?: string; chart?: Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'table'>; … }[]` | optional | Widgets to place on the dashboard | --- @@ -81,7 +81,7 @@ const result = BlueprintApp.parse(data); | **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 | | **required** | `boolean` | optional | Whether the field is required | | **reference** | `string` | optional | Target object name for lookup / master_detail relationship fields | -| **options** | `Object[]` | optional | Choices for select / multiselect / radio fields | +| **options** | `{ label: string; value: string }[]` | optional | Choices for select / multiselect / radio fields | --- @@ -109,7 +109,7 @@ const result = BlueprintApp.parse(data); | **name** | `string` | ✅ | Object machine name (snake_case) | | **label** | `string` | optional | Human-readable singular label | | **description** | `string` | optional | What this object represents | -| **fields** | `Object[]` | ✅ | Fields to create on the object | +| **fields** | `{ name: string; label?: string; 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'>; required?: boolean; … }[]` | ✅ | Fields to create on the object | | **nameField** | `string` | optional | The record title field — which field holds the human-readable name shown on cards, lookup chips, breadcrumbs and search (ADR-0079). Set it to the object's text label field (e.g. "product_name"). For a numbered entity (invoice/ticket), set it to a formula field that composes number + name (e.g. "`{order_no}` · `{customer}`"). Omitting it lets the platform auto-pick a text field, but declaring it is strongly preferred. | @@ -165,11 +165,11 @@ const result = BlueprintApp.parse(data); | **summary** | `string` | ✅ | One-line description of the proposed solution | | **assumptions** | `string[]` | ✅ | Design assumptions made from the underspecified goal | | **questions** | `string[]` | optional | At most 1-2 structure-deciding questions to confirm before building | -| **objects** | `Object[]` | ✅ | Objects (tables) to create | -| **views** | `Object[]` | optional | Views to create | -| **dashboards** | `Object[]` | optional | Dashboards to create | -| **app** | `Object` | optional | The navigation shell (app) that surfaces the created objects/dashboards to end users | -| **seedData** | `Object[]` | optional | Suggested seed data (reported, not auto-applied in Phase C) | +| **objects** | `{ name: string; label?: string; description?: string; fields: { name: string; label?: string; 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'>; required?: boolean; … }[]; … }[]` | ✅ | Objects (tables) to create | +| **views** | `{ object: string; name: string; label?: string; type: Enum<'list' \| 'form' \| 'kanban' \| 'calendar' \| 'gallery' \| 'gantt'>; … }[]` | optional | Views to create | +| **dashboards** | `{ name: string; label?: string; widgets?: { id: string; title?: string; object?: string; chart?: Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'table'>; … }[] }[]` | optional | Dashboards to create | +| **app** | `{ name: string; label?: string; icon?: string; nav?: { type: Enum<'object' \| 'dashboard'>; target: string; label?: string; icon?: string }[] }` | optional | The navigation shell (app) that surfaces the created objects/dashboards to end users | +| **seedData** | `{ object: string; records: Record[] }[]` | optional | Suggested seed data (reported, not auto-applied in Phase C) | --- @@ -183,10 +183,10 @@ const result = BlueprintApp.parse(data); | **summary** | `string` | ✅ | One-line description of the proposed solution | | **assumptions** | `string[]` | ✅ | Design assumptions made from the underspecified goal | | **questions** | `string[] \| null` | ✅ | At most 1-2 structure-deciding questions to confirm before building, or null | -| **objects** | `Object[]` | ✅ | Objects (tables) to create | -| **views** | `Object[] \| null` | ✅ | Views to create, or null | -| **dashboards** | `Object[] \| null` | ✅ | Dashboards to create, or null | -| **app** | `Object \| null` | ✅ | The navigation shell (app) that surfaces the created objects/dashboards, or null | +| **objects** | `{ name: string; label: string \| null; description: string \| null; fields: { name: string; label: string \| null; 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'>; required: boolean \| null; … }[] }[]` | ✅ | Objects (tables) to create | +| **views** | `{ object: string; name: string; label: string \| null; type: Enum<'list' \| 'form' \| 'kanban' \| 'calendar' \| 'gallery' \| 'gantt'> \| null; … }[] \| null` | ✅ | Views to create, or null | +| **dashboards** | `{ name: string; label: string \| null; widgets: { id: string; title: string \| null; object: string \| null; chart: Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'table'> \| null; … }[] \| null }[] \| null` | ✅ | Dashboards to create, or null | +| **app** | `{ name: string; label: string \| null; icon: string \| null; nav: { type: Enum<'object' \| 'dashboard'>; target: string; label: string \| null; icon: string \| null }[] \| null } \| null` | ✅ | The navigation shell (app) that surfaces the created objects/dashboards, or null | --- diff --git a/content/docs/references/ai/tool.mdx b/content/docs/references/ai/tool.mdx index c7fdd70eeb..8397d3578e 100644 --- a/content/docs/references/ai/tool.mdx +++ b/content/docs/references/ai/tool.mdx @@ -42,7 +42,7 @@ const result = Tool.parse(data); | **permissions** | `string[]` | optional | Required permission-set capabilities | | **active** | `boolean` | ✅ | Whether the tool is enabled | | **builtIn** | `boolean` | ✅ | Platform built-in tool flag | -| **protection** | `Object` | optional | Package author protection block — lock policy for this tool. | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | diff --git a/content/docs/references/ai/usage.mdx b/content/docs/references/ai/usage.mdx index 65480e83a9..2f7f169f5f 100644 --- a/content/docs/references/ai/usage.mdx +++ b/content/docs/references/ai/usage.mdx @@ -54,7 +54,7 @@ const result = AIUsageRecord.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **model** | `string` | ✅ | | -| **usage** | `Object` | ✅ | | +| **usage** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | ✅ | | | **costUsd** | `number` | ✅ | Computed cost in USD | | **latencyMs** | `number` | optional | | | **timestamp** | `string` | optional | | diff --git a/content/docs/references/api/analytics.mdx b/content/docs/references/api/analytics.mdx index 3101ae43a2..953b420255 100644 --- a/content/docs/references/api/analytics.mdx +++ b/content/docs/references/api/analytics.mdx @@ -45,9 +45,9 @@ const result = AnalyticsEndpoint.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ cubes: { name: string; title?: string; description?: string; sql: string; … }[] }` | ✅ | | --- @@ -58,7 +58,7 @@ const result = AnalyticsEndpoint.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **query** | `Object` | ✅ | The analytic query definition | +| **query** | `{ cube?: string; measures: string[]; dimensions?: string[]; where?: any; … }` | ✅ | The analytic query definition | | **cube** | `string` | ✅ | Target cube name | | **format** | `Enum<'json' \| 'csv' \| 'xlsx'>` | ✅ | Response format | @@ -72,9 +72,9 @@ const result = AnalyticsEndpoint.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ rows: Record[]; fields: { name: string; type: string }[]; sql?: string }` | ✅ | | --- @@ -86,9 +86,9 @@ const result = AnalyticsEndpoint.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ sql: string; params: any[] }` | ✅ | | --- diff --git a/content/docs/references/api/auth-endpoints.mdx b/content/docs/references/api/auth-endpoints.mdx index 128e5e54c8..f0cf415138 100644 --- a/content/docs/references/api/auth-endpoints.mdx +++ b/content/docs/references/api/auth-endpoints.mdx @@ -39,14 +39,14 @@ const result = AuthEndpoint.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **signInEmail** | `Object` | ✅ | | -| **signUpEmail** | `Object` | ✅ | | -| **signOut** | `Object` | ✅ | | -| **getSession** | `Object` | ✅ | | -| **forgetPassword** | `Object` | ✅ | | -| **resetPassword** | `Object` | ✅ | | -| **sendVerificationEmail** | `Object` | ✅ | | -| **verifyEmail** | `Object` | ✅ | | +| **signInEmail** | `{ method: 'POST'; path: '/sign-in/email'; description: 'Sign in with email and password' }` | ✅ | | +| **signUpEmail** | `{ method: 'POST'; path: '/sign-up/email'; description: 'Register new user with email and password' }` | ✅ | | +| **signOut** | `{ method: 'POST'; path: '/sign-out'; description: 'Sign out current user' }` | ✅ | | +| **getSession** | `{ method: 'GET'; path: '/get-session'; description: 'Get current user session' }` | ✅ | | +| **forgetPassword** | `{ method: 'POST'; path: '/forget-password'; description: 'Request password reset email' }` | ✅ | | +| **resetPassword** | `{ method: 'POST'; path: '/reset-password'; description: 'Reset password with token' }` | ✅ | | +| **sendVerificationEmail** | `{ method: 'POST'; path: '/send-verification-email'; description: 'Send email verification link' }` | ✅ | | +| **verifyEmail** | `{ method: 'GET'; path: '/verify-email'; description: 'Verify email with token' }` | ✅ | | --- @@ -108,7 +108,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **status** | `string` | ✅ | | +| **status** | `'pending'` | ✅ | | --- @@ -118,9 +118,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **status** | `string` | ✅ | | +| **status** | `'approved'` | ✅ | | | **token** | `string` | ✅ | Bearer token to store in credentials file | -| **user** | `Object` | ✅ | | +| **user** | `{ id: string; email: string; name?: string }` | ✅ | | --- @@ -130,7 +130,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **status** | `string` | ✅ | | +| **status** | `'expired'` | ✅ | | --- @@ -156,9 +156,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **emailPassword** | `Object` | ✅ | Email/password authentication config | -| **socialProviders** | `Object[]` | ✅ | Available social/OAuth providers | -| **features** | `Object` | ✅ | Enabled authentication features | +| **emailPassword** | `{ enabled: boolean; disableSignUp?: boolean; requireEmailVerification?: boolean }` | ✅ | Email/password authentication config | +| **socialProviders** | `{ id: string; name: string; enabled: boolean; type: Enum<'social' \| 'oidc'> }[]` | ✅ | Available social/OAuth providers | +| **features** | `{ twoFactor: boolean; passkeys: boolean; magicLink: boolean; organization: boolean; … }` | ✅ | Enabled authentication features | --- diff --git a/content/docs/references/api/auth.mdx b/content/docs/references/api/auth.mdx index e24aca6ef3..c696cfde93 100644 --- a/content/docs/references/api/auth.mdx +++ b/content/docs/references/api/auth.mdx @@ -102,9 +102,9 @@ const result = AuthProvider.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ session: object; user: object; token?: string }` | ✅ | | --- @@ -138,9 +138,9 @@ const result = AuthProvider.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id: string; email: string; emailVerified: boolean; name: string; … }` | ✅ | | --- diff --git a/content/docs/references/api/automation-api.mdx b/content/docs/references/api/automation-api.mdx index 2d5a8831a7..ed61337cea 100644 --- a/content/docs/references/api/automation-api.mdx +++ b/content/docs/references/api/automation-api.mdx @@ -104,13 +104,13 @@ const result = AutomationApiErrorCode.parse(data); | **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 | +| **variables** | `{ name: string; type: string; isInput?: boolean; isOutput?: boolean }[]` | optional | Flow variables | +| **nodes** | `{ id: string; type: string; label: string; config?: Record; … }[]` | ✅ | Flow nodes | +| **edges** | `{ id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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. | +| **errorHandling** | `{ strategy?: Enum<'fail' \| 'retry' \| 'continue'>; maxRetries?: integer; retryDelayMs?: integer; backoffMultiplier?: number; … }` | optional | Flow-level error handling configuration | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -129,9 +129,9 @@ const result = AutomationApiErrorCode.parse(data); | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | The created flow definition | --- @@ -154,9 +154,9 @@ const result = AutomationApiErrorCode.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; deleted: boolean }` | ✅ | | --- @@ -197,9 +197,9 @@ const result = AutomationApiErrorCode.parse(data); | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | Full flow definition | --- @@ -223,9 +223,9 @@ const result = AutomationApiErrorCode.parse(data); | 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 execution log with step details | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id: string; flowName: string; flowVersion?: integer; status: Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>; … }` | ✅ | Full execution log with step details | --- @@ -251,9 +251,9 @@ const result = AutomationApiErrorCode.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ flows: { name: string; label: string; type: string; status: string; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -279,9 +279,9 @@ const result = AutomationApiErrorCode.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ runs: { id: string; flowName: string; flowVersion?: integer; status: Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -305,9 +305,9 @@ const result = AutomationApiErrorCode.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; enabled: boolean }` | ✅ | | --- @@ -335,9 +335,9 @@ const result = AutomationApiErrorCode.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ success: boolean; output?: any; error?: string; durationMs?: number }` | ✅ | | --- @@ -349,7 +349,7 @@ const result = AutomationApiErrorCode.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Flow machine name (snake_case) | -| **definition** | `Object` | ✅ | Partial flow definition to update | +| **definition** | `{ name?: string; label?: string; description?: string; successMessage?: string; … }` | ✅ | Partial flow definition to update | --- @@ -361,9 +361,9 @@ const result = AutomationApiErrorCode.parse(data); | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | The updated flow definition | --- diff --git a/content/docs/references/api/batch.mdx b/content/docs/references/api/batch.mdx index 1bf7c47e20..63d64f1558 100644 --- a/content/docs/references/api/batch.mdx +++ b/content/docs/references/api/batch.mdx @@ -47,7 +47,7 @@ const result = BatchConfig.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable batch operations | | **maxRecordsPerBatch** | `integer` | ✅ | Maximum records per batch | -| **defaultOptions** | `Object` | optional | Default batch options | +| **defaultOptions** | `{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }` | optional | Default batch options | --- @@ -60,7 +60,7 @@ const result = BatchConfig.parse(data); | :--- | :--- | :--- | :--- | | **id** | `string` | optional | Record ID if operation succeeded | | **success** | `boolean` | ✅ | Whether this record was processed successfully | -| **errors** | `Object[]` | optional | Array of errors if operation failed | +| **errors** | `{ code: string; message: string; category?: string; details?: any; … }[]` | optional | Array of errors if operation failed | | **data** | `Record` | optional | Full record data (if returnRecords=true) | | **index** | `number` | optional | Index of the record in the request array | @@ -113,8 +113,8 @@ const result = BatchConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | ✅ | Type of batch operation | -| **records** | `Object[]` | ✅ | Array of records to process (max 200 per batch) | -| **options** | `Object` | optional | Batch operation options | +| **records** | `{ id?: string; data?: Record; externalId?: string }[]` | ✅ | Array of records to process (max 200 per batch) | +| **options** | `{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }` | optional | Batch operation options | --- @@ -126,13 +126,13 @@ const result = BatchConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | optional | Operation type that was performed | | **total** | `number` | ✅ | Total number of records in the batch | | **succeeded** | `number` | ✅ | Number of records that succeeded | | **failed** | `number` | ✅ | Number of records that failed | -| **results** | `Object[]` | ✅ | Detailed results for each record | +| **results** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record; … }[]` | ✅ | Detailed results for each record | --- @@ -144,7 +144,7 @@ const result = BatchConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **ids** | `string[]` | ✅ | Array of record IDs to delete (max 200) | -| **options** | `Object` | optional | Delete options | +| **options** | `{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }` | optional | Delete options | --- @@ -155,8 +155,8 @@ const result = BatchConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **records** | `Object[]` | ✅ | Array of records to update (max 200 per batch) | -| **options** | `Object` | optional | Update options | +| **records** | `{ id?: string; data?: Record; externalId?: string }[]` | ✅ | Array of records to update (max 200 per batch) | +| **options** | `{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }` | optional | Update options | --- diff --git a/content/docs/references/api/connector.mdx b/content/docs/references/api/connector.mdx index 990bc65596..cae87b4a81 100644 --- a/content/docs/references/api/connector.mdx +++ b/content/docs/references/api/connector.mdx @@ -57,8 +57,8 @@ const result = ErrorCategory.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable webhook support | -| **events** | `Object[]` | ✅ | Registered webhook events | -| **deliveryConfig** | `Object` | ✅ | Webhook delivery configuration | +| **events** | `{ name: string; description: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>; payloadSchema: string; … }[]` | ✅ | Registered webhook events | +| **deliveryConfig** | `{ maxRetries: integer; retryIntervalMs: integer; timeoutMs: integer; signatureHeader: string }` | ✅ | Webhook delivery configuration | | **registrationEndpoint** | `string` | ✅ | URL path for webhook registration | diff --git a/content/docs/references/api/contract.mdx b/content/docs/references/api/contract.mdx index f36baedb1b..a42cce44c9 100644 --- a/content/docs/references/api/contract.mdx +++ b/content/docs/references/api/contract.mdx @@ -45,8 +45,8 @@ const result = ApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | --- @@ -84,9 +84,9 @@ const result = ApiError.parse(data); | 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[]` | ✅ | Results for each item in the batch | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; index?: number; … }[]` | ✅ | Results for each item in the batch | --- @@ -126,8 +126,8 @@ const result = ApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **id** | `string` | ✅ | ID of the deleted record | @@ -140,21 +140,21 @@ const result = ApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name (e.g. account) | -| **fields** | `[__schema1](./__schema1)[]` | optional | Fields to retrieve | -| **where** | `[__schema2](./__schema2)` | optional | Filtering criteria (WHERE) | -| **search** | `Object` | optional | Full-text search configuration ($search parameter) | -| **orderBy** | `Object[]` | optional | Sorting instructions (ORDER BY) | +| **fields** | `string \| { field: string; fields?: object[]; alias?: string }[]` | optional | Fields to retrieve | +| **where** | `any` | optional | Filtering criteria (WHERE) | +| **search** | `{ query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | Full-text search configuration ($search parameter) | +| **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sorting instructions (ORDER BY) | | **limit** | `number` | optional | Max records to return (LIMIT) | | **offset** | `number` | optional | Records to skip (OFFSET) | | **top** | `number` | optional | Alias for limit (OData compatibility) | | **cursor** | `Record` | optional | Cursor for keyset pagination | -| **joins** | `Object[]` | optional | Explicit Table Joins | -| **aggregations** | `Object[]` | optional | Aggregation functions | -| **groupBy** | `string \| Object[]` | optional | GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing) | -| **having** | `[__schema2](./__schema2)` | optional | HAVING clause for aggregation filtering | -| **windowFunctions** | `Object[]` | optional | Window functions with OVER clause | +| **joins** | `{ type: Enum<'inner' \| 'left' \| 'right' \| 'full'>; strategy?: Enum<'auto' \| 'database' \| 'hash' \| 'loop'>; object: string; alias?: string; … }[]` | optional | Explicit Table Joins | +| **aggregations** | `{ function: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; alias: string; distinct?: boolean; … }[]` | optional | Aggregation functions | +| **groupBy** | `string \| { field: string; dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; alias?: string }[]` | optional | GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing) | +| **having** | `any` | optional | HAVING clause for aggregation filtering | +| **windowFunctions** | `{ function: Enum<'row_number' \| 'rank' \| 'dense_rank' \| 'percent_rank' \| 'lag' \| 'lead' \| 'first_value' \| 'last_value' \| 'sum' \| 'avg' \| 'count' \| 'min' \| 'max'>; field?: string; alias: string; over: object }[]` | optional | Window functions with OVER clause | | **distinct** | `boolean` | optional | SELECT DISTINCT flag | -| **expand** | `Record` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (`fields`) and filter (`where`, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent `limit`/`offset`/`orderBy` are NOT applied on this path. | +| **expand** | `Record` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (`fields`) and filter (`where`, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent `limit`/`offset`/`orderBy` are NOT applied on this path. | --- @@ -177,10 +177,10 @@ const result = ApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `Record[]` | ✅ | Array of matching records | -| **pagination** | `Object` | ✅ | Pagination info | +| **pagination** | `{ total?: number; limit?: number; offset?: number; cursor?: string; … }` | ✅ | Pagination info | --- @@ -193,7 +193,7 @@ const result = ApiError.parse(data); | :--- | :--- | :--- | :--- | | **id** | `string` | optional | Record ID if processed | | **success** | `boolean` | ✅ | | -| **errors** | `Object[]` | optional | | +| **errors** | `{ code: string; message: string; category?: string; details?: any; … }[]` | optional | | | **index** | `number` | optional | Index in original request | | **data** | `any` | optional | Result data (e.g. created record) | @@ -207,8 +207,8 @@ const result = ApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **preventNPlusOne** | `boolean` | ✅ | Enable N+1 query detection and prevention | -| **dataLoader** | `Object` | optional | DataLoader batch loading configuration | -| **batchStrategy** | `Object` | optional | Batch loading strategy configuration | +| **dataLoader** | `{ maxBatchSize: integer; batchScheduleFn: Enum<'microtask' \| 'timeout' \| 'manual'>; cacheEnabled: boolean; cacheKeyFn?: string; … }` | optional | DataLoader batch loading configuration | +| **batchStrategy** | `{ strategy: Enum<'dataloader' \| 'windowed' \| 'prefetch'>; windowMs?: number; prefetchDepth?: integer; associationLoading: Enum<'lazy' \| 'eager' \| 'batch'> }` | optional | Batch loading strategy configuration | | **maxQueryDepth** | `integer` | ✅ | Maximum depth for nested relation queries | | **queryComplexityLimit** | `number` | optional | Maximum allowed query complexity score | | **enableQueryPlan** | `boolean` | ✅ | Log query execution plans for debugging | @@ -226,8 +226,8 @@ const result = ApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `Record` | ✅ | The requested or modified record | diff --git a/content/docs/references/api/discovery.mdx b/content/docs/references/api/discovery.mdx index df8d601ab1..90b7625edc 100644 --- a/content/docs/references/api/discovery.mdx +++ b/content/docs/references/api/discovery.mdx @@ -73,11 +73,11 @@ const result = ApiRoutes.parse(data); | **name** | `string` | ✅ | | | **version** | `string` | ✅ | | | **environment** | `Enum<'production' \| 'sandbox' \| 'development'>` | ✅ | | -| **routes** | `Object` | ✅ | | -| **locale** | `Object` | ✅ | | -| **services** | `Record` | ✅ | Per-service availability map keyed by CoreServiceName | -| **capabilities** | `Record` | optional | Hierarchical capability descriptors for frontend intelligent adaptation | -| **schemaDiscovery** | `Object` | optional | Schema discovery endpoints for API toolchain integration | +| **routes** | `{ data: string; metadata: string; discovery?: string; ui?: string; … }` | ✅ | | +| **locale** | `{ default: string; supported: string[]; timezone: string }` | ✅ | | +| **services** | `Record; handlerReady?: boolean; route?: string; … }>` | ✅ | Per-service availability map keyed by CoreServiceName | +| **capabilities** | `Record; description?: string }>` | optional | Hierarchical capability descriptors for frontend intelligent adaptation | +| **schemaDiscovery** | `{ openapi?: string; graphql?: string; jsonSchema?: string }` | optional | Schema discovery endpoints for API toolchain integration | | **metadata** | `Record` | optional | Custom metadata key-value pairs for extensibility | @@ -111,7 +111,7 @@ const result = ApiRoutes.parse(data); | **totalDeclared** | `integer` | ✅ | Total routes declared in discovery | | **totalRegistered** | `integer` | ✅ | Routes with confirmed handler | | **totalMissing** | `integer` | ✅ | Routes missing a handler | -| **routes** | `Object[]` | ✅ | Per-route health entries | +| **routes** | `{ route: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>; service: string; declared: boolean; … }[]` | ✅ | Per-route health entries | --- @@ -129,7 +129,7 @@ const result = ApiRoutes.parse(data); | **provider** | `string` | optional | e.g. "objectql", "plugin-redis", "driver-memory" | | **version** | `string` | optional | Semantic version of the service implementation (e.g. "3.0.6") | | **message** | `string` | optional | e.g. "Install plugin-workflow to enable" | -| **rateLimit** | `Object` | optional | Rate limit and quota info for this service | +| **rateLimit** | `{ requestsPerMinute?: integer; requestsPerHour?: integer; burstLimit?: integer; retryAfterMs?: integer }` | optional | Rate limit and quota info for this service | --- diff --git a/content/docs/references/api/dispatcher.mdx b/content/docs/references/api/dispatcher.mdx index 83a039512c..37daae854c 100644 --- a/content/docs/references/api/dispatcher.mdx +++ b/content/docs/references/api/dispatcher.mdx @@ -51,7 +51,7 @@ const result = DispatcherConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **routes** | `Object[]` | ✅ | Route-to-service mappings | +| **routes** | `{ prefix: string; service: Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'graphql' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui' \| 'workflow'>; authRequired: boolean; criticality: Enum<'required' \| 'core' \| 'optional'>; … }[]` | ✅ | Route-to-service mappings | | **fallback** | `Enum<'404' \| 'proxy' \| 'custom'>` | ✅ | Behavior when no route matches | | **proxyTarget** | `string` | optional | Proxy target URL when fallback is "proxy" | @@ -78,8 +78,8 @@ const result = DispatcherConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | | -| **error** | `Object` | ✅ | | +| **success** | `'false'` | ✅ | | +| **error** | `{ code: integer; message: string; type?: Enum<'ROUTE_NOT_FOUND' \| 'METHOD_NOT_ALLOWED' \| 'NOT_IMPLEMENTED' \| 'SERVICE_UNAVAILABLE'>; route?: string; … }` | ✅ | | --- diff --git a/content/docs/references/api/documentation.mdx b/content/docs/references/api/documentation.mdx index 1e8fbe7b75..ca2f8c254d 100644 --- a/content/docs/references/api/documentation.mdx +++ b/content/docs/references/api/documentation.mdx @@ -85,7 +85,7 @@ const result = ApiChangelogEntry.parse(data); | :--- | :--- | :--- | :--- | | **version** | `string` | ✅ | API version | | **date** | `string` | ✅ | Release date | -| **changes** | `Object` | ✅ | Version changes | +| **changes** | `{ added: string[]; changed: string[]; deprecated: string[]; removed: string[]; … }` | ✅ | Version changes | | **migrationGuide** | `string` | optional | Migration guide URL or text | @@ -101,19 +101,19 @@ const result = ApiChangelogEntry.parse(data); | **title** | `string` | ✅ | Documentation title | | **version** | `string` | ✅ | API version | | **description** | `string` | optional | API description | -| **servers** | `Object[]` | ✅ | API server URLs | -| **ui** | `Object` | optional | Testing UI configuration | +| **servers** | `{ url: string; description?: string; variables?: Record }[]` | ✅ | API server URLs | +| **ui** | `{ type: Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphql-playground' \| 'graphiql' \| 'postman' \| 'custom'>; path: string; theme: Enum<'light' \| 'dark' \| 'auto'>; enableTryItOut: boolean; … }` | optional | Testing UI configuration | | **generateOpenApi** | `boolean` | ✅ | Generate OpenAPI 3.0 specification | | **generateTestCollections** | `boolean` | ✅ | Generate API test collections | -| **testCollections** | `Object[]` | ✅ | Predefined test collections | -| **changelog** | `Object[]` | ✅ | API version changelog | -| **codeTemplates** | `Object[]` | ✅ | Code generation templates | +| **testCollections** | `{ name: string; description?: string; variables: Record; requests: { name: string; description?: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>; url: string; … }[]; … }[]` | ✅ | Predefined test collections | +| **changelog** | `{ version: string; date: string; changes: object; migrationGuide?: string }[]` | ✅ | API version changelog | +| **codeTemplates** | `{ language: string; name: string; template: string; variables?: string[] }[]` | ✅ | Code generation templates | | **termsOfService** | `string` | optional | Terms of service URL | -| **contact** | `Object` | optional | Contact information | -| **license** | `Object` | optional | API license | -| **externalDocs** | `Object` | optional | External documentation link | -| **securitySchemes** | `Record` | optional | Security scheme definitions | -| **tags** | `Object[]` | optional | Global tag definitions | +| **contact** | `{ name?: string; url?: string; email?: string }` | optional | Contact information | +| **license** | `{ name: string; url?: string }` | optional | API license | +| **externalDocs** | `{ description?: string; url: string }` | optional | External documentation link | +| **securitySchemes** | `Record; scheme?: string; bearerFormat?: string; name?: string; … }>` | optional | Security scheme definitions | +| **tags** | `{ name: string; description?: string; externalDocs?: object }[]` | optional | Global tag definitions | --- @@ -127,8 +127,8 @@ const result = ApiChangelogEntry.parse(data); | **name** | `string` | ✅ | Collection name | | **description** | `string` | optional | Collection description | | **variables** | `Record` | ✅ | Shared variables | -| **requests** | `Object[]` | ✅ | Test requests in this collection | -| **folders** | `Object[]` | optional | Request folders for organization | +| **requests** | `{ name: string; description?: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>; url: string; … }[]` | ✅ | Test requests in this collection | +| **folders** | `{ name: string; description?: string; requests: { name: string; description?: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>; url: string; … }[] }[]` | optional | Request folders for organization | --- @@ -147,7 +147,7 @@ const result = ApiChangelogEntry.parse(data); | **queryParams** | `Record` | ✅ | Query parameters | | **body** | `any` | optional | Request body | | **variables** | `Record` | ✅ | Template variables | -| **expectedResponse** | `Object` | optional | Expected response for validation | +| **expectedResponse** | `{ statusCode: integer; body?: any }` | optional | Expected response for validation | --- @@ -169,7 +169,7 @@ const result = ApiChangelogEntry.parse(data); | **syntaxHighlighting** | `boolean` | ✅ | Enable syntax highlighting | | **customCssUrl** | `string` | optional | Custom CSS stylesheet URL | | **customJsUrl** | `string` | optional | Custom JavaScript URL | -| **layout** | `Object` | optional | Layout configuration | +| **layout** | `{ showExtensions: boolean; showCommonExtensions: boolean; deepLinking: boolean; displayOperationId: boolean; … }` | optional | Layout configuration | --- @@ -211,8 +211,8 @@ const result = ApiChangelogEntry.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **openApiSpec** | `Object` | optional | Generated OpenAPI specification | -| **testCollections** | `Object[]` | optional | Generated test collections | +| **openApiSpec** | `{ openapi: string; info: object; servers: { url: string; description?: string; variables?: Record }[]; paths: Record; … }` | optional | Generated OpenAPI specification | +| **testCollections** | `{ name: string; description?: string; variables: Record; requests: { name: string; description?: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>; url: string; … }[]; … }[]` | optional | Generated test collections | | **markdown** | `string` | optional | Generated markdown documentation | | **html** | `string` | optional | Generated HTML documentation | | **generatedAt** | `string` | ✅ | Generation timestamp | @@ -232,7 +232,7 @@ const result = ApiChangelogEntry.parse(data); | **bearerFormat** | `string` | optional | Bearer token format (e.g., JWT) | | **name** | `string` | optional | API key parameter name | | **in** | `Enum<'header' \| 'query' \| 'cookie'>` | optional | API key location | -| **flows** | `Object` | optional | OAuth2 flows | +| **flows** | `{ implicit?: any; password?: any; clientCredentials?: any; authorizationCode?: any }` | optional | OAuth2 flows | | **openIdConnectUrl** | `string` | optional | OpenID Connect discovery URL | | **description** | `string` | optional | Security scheme description | @@ -247,7 +247,7 @@ const result = ApiChangelogEntry.parse(data); | :--- | :--- | :--- | :--- | | **url** | `string` | ✅ | Server base URL | | **description** | `string` | optional | Server description | -| **variables** | `Record` | optional | URL template variables | +| **variables** | `Record` | optional | URL template variables | --- @@ -259,13 +259,13 @@ const result = ApiChangelogEntry.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **openapi** | `string` | ✅ | OpenAPI specification version | -| **info** | `Object` | ✅ | API metadata | -| **servers** | `Object[]` | ✅ | API servers | +| **info** | `{ title: string; version: string; description?: string; termsOfService?: string; … }` | ✅ | API metadata | +| **servers** | `{ url: string; description?: string; variables?: Record }[]` | ✅ | API servers | | **paths** | `Record` | ✅ | API paths and operations | -| **components** | `Object` | optional | Reusable components | +| **components** | `{ schemas?: Record; responses?: Record; parameters?: Record; examples?: Record; … }` | optional | Reusable components | | **security** | `Record[]` | optional | Global security requirements | -| **tags** | `Object[]` | optional | Tag definitions | -| **externalDocs** | `Object` | optional | External documentation | +| **tags** | `{ name: string; description?: string; externalDocs?: object }[]` | optional | Tag definitions | +| **externalDocs** | `{ description?: string; url: string }` | optional | External documentation | --- diff --git a/content/docs/references/api/endpoint.mdx b/content/docs/references/api/endpoint.mdx index 128e13ecd9..ce113be770 100644 --- a/content/docs/references/api/endpoint.mdx +++ b/content/docs/references/api/endpoint.mdx @@ -38,11 +38,11 @@ const result = ApiEndpoint.parse(data); | **description** | `string` | optional | | | **type** | `Enum<'flow' \| 'script' \| 'object_operation' \| 'proxy'>` | ✅ | Implementation type | | **target** | `string` | ✅ | Target Flow ID, Script Name, or Proxy URL | -| **objectParams** | `Object` | optional | For object_operation type | -| **inputMapping** | `Object[]` | optional | Map Request Body to Internal Params | -| **outputMapping** | `Object[]` | optional | Map Internal Result to Response Body | +| **objectParams** | `{ object?: string; operation?: Enum<'find' \| 'get' \| 'create' \| 'update' \| 'delete'> }` | optional | For object_operation type | +| **inputMapping** | `{ source: string; target: string; transform?: string }[]` | optional | Map Request Body to Internal Params | +| **outputMapping** | `{ source: string; target: string; transform?: string }[]` | optional | Map Internal Result to Response Body | | **authRequired** | `boolean` | ✅ | Require authentication | -| **rateLimit** | `Object` | optional | Rate limiting policy | +| **rateLimit** | `{ enabled: boolean; windowMs: integer; maxRequests: integer }` | optional | Rate limiting policy | | **cacheTtl** | `number` | optional | Response cache TTL in seconds | diff --git a/content/docs/references/api/errors.mdx b/content/docs/references/api/errors.mdx index eafb2dd374..a17adfc945 100644 --- a/content/docs/references/api/errors.mdx +++ b/content/docs/references/api/errors.mdx @@ -53,7 +53,7 @@ const result = EnhancedApiError.parse(data); | **retryStrategy** | `Enum<'no_retry' \| 'retry_immediate' \| 'retry_backoff' \| 'retry_after'>` | optional | Recommended retry strategy | | **retryAfter** | `number` | optional | Seconds to wait before retrying | | **details** | `any` | optional | Additional error context | -| **fieldErrors** | `Object[]` | optional | Field-specific validation errors | +| **fieldErrors** | `{ field: string; code: Enum<'validation_error' \| 'invalid_field' \| 'missing_required_field' \| 'invalid_format' \| 'value_too_long' \| 'value_too_short' \| 'value_out_of_range' \| 'invalid_reference' \| 'duplicate_value' \| 'invalid_query' \| 'invalid_filter' \| 'invalid_sort' \| 'max_records_exceeded' \| 'unauthenticated' \| 'invalid_credentials' \| 'expired_token' \| 'invalid_token' \| 'session_expired' \| 'mfa_required' \| 'email_not_verified' \| 'permission_denied' \| 'insufficient_privileges' \| 'field_not_accessible' \| 'record_not_accessible' \| 'license_required' \| 'ip_restricted' \| 'time_restricted' \| 'resource_not_found' \| 'object_not_found' \| 'record_not_found' \| 'field_not_found' \| 'endpoint_not_found' \| 'resource_conflict' \| 'concurrent_modification' \| 'delete_restricted' \| 'duplicate_record' \| 'lock_conflict' \| 'rate_limit_exceeded' \| 'quota_exceeded' \| 'concurrent_limit_exceeded' \| 'internal_error' \| 'database_error' \| 'timeout' \| 'service_unavailable' \| 'not_implemented' \| 'external_service_error' \| 'integration_error' \| 'webhook_delivery_failed' \| 'batch_partial_failure' \| 'batch_complete_failure' \| 'transaction_failed'>; message: string; value?: any; … }[]` | optional | Field-specific validation errors | | **timestamp** | `string` | optional | When the error occurred | | **requestId** | `string` | optional | Request ID for tracking | | **traceId** | `string` | optional | Distributed trace ID | @@ -69,9 +69,9 @@ const result = EnhancedApiError.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Always false for error responses | -| **error** | `Object` | ✅ | Error details | -| **meta** | `Object` | optional | Response metadata | +| **success** | `'false'` | ✅ | Always false for error responses | +| **error** | `{ code: Enum<'validation_error' \| 'invalid_field' \| 'missing_required_field' \| 'invalid_format' \| 'value_too_long' \| 'value_too_short' \| 'value_out_of_range' \| 'invalid_reference' \| 'duplicate_value' \| 'invalid_query' \| 'invalid_filter' \| 'invalid_sort' \| 'max_records_exceeded' \| 'unauthenticated' \| 'invalid_credentials' \| 'expired_token' \| 'invalid_token' \| 'session_expired' \| 'mfa_required' \| 'email_not_verified' \| 'permission_denied' \| 'insufficient_privileges' \| 'field_not_accessible' \| 'record_not_accessible' \| 'license_required' \| 'ip_restricted' \| 'time_restricted' \| 'resource_not_found' \| 'object_not_found' \| 'record_not_found' \| 'field_not_found' \| 'endpoint_not_found' \| 'resource_conflict' \| 'concurrent_modification' \| 'delete_restricted' \| 'duplicate_record' \| 'lock_conflict' \| 'rate_limit_exceeded' \| 'quota_exceeded' \| 'concurrent_limit_exceeded' \| 'internal_error' \| 'database_error' \| 'timeout' \| 'service_unavailable' \| 'not_implemented' \| 'external_service_error' \| 'integration_error' \| 'webhook_delivery_failed' \| 'batch_partial_failure' \| 'batch_complete_failure' \| 'transaction_failed'>; message: string; category?: Enum<'validation' \| 'authentication' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'server' \| 'external' \| 'maintenance'>; httpStatus?: number; … }` | ✅ | Error details | +| **meta** | `{ timestamp?: string; requestId?: string; traceId?: string }` | optional | Response metadata | --- diff --git a/content/docs/references/api/export.mdx b/content/docs/references/api/export.mdx index aa976a0997..3643d80c35 100644 --- a/content/docs/references/api/export.mdx +++ b/content/docs/references/api/export.mdx @@ -43,7 +43,7 @@ const result = CreateExportJobRequest.parse(data); | **format** | `Enum<'csv' \| 'json' \| 'jsonl' \| 'xlsx' \| 'parquet'>` | ✅ | Export file format | | **fields** | `string[]` | optional | Specific fields to include (omit for all fields) | | **filter** | `Record` | optional | Filter criteria for records to export | -| **sort** | `Object[]` | optional | Sort order for exported records | +| **sort** | `{ field: string; direction: Enum<'asc' \| 'desc'> }[]` | optional | Sort order for exported records | | **limit** | `integer` | optional | Maximum number of records to export | | **includeHeaders** | `boolean` | ✅ | Include header row (CSV/XLSX) | | **encoding** | `string` | ✅ | Character encoding for the export file | @@ -59,9 +59,9 @@ const result = CreateExportJobRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ jobId: string; status: Enum<'pending' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'expired'>; estimatedRecords?: integer; createdAt: string }` | ✅ | | --- @@ -77,7 +77,7 @@ const result = CreateExportJobRequest.parse(data); | **rows** | `Record[]` | optional | Row objects (when format = json) | | **xlsxBase64** | `string` | optional | Base64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side | | **sheet** | `string \| integer` | optional | Worksheet name or 1-based index to read (xlsx; defaults to the first sheet) | -| **mapping** | `Record \| Object[]` | optional | Source column → target field mapping | +| **mapping** | `Record \| { sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' \| 'uppercase' \| 'lowercase' \| 'trim' \| 'date_format' \| 'lookup'>; … }[]` | optional | Source column → target field mapping | | **dryRun** | `boolean` | ✅ | Validate + coerce every row without persisting | | **writeMode** | `Enum<'insert' \| 'update' \| 'upsert'>` | ✅ | insert / update / upsert semantics | | **matchFields** | `string[]` | optional | Fields that identify an existing record (required for update/upsert) | @@ -143,7 +143,7 @@ const result = CreateExportJobRequest.parse(data); | **object** | `string` | ✅ | Target object name | | **direction** | `Enum<'import' \| 'export' \| 'bidirectional'>` | ✅ | Template direction | | **format** | `Enum<'csv' \| 'json' \| 'jsonl' \| 'xlsx' \| 'parquet'>` | optional | Default file format for this template | -| **mappings** | `Object[]` | ✅ | Field mapping entries | +| **mappings** | `{ sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' \| 'uppercase' \| 'lowercase' \| 'trim' \| 'date_format' \| 'lookup'>; … }[]` | ✅ | Field mapping entries | | **createdAt** | `string` | optional | Template creation timestamp | | **updatedAt** | `string` | optional | Last update timestamp | | **createdBy** | `string` | optional | User who created the template | @@ -158,9 +158,9 @@ const result = CreateExportJobRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ jobId: string; status: Enum<'pending' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'expired'>; format: Enum<'csv' \| 'json' \| 'jsonl' \| 'xlsx' \| 'parquet'>; totalRecords?: integer; … }` | ✅ | | --- @@ -232,9 +232,9 @@ const result = CreateExportJobRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ jobId: string; downloadUrl: string; fileName: string; fileSize: integer; … }` | ✅ | | --- @@ -291,7 +291,7 @@ const result = CreateExportJobRequest.parse(data); | **startedAt** | `string` | optional | Processing start timestamp (ISO 8601) | | **completedAt** | `string` | optional | Completion timestamp (ISO 8601) | | **createdAt** | `string` | ✅ | Job creation timestamp (ISO 8601) | -| **results** | `Object[]` | ✅ | Capped sample of per-row outcomes (failures first) | +| **results** | `{ row: integer; ok: boolean; action: Enum<'created' \| 'updated' \| 'skipped' \| 'failed'>; id?: string; … }[]` | ✅ | Capped sample of per-row outcomes (failures first) | | **resultsTruncated** | `boolean` | ✅ | Whether `results` is a capped sample of a larger set | @@ -347,7 +347,7 @@ Type: `Record` #### Option 2 -Type: `Object[]` +Type: `{ sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[]` --- @@ -365,7 +365,7 @@ Type: `Object[]` | **rows** | `Record[]` | optional | Row objects (when format = json) | | **xlsxBase64** | `string` | optional | Base64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side | | **sheet** | `string \| integer` | optional | Worksheet name or 1-based index to read (xlsx; defaults to the first sheet) | -| **mapping** | `Record \| Object[]` | optional | Source column → target field mapping | +| **mapping** | `Record \| { sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' \| 'uppercase' \| 'lowercase' \| 'trim' \| 'date_format' \| 'lookup'>; … }[]` | optional | Source column → target field mapping | | **dryRun** | `boolean` | ✅ | Validate + coerce every row without persisting | | **writeMode** | `Enum<'insert' \| 'update' \| 'upsert'>` | ✅ | insert / update / upsert semantics | | **matchFields** | `string[]` | optional | Fields that identify an existing record (required for update/upsert) | @@ -393,7 +393,7 @@ Type: `Object[]` | **created** | `integer` | ✅ | Rows that created a new record | | **updated** | `integer` | ✅ | Rows that updated an existing record | | **skipped** | `integer` | ✅ | Rows skipped (no match in update mode, etc.) | -| **results** | `Object[]` | ✅ | Per-row outcomes | +| **results** | `{ row: integer; ok: boolean; action: Enum<'created' \| 'updated' \| 'skipped' \| 'failed'>; id?: string; … }[]` | ✅ | Per-row outcomes | --- @@ -422,7 +422,7 @@ Type: `Object[]` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **mode** | `Enum<'strict' \| 'lenient' \| 'dry_run'>` | ✅ | Validation mode for the import | -| **deduplication** | `Object` | optional | Deduplication configuration | +| **deduplication** | `{ strategy: Enum<'skip' \| 'update' \| 'create_new' \| 'fail'>; matchFields: string[] }` | optional | Deduplication configuration | | **maxErrors** | `integer` | ✅ | Maximum validation errors before aborting | | **trimWhitespace** | `boolean` | ✅ | Trim leading/trailing whitespace from string fields | | **dateFormat** | `string` | optional | Expected date format in import data (e.g., "YYYY-MM-DD") | @@ -449,9 +449,9 @@ Type: `Object[]` | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ totalRecords: integer; validRecords: integer; invalidRecords: integer; duplicateRecords: integer; … }` | ✅ | | --- @@ -488,9 +488,9 @@ Type: `Object[]` | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ jobs: { jobId: string; object: string; status: Enum<'pending' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'expired'>; format: Enum<'csv' \| 'json' \| 'jsonl' \| 'xlsx' \| 'parquet'>; … }[]; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -515,7 +515,7 @@ Type: `Object[]` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **jobs** | `Object[]` | ✅ | Import jobs, newest first | +| **jobs** | `{ jobId: string; object: string; status: Enum<'pending' \| 'running' \| 'succeeded' \| 'failed' \| 'cancelled'>; total: integer; … }[]` | ✅ | Import jobs, newest first | --- @@ -533,8 +533,8 @@ Type: `Object[]` | **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 | +| **schedule** | `{ cronExpression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; timezone?: string }` | ✅ | Schedule timing configuration | +| **delivery** | `{ method: Enum<'email' \| 'storage' \| 'webhook'>; recipients?: string[]; storagePath?: string; webhookUrl?: string }` | ✅ | Export delivery configuration | --- @@ -546,9 +546,9 @@ Type: `Object[]` | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id: string; name: string; enabled: boolean; nextRunAt?: string; … }` | ✅ | | --- @@ -567,8 +567,8 @@ Type: `Object[]` | **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 | +| **schedule** | `{ cronExpression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; timezone?: string }` | ✅ | Schedule timing configuration | +| **delivery** | `{ method: Enum<'email' \| 'storage' \| 'webhook'>; recipients?: string[]; storagePath?: string; webhookUrl?: string }` | ✅ | Export delivery configuration | | **enabled** | `boolean` | optional | Whether the scheduled export is active | | **lastRunAt** | `string` | optional | Last execution timestamp | | **nextRunAt** | `string` | optional | Next scheduled execution | diff --git a/content/docs/references/api/feed-api.mdx b/content/docs/references/api/feed-api.mdx index 47560d3e8e..6d91226c1d 100644 --- a/content/docs/references/api/feed-api.mdx +++ b/content/docs/references/api/feed-api.mdx @@ -82,9 +82,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ reactions: { emoji: string; userIds: string[]; count: integer }[] }` | ✅ | | --- @@ -98,8 +98,8 @@ const result = AddReactionRequest.parse(data); | **id** | `string` | ✅ | Changelog entry ID | | **object** | `string` | ✅ | Object name | | **recordId** | `string` | ✅ | Record ID | -| **actor** | `Object` | ✅ | Who made the change | -| **changes** | `Object[]` | ✅ | Field-level changes | +| **actor** | `{ type: Enum<'user' \| 'system' \| 'service' \| 'automation'>; id: string; name?: string }` | ✅ | Who made the change | +| **changes** | `{ field: string; fieldLabel?: string; oldValue?: any; newValue?: any; … }[]` | ✅ | Field-level changes | | **timestamp** | `string` | ✅ | When the change occurred | | **source** | `string` | optional | Change source (e.g., "API", "UI", "automation") | @@ -116,7 +116,7 @@ const result = AddReactionRequest.parse(data); | **recordId** | `string` | ✅ | Record ID | | **type** | `Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>` | ✅ | Type of feed item to create | | **body** | `string` | optional | Rich text body (Markdown supported) | -| **mentions** | `Object[]` | optional | Mentioned users, teams, or records | +| **mentions** | `{ type: Enum<'user' \| 'team' \| 'record'>; id: string; name: string; offset: integer; … }[]` | optional | Mentioned users, teams, or records | | **parentId** | `string` | optional | Parent feed item ID for threaded replies | | **visibility** | `Enum<'public' \| 'internal' \| 'private'>` | ✅ | Visibility: public, internal, or private | @@ -130,9 +130,9 @@ const result = AddReactionRequest.parse(data); | 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 feed item | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id: string; type: Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>; object: string; recordId: string; … }` | ✅ | The created feed item | --- @@ -157,9 +157,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ feedId: string }` | ✅ | | --- @@ -260,9 +260,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ entries: { id: string; object: string; recordId: string; actor: object; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -289,9 +289,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ items: { id: string; type: Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>; object: string; recordId: string; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -316,9 +316,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ feedId: string; pinned: boolean; pinnedAt: string }` | ✅ | | --- @@ -344,9 +344,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ reactions: { emoji: string; userIds: string[]; count: integer }[] }` | ✅ | | --- @@ -380,9 +380,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ items: { id: string; type: Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>; object: string; recordId: string; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -407,9 +407,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ feedId: string; starred: boolean; starredAt: string }` | ✅ | | --- @@ -435,9 +435,9 @@ const result = AddReactionRequest.parse(data); | 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 or updated subscription | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ object: string; recordId: string; userId: string; events: Enum<'comment' \| 'mention' \| 'field_change' \| 'task' \| 'approval' \| 'all'>[]; … }` | ✅ | The created or updated subscription | --- @@ -462,9 +462,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ feedId: string; pinned: boolean }` | ✅ | | --- @@ -489,9 +489,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ feedId: string; starred: boolean }` | ✅ | | --- @@ -503,9 +503,9 @@ const result = AddReactionRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ object: string; recordId: string; unsubscribed: boolean }` | ✅ | | --- @@ -520,7 +520,7 @@ const result = AddReactionRequest.parse(data); | **recordId** | `string` | ✅ | Record ID | | **feedId** | `string` | ✅ | Feed item ID | | **body** | `string` | optional | Updated rich text body | -| **mentions** | `Object[]` | optional | Updated mentions | +| **mentions** | `{ type: Enum<'user' \| 'team' \| 'record'>; id: string; name: string; offset: integer; … }[]` | optional | Updated mentions | | **visibility** | `Enum<'public' \| 'internal' \| 'private'>` | optional | Updated visibility | @@ -533,9 +533,9 @@ const result = AddReactionRequest.parse(data); | 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 feed item | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id: string; type: Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>; object: string; recordId: string; … }` | ✅ | The updated feed item | --- diff --git a/content/docs/references/api/graphql.mdx b/content/docs/references/api/graphql.mdx index 997b782230..4cfffaeab8 100644 --- a/content/docs/references/api/graphql.mdx +++ b/content/docs/references/api/graphql.mdx @@ -55,9 +55,9 @@ GraphQL provides: - GraphQL playground -@see https://graphql.org/ +See also: https://graphql.org/ -@see https://spec.graphql.org/ +See also: https://spec.graphql.org/ @example GraphQL Query @@ -142,10 +142,10 @@ const result = FederationEntity.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **typeName** | `string` | ✅ | GraphQL type name for this entity | -| **keys** | `Object[]` | ✅ | Entity key definitions | -| **externalFields** | `Object[]` | optional | Fields owned by other subgraphs | -| **requires** | `Object[]` | optional | Required external fields for computed fields | -| **provides** | `Object[]` | optional | Fields provided during resolution | +| **keys** | `{ fields: string; resolvable: boolean }[]` | ✅ | Entity key definitions | +| **externalFields** | `{ field: string; ownerSubgraph?: string }[]` | optional | Fields owned by other subgraphs | +| **requires** | `{ field: string; fields: string }[]` | optional | Required external fields for computed fields | +| **provides** | `{ field: string; fields: string }[]` | optional | Fields provided during resolution | | **owner** | `boolean` | ✅ | Whether this subgraph is the owner of this entity | @@ -183,11 +183,11 @@ const result = FederationEntity.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable GraphQL Federation gateway mode | | **version** | `Enum<'v1' \| 'v2'>` | ✅ | Federation specification version | -| **subgraphs** | `Object[]` | ✅ | Subgraph configurations | -| **serviceDiscovery** | `Object` | optional | Service discovery configuration | -| **queryPlanning** | `Object` | optional | Query planning configuration | -| **composition** | `Object` | optional | Schema composition configuration | -| **errorHandling** | `Object` | optional | Error handling configuration | +| **subgraphs** | `{ name: string; url: string; schemaSource: Enum<'introspection' \| 'file' \| 'registry'>; schemaPath?: string; … }[]` | ✅ | Subgraph configurations | +| **serviceDiscovery** | `{ type: Enum<'static' \| 'dns' \| 'consul' \| 'kubernetes'>; pollIntervalMs?: integer; namespace?: string }` | optional | Service discovery configuration | +| **queryPlanning** | `{ strategy: Enum<'parallel' \| 'sequential' \| 'adaptive'>; maxDepth?: integer; dryRun: boolean }` | optional | Query planning configuration | +| **composition** | `{ conflictResolution: Enum<'error' \| 'first_wins' \| 'last_wins'>; validate: boolean }` | optional | Schema composition configuration | +| **errorHandling** | `{ includeSubgraphName: boolean; partialErrors: Enum<'propagate' \| 'nullify' \| 'reject'> }` | optional | Error handling configuration | --- @@ -224,11 +224,11 @@ const result = FederationEntity.parse(data); | :--- | :--- | :--- | :--- | | **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 | +| **playground** | `{ enabled?: boolean; path?: string }` | optional | GraphQL Playground configuration | +| **schema** | `{ autoGenerateTypes?: boolean; types?: { name: string; object: string; description?: string; fields?: object; … }[]; queries?: { name: string; object: string; type: Enum<'get' \| 'list' \| 'search'>; description?: string; … }[]; mutations?: { name: string; object: string; type: Enum<'create' \| 'update' \| 'delete' \| 'upsert' \| 'custom'>; description?: string; … }[]; … }` | optional | Schema generation configuration | +| **dataLoaders** | `{ name: string; source: string; batchFunction: object; cache?: object; … }[]` | optional | DataLoader configurations | +| **security** | `{ depthLimit?: object; complexity?: object; rateLimit?: object; persistedQueries?: object }` | optional | Security configuration | +| **federation** | `{ enabled?: boolean; version?: Enum<'v1' \| 'v2'>; subgraphs: { name: string; url: string; schemaSource?: Enum<'introspection' \| 'file' \| 'registry'>; schemaPath?: string; … }[]; serviceDiscovery?: object; … }` | optional | GraphQL Federation gateway configuration | --- @@ -241,9 +241,9 @@ const result = FederationEntity.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | DataLoader name | | **source** | `string` | ✅ | Source object or datasource | -| **batchFunction** | `Object` | ✅ | Batch function configuration | -| **cache** | `Object` | optional | DataLoader caching | -| **options** | `Object` | optional | DataLoader options | +| **batchFunction** | `{ type: Enum<'findByIds' \| 'query' \| 'script' \| 'custom'>; keyField?: string; query?: string; script?: string; … }` | ✅ | Batch function configuration | +| **cache** | `{ enabled: boolean; keyFn?: string }` | optional | DataLoader caching | +| **options** | `{ batch: boolean; cache: boolean; maxCacheSize?: integer }` | optional | DataLoader options | --- @@ -257,9 +257,9 @@ const result = FederationEntity.parse(data); | **name** | `string` | ✅ | Directive name (camelCase) | | **description** | `string` | optional | Directive description | | **locations** | `Enum<'QUERY' \| 'MUTATION' \| 'SUBSCRIPTION' \| 'FIELD' \| 'FRAGMENT_DEFINITION' \| 'FRAGMENT_SPREAD' \| 'INLINE_FRAGMENT' \| 'VARIABLE_DEFINITION' \| 'SCHEMA' \| 'SCALAR' \| 'OBJECT' \| 'FIELD_DEFINITION' \| 'ARGUMENT_DEFINITION' \| 'INTERFACE' \| 'UNION' \| 'ENUM' \| 'ENUM_VALUE' \| 'INPUT_OBJECT' \| 'INPUT_FIELD_DEFINITION'>[]` | ✅ | Directive locations | -| **args** | `Record` | optional | Directive arguments | +| **args** | `Record` | optional | Directive arguments | | **repeatable** | `boolean` | ✅ | Can be applied multiple times | -| **implementation** | `Object` | optional | Directive implementation | +| **implementation** | `{ type: Enum<'auth' \| 'validation' \| 'transform' \| 'cache' \| 'deprecation' \| 'custom'>; handler?: string }` | optional | Directive implementation | --- @@ -301,12 +301,12 @@ const result = FederationEntity.parse(data); | **object** | `string` | ✅ | Source ObjectQL object name | | **type** | `Enum<'create' \| 'update' \| 'delete' \| 'upsert' \| 'custom'>` | ✅ | Mutation type | | **description** | `string` | optional | Mutation description | -| **input** | `Object` | optional | Input configuration | -| **output** | `Object` | optional | Output configuration | -| **transaction** | `Object` | optional | Transaction configuration | +| **input** | `{ typeName?: string; fields?: object; validation?: object }` | optional | Input configuration | +| **output** | `{ type: Enum<'object' \| 'payload' \| 'boolean' \| 'custom'>; includeEnvelope: boolean; customType?: string }` | optional | Output configuration | +| **transaction** | `{ enabled: boolean; isolationLevel?: Enum<'read_uncommitted' \| 'read_committed' \| 'repeatable_read' \| 'serializable'> }` | optional | Transaction configuration | | **authRequired** | `boolean` | ✅ | Require authentication | | **permissions** | `string[]` | optional | Required permissions | -| **hooks** | `Object` | optional | Lifecycle hooks | +| **hooks** | `{ before?: string[]; after?: string[] }` | optional | Lifecycle hooks | --- @@ -319,10 +319,10 @@ const result = FederationEntity.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable persisted queries | | **mode** | `Enum<'optional' \| 'required'>` | ✅ | Persisted query mode (optional: allow both, required: only persisted) | -| **store** | `Object` | optional | Query store configuration | -| **apq** | `Object` | optional | Automatic Persisted Queries configuration | -| **allowlist** | `Object` | optional | Query allow list configuration | -| **security** | `Object` | optional | Security configuration | +| **store** | `{ type: Enum<'memory' \| 'redis' \| 'database' \| 'file'>; connection?: string; ttl?: integer }` | optional | Query store configuration | +| **apq** | `{ enabled: boolean; hashAlgorithm: Enum<'sha256' \| 'sha1' \| 'md5'>; cache?: object }` | optional | Automatic Persisted Queries configuration | +| **allowlist** | `{ enabled: boolean; queries?: { id: string; operation?: string; query?: string }[]; source?: string }` | optional | Query allow list configuration | +| **security** | `{ maxQuerySize?: integer; rejectIntrospection: boolean }` | optional | Security configuration | --- @@ -336,7 +336,7 @@ const result = FederationEntity.parse(data); | **enabled** | `boolean` | ✅ | Enable query complexity limiting | | **maxComplexity** | `integer` | ✅ | Maximum query complexity | | **defaultFieldComplexity** | `integer` | ✅ | Default complexity per field | -| **fieldComplexity** | `Record` | optional | Per-field complexity configuration | +| **fieldComplexity** | `Record` | optional | Per-field complexity configuration | | **listMultiplier** | `number` | ✅ | Multiplier for list fields | | **onComplexityExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | ✅ | Action when complexity exceeded | | **errorMessage** | `string` | optional | Custom error message for complexity violations | @@ -354,14 +354,14 @@ const result = FederationEntity.parse(data); | **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 | +| **args** | `Record` | optional | Query arguments | +| **filtering** | `{ enabled?: boolean; fields?: string[]; operators?: Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'notIn' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'isNull' \| 'isNotNull'>[] }` | optional | Filtering capabilities | +| **sorting** | `{ enabled?: boolean; fields?: string[]; defaultSort?: object }` | optional | Sorting capabilities | +| **pagination** | `{ enabled?: boolean; type?: Enum<'offset' \| 'cursor' \| 'relay'>; defaultLimit?: integer; maxLimit?: integer; … }` | optional | Pagination configuration | +| **fields** | `{ required?: string[]; selectable?: string[] }` | optional | Field selection configuration | | **authRequired** | `boolean` | optional | Require authentication | | **permissions** | `string[]` | optional | Required permissions | -| **cache** | `Object` | optional | Query caching | +| **cache** | `{ enabled?: boolean; ttl?: integer; key?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }` | optional | Query caching | --- @@ -389,10 +389,10 @@ const result = FederationEntity.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable rate limiting | | **strategy** | `Enum<'token_bucket' \| 'fixed_window' \| 'sliding_window' \| 'cost_based'>` | ✅ | Rate limiting strategy | -| **global** | `Object` | optional | Global rate limits | -| **perUser** | `Object` | optional | Per-user rate limits | -| **costBased** | `Object` | optional | Cost-based rate limiting | -| **operations** | `Record` | optional | Per-operation rate limits | +| **global** | `{ maxRequests: integer; windowMs: integer }` | optional | Global rate limits | +| **perUser** | `{ maxRequests: integer; windowMs: integer }` | optional | Per-user rate limits | +| **costBased** | `{ enabled: boolean; maxCost: integer; windowMs: integer; useComplexityAsCost: boolean }` | optional | Cost-based rate limiting | +| **operations** | `Record` | optional | Per-operation rate limits | | **onLimitExceeded** | `Enum<'reject' \| 'queue' \| 'log'>` | ✅ | Action when rate limit exceeded | | **errorMessage** | `string` | optional | Custom error message for rate limit violations | | **includeHeaders** | `boolean` | ✅ | Include rate limit headers in response | @@ -408,8 +408,8 @@ const result = FederationEntity.parse(data); | :--- | :--- | :--- | :--- | | **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 | +| **implementation** | `{ datasource?: string; query?: string; expression?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; dependencies?: string[]; … }` | optional | Implementation configuration | +| **cache** | `{ enabled?: boolean; ttl?: integer; keyArgs?: string[] }` | optional | Resolver caching | --- @@ -453,11 +453,11 @@ const result = FederationEntity.parse(data); | **object** | `string` | ✅ | Source ObjectQL object name | | **events** | `Enum<'created' \| 'updated' \| 'deleted' \| 'custom'>[]` | ✅ | Events to subscribe to | | **description** | `string` | optional | Subscription description | -| **filter** | `Object` | optional | Subscription filtering | -| **payload** | `Object` | optional | Payload configuration | +| **filter** | `{ enabled: boolean; fields?: string[] }` | optional | Subscription filtering | +| **payload** | `{ includeEntity: boolean; includePreviousValues: boolean; includeMeta: boolean }` | optional | Payload configuration | | **authRequired** | `boolean` | ✅ | Require authentication | | **permissions** | `string[]` | optional | Required permissions | -| **rateLimit** | `Object` | optional | Subscription rate limiting | +| **rateLimit** | `{ enabled: boolean; maxSubscriptionsPerUser: integer; throttleMs?: integer }` | optional | Subscription rate limiting | --- @@ -471,10 +471,10 @@ const result = FederationEntity.parse(data); | **name** | `string` | ✅ | GraphQL type name (PascalCase recommended) | | **object** | `string` | ✅ | Source ObjectQL object name | | **description** | `string` | optional | Type description | -| **fields** | `Object` | optional | Field configuration | +| **fields** | `{ include?: string[]; exclude?: string[]; mappings?: Record }` | optional | Field configuration | | **interfaces** | `string[]` | optional | GraphQL interface names | | **isInterface** | `boolean` | ✅ | Define as GraphQL interface | -| **directives** | `Object[]` | optional | GraphQL directives | +| **directives** | `{ name: string; args?: Record }[]` | optional | GraphQL directives | --- @@ -489,8 +489,8 @@ const result = FederationEntity.parse(data); | **url** | `string` | ✅ | Subgraph endpoint URL | | **schemaSource** | `Enum<'introspection' \| 'file' \| 'registry'>` | ✅ | How to obtain the subgraph schema | | **schemaPath** | `string` | optional | Path to schema file (SDL format) | -| **entities** | `Object[]` | optional | Entity definitions for this subgraph | -| **healthCheck** | `Object` | optional | Subgraph health check configuration | +| **entities** | `{ typeName: string; keys: { fields: string; resolvable: boolean }[]; externalFields?: { field: string; ownerSubgraph?: string }[]; requires?: { field: string; fields: string }[]; … }[]` | optional | Entity definitions for this subgraph | +| **healthCheck** | `{ enabled: boolean; path: string; intervalMs: integer }` | optional | Subgraph health check configuration | | **forwardHeaders** | `string[]` | optional | HTTP headers to forward to this subgraph | diff --git a/content/docs/references/api/http-cache.mdx b/content/docs/references/api/http-cache.mdx index a4e1d6145b..4f7b15ab22 100644 --- a/content/docs/references/api/http-cache.mdx +++ b/content/docs/references/api/http-cache.mdx @@ -13,7 +13,7 @@ Implements P0 requirement for ObjectStack kernel. ## Caching in ObjectStack -**HTTP Cache (`api/http-cache.zod.ts`) - This File** +**HTTP Cache (`[api/http-cache.zod.ts](/docs/references/api/http-cache)`) - This File** - **Purpose**: Cache API responses at HTTP protocol level @@ -25,7 +25,7 @@ Implements P0 requirement for ObjectStack kernel. - **Scope**: HTTP layer, client-server communication -**Application Cache (`system/cache.zod.ts`)** +**Application Cache (`[system/cache.zod.ts](/docs/references/system/cache)`)** - **Purpose**: Cache computed data, query results, aggregations @@ -49,7 +49,7 @@ Implements P0 requirement for ObjectStack kernel. Industry alignment: HTTP Caching (RFC 7234), Salesforce Metadata API -@see ../../system/cache.zod.ts for application-level caching +See also: ../../[system/cache.zod.ts](/docs/references/system/cache) for application-level caching **Source:** `packages/spec/src/api/http-cache.zod.ts` @@ -156,7 +156,7 @@ const result = CacheControl.parse(data); | :--- | :--- | :--- | :--- | | **ifNoneMatch** | `string` | optional | ETag value for conditional request (If-None-Match header) | | **ifModifiedSince** | `string` | optional | Timestamp for conditional request (If-Modified-Since header) | -| **cacheControl** | `Object` | optional | Client cache control preferences | +| **cacheControl** | `{ directives: Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]; maxAge?: number; staleWhileRevalidate?: number; staleIfError?: number }` | optional | Client cache control preferences | --- @@ -168,9 +168,9 @@ const result = CacheControl.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **data** | `any` | optional | Metadata payload (omitted for 304 Not Modified) | -| **etag** | `Object` | optional | ETag for this resource version | +| **etag** | `{ value: string; weak: boolean }` | optional | ETag for this resource version | | **lastModified** | `string` | optional | Last modification timestamp | -| **cacheControl** | `Object` | optional | Cache control directives | +| **cacheControl** | `{ directives: Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]; maxAge?: number; staleWhileRevalidate?: number; staleIfError?: number }` | optional | Cache control directives | | **notModified** | `boolean` | ✅ | True if resource has not been modified (304 response) | | **version** | `string` | optional | Metadata version identifier | diff --git a/content/docs/references/api/metadata-plugin.mdx b/content/docs/references/api/metadata-plugin.mdx index 60b07ddd2d..dc3fa4e956 100644 --- a/content/docs/references/api/metadata-plugin.mdx +++ b/content/docs/references/api/metadata-plugin.mdx @@ -27,7 +27,7 @@ const result = MetadataBulkRegisterRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | Items to register | +| **items** | `{ type: string; name: string; data: Record }[]` | ✅ | Items to register | | **continueOnError** | `boolean` | ✅ | Continue on individual failure | | **validate** | `boolean` | ✅ | Validate before registering | diff --git a/content/docs/references/api/metadata.mdx b/content/docs/references/api/metadata.mdx index ccc6859521..c5dcd26ba5 100644 --- a/content/docs/references/api/metadata.mdx +++ b/content/docs/references/api/metadata.mdx @@ -66,9 +66,9 @@ const result = AppDefinitionResponse.parse(data); | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; label: string; version?: string; description?: string; … }` | ✅ | Full App Configuration | --- @@ -80,9 +80,9 @@ const result = AppDefinitionResponse.parse(data); | 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[]` | ✅ | List of available concepts (Objects, Apps, Flows) | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; label: string; icon?: string; description?: string }[]` | ✅ | List of available concepts (Objects, Apps, Flows) | --- @@ -94,9 +94,9 @@ const result = AppDefinitionResponse.parse(data); | 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` | ✅ | Bulk operation result | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ total: integer; succeeded: integer; failed: integer; errors?: { type: string; name: string; error: string }[] }` | ✅ | Bulk operation result | --- @@ -107,7 +107,7 @@ const result = AppDefinitionResponse.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | Items to unregister | +| **items** | `{ type: string; name: string }[]` | ✅ | Items to unregister | --- @@ -119,9 +119,9 @@ const result = AppDefinitionResponse.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ type: string; name: string }` | ✅ | | --- @@ -133,9 +133,9 @@ const result = AppDefinitionResponse.parse(data); | 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[]` | ✅ | Items this item depends on | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ sourceType: string; sourceName: string; targetType: string; targetName: string; … }[]` | ✅ | Items this item depends on | --- @@ -147,9 +147,9 @@ const result = AppDefinitionResponse.parse(data); | 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[]` | ✅ | Items that depend on this item | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ sourceType: string; sourceName: string; targetType: string; targetName: string; … }[]` | ✅ | Items that depend on this item | --- @@ -161,8 +161,8 @@ const result = AppDefinitionResponse.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `Record` | optional | Effective metadata with all overlays applied | @@ -175,9 +175,9 @@ const result = AppDefinitionResponse.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ exists: boolean }` | ✅ | | --- @@ -202,8 +202,8 @@ const result = AppDefinitionResponse.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `any` | ✅ | Exported metadata bundle | @@ -230,9 +230,9 @@ const result = AppDefinitionResponse.parse(data); | 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` | ✅ | Import result | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ total: integer; imported: integer; skipped: integer; failed: integer; … }` | ✅ | Import result | --- @@ -244,9 +244,9 @@ const result = AppDefinitionResponse.parse(data); | 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` | ✅ | Metadata item | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ type: string; name: string; definition: Record }` | ✅ | Metadata item | --- @@ -258,8 +258,8 @@ const result = AppDefinitionResponse.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `Record[]` | ✅ | Array of metadata definitions | @@ -272,8 +272,8 @@ const result = AppDefinitionResponse.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `string[]` | ✅ | Array of metadata item names | @@ -286,9 +286,9 @@ const result = AppDefinitionResponse.parse(data); | 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 | Overlay definition, undefined if none | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ id: string; baseType: string; baseName: string; packageId?: string; … }` | optional | Overlay definition, undefined if none | --- @@ -310,7 +310,7 @@ Overlay to save | **tenantId** | `string` | optional | Tenant identifier | | **owner** | `string` | optional | Owner user ID for user-scope overlays | | **patch** | `Record` | ✅ | JSON Merge Patch payload (changed fields only) | -| **changes** | `Object[]` | optional | Field-level change tracking for conflict detection | +| **changes** | `{ path: string; originalValue?: any; currentValue: any; changedBy?: string; … }[]` | optional | Field-level change tracking for conflict detection | | **active** | `boolean` | ✅ | Whether this overlay is active | | **createdAt** | `string` | optional | | | **createdBy** | `string` | optional | | @@ -350,9 +350,9 @@ Metadata query with filtering, sorting, and pagination | 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` | ✅ | Paginated query result | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ items: { type: string; name: string; namespace?: string; label?: string; … }[]; total: integer; page: integer; pageSize: integer }` | ✅ | Paginated query result | --- @@ -378,9 +378,9 @@ Metadata query with filtering, sorting, and pagination | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ type: string; label: string; description?: string; filePatterns: string[]; … }` | optional | Type info | --- @@ -392,8 +392,8 @@ Metadata query with filtering, sorting, and pagination | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **data** | `string[]` | ✅ | Registered metadata type identifiers | @@ -418,9 +418,9 @@ Metadata query with filtering, sorting, and pagination | 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` | ✅ | Validation result | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ valid: boolean; errors?: { path: string; message: string; code?: string }[]; warnings?: { path: string; message: string }[] }` | ✅ | Validation result | --- @@ -432,9 +432,9 @@ Metadata query with filtering, sorting, and pagination | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ name: string; label?: string; pluralLabel?: string; description?: string; … }` | ✅ | Full Object Schema | --- diff --git a/content/docs/references/api/object.mdx b/content/docs/references/api/object.mdx index 0b7d48412a..cbdb9b5208 100644 --- a/content/docs/references/api/object.mdx +++ b/content/docs/references/api/object.mdx @@ -30,11 +30,11 @@ const result = VersioningConfig.parse(data); | **strategy** | `Enum<'urlPath' \| 'header' \| 'queryParam' \| 'dateBased'>` | ✅ | How the API version is specified by clients | | **current** | `string` | ✅ | The current/recommended API version identifier | | **default** | `string` | ✅ | Fallback version when client does not specify one | -| **versions** | `Object[]` | ✅ | All available API versions with lifecycle metadata | +| **versions** | `{ version: string; status: Enum<'preview' \| 'current' \| 'supported' \| 'deprecated' \| 'retired'>; releasedAt: string; deprecatedAt?: string; … }[]` | ✅ | All available API versions with lifecycle metadata | | **headerName** | `string` | ✅ | HTTP header name for version negotiation (header/dateBased strategies) | | **queryParamName** | `string` | ✅ | Query parameter name for version specification (queryParam strategy) | | **urlPrefix** | `string` | ✅ | URL prefix before version segment (urlPath strategy) | -| **deprecation** | `Object` | optional | Deprecation lifecycle behavior | +| **deprecation** | `{ warnHeader: boolean; sunsetHeader: boolean; linkHeader: boolean; rejectRetired: boolean; … }` | optional | Deprecation lifecycle behavior | | **includeInDiscovery** | `boolean` | ✅ | Include version information in the API discovery endpoint | diff --git a/content/docs/references/api/odata.mdx b/content/docs/references/api/odata.mdx index f7855bb355..6121bc5841 100644 --- a/content/docs/references/api/odata.mdx +++ b/content/docs/references/api/odata.mdx @@ -55,9 +55,9 @@ OData v4 provides standardized URL conventions for querying data including: - Data virtualization -@see https://www.odata.org/documentation/ +See also: https://www.odata.org/documentation/ -@see https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html +See also: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html @example OData Query @@ -129,7 +129,7 @@ const result = ODataConfig.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable OData API | | **path** | `string` | ✅ | OData endpoint path | -| **metadata** | `Object` | optional | OData metadata configuration | +| **metadata** | `{ namespace: string; entityTypes: { name: string; key: string[]; properties: { name: string; type: string; nullable: boolean }[]; navigationProperties?: { name: string; type: string; partner?: string }[] }[]; entitySets: { name: string; entityType: string }[] }` | optional | OData metadata configuration | --- @@ -140,7 +140,7 @@ const result = ODataConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **error** | `Object` | ✅ | | +| **error** | `{ code: string; message: string; target?: string; details?: { code: string; message: string; target?: string }[]; … }` | ✅ | | --- @@ -209,8 +209,8 @@ const result = ODataConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **namespace** | `string` | ✅ | Service namespace | -| **entityTypes** | `Object[]` | ✅ | Entity types | -| **entitySets** | `Object[]` | ✅ | Entity sets | +| **entityTypes** | `{ name: string; key: string[]; properties: { name: string; type: string; nullable: boolean }[]; navigationProperties?: { name: string; type: string; partner?: string }[] }[]` | ✅ | Entity types | +| **entitySets** | `{ name: string; entityType: string }[]` | ✅ | Entity sets | --- diff --git a/content/docs/references/api/package-api.mdx b/content/docs/references/api/package-api.mdx index ed9879457b..1c1d0f4672 100644 --- a/content/docs/references/api/package-api.mdx +++ b/content/docs/references/api/package-api.mdx @@ -65,9 +65,9 @@ Get installed package response | 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 | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Installed package details | --- @@ -97,9 +97,9 @@ List installed packages response | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ packages: { manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }[]; total?: integer; nextCursor?: string; hasMore: boolean }` | ✅ | | --- @@ -133,11 +133,11 @@ Install package request | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | Package manifest to install | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | 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 | +| **artifactRef** | `{ url: string; sha256: string; size: integer; format?: Enum<'tgz' \| 'zip'>; … }` | optional | Artifact reference for marketplace installation | --- @@ -151,9 +151,9 @@ Install package response | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ package: object; dependencyResolution?: object; namespaceConflicts?: { type: 'namespace_conflict'; requestedNamespace: string; conflictingPackageId: string; conflictingPackageName: string; … }[]; message?: string }` | ✅ | | --- @@ -193,9 +193,9 @@ Rollback package response | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ success: boolean; restoredVersion?: string; message?: string }` | ✅ | | --- @@ -210,7 +210,7 @@ Upgrade package request | :--- | :--- | :--- | :--- | | **packageId** | `string` | ✅ | Package ID to upgrade | | **targetVersion** | `string` | optional | Target version (defaults to latest) | -| **manifest** | `Object` | optional | New manifest for the target version | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | 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 | @@ -228,9 +228,9 @@ Upgrade package response | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ success: boolean; phase: string; plan?: object; snapshotId?: string; … }` | ✅ | | --- @@ -243,7 +243,7 @@ Resolve dependencies request | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | Package manifest to resolve dependencies for | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | Package manifest to resolve dependencies for | | **platformVersion** | `string` | optional | Current platform version for compatibility filtering | @@ -258,9 +258,9 @@ Resolve dependencies response | 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` | ✅ | Dependency resolution result with topological sort | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ dependencies: { packageId: string; requiredRange: string; resolvedVersion?: string; installedVersion?: string; … }[]; canProceed: boolean; requiredActions: { type: Enum<'install' \| 'upgrade' \| 'confirm_conflict'>; packageId: string; description: string }[]; installOrder: string[]; … }` | ✅ | Dependency resolution result with topological sort | --- @@ -285,9 +285,9 @@ Uninstall package response | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ packageId: string; success: boolean; message?: string }` | ✅ | | --- @@ -300,7 +300,7 @@ Upload artifact request | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **artifact** | `Object` | ✅ | Package artifact metadata | +| **artifact** | `{ formatVersion: string; packageId: string; version: string; format: Enum<'tgz' \| 'zip'>; … }` | ✅ | Package artifact metadata | | **sha256** | `string` | optional | SHA256 checksum of the uploaded file | | **token** | `string` | optional | Publisher authentication token | | **releaseNotes** | `string` | optional | Release notes for this version | @@ -317,9 +317,9 @@ Upload artifact response | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ success: boolean; artifactRef?: object; submissionId?: string; message?: string }` | ✅ | | --- diff --git a/content/docs/references/api/package-registry.mdx b/content/docs/references/api/package-registry.mdx index feafa7bf2c..e48585dbdc 100644 --- a/content/docs/references/api/package-registry.mdx +++ b/content/docs/references/api/package-registry.mdx @@ -42,7 +42,7 @@ Disable package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Disabled package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Disabled package details | | **message** | `string` | optional | Disable status message | @@ -69,7 +69,7 @@ Enable package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Enabled package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Enabled package details | | **message** | `string` | optional | Enable status message | @@ -96,7 +96,7 @@ Get package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Package details | --- @@ -109,7 +109,7 @@ Install package request | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | Package manifest to install | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | 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 | @@ -125,9 +125,9 @@ Install package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Installed package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Installed package details | | **message** | `string` | optional | Installation status message | -| **dependencyResolution** | `Object` | optional | Dependency resolution result from install analysis | +| **dependencyResolution** | `{ dependencies: { packageId: string; requiredRange: string; resolvedVersion?: string; installedVersion?: string; … }[]; canProceed: boolean; requiredActions: { type: Enum<'install' \| 'upgrade' \| 'confirm_conflict'>; packageId: string; description: string }[]; installOrder: string[]; … }` | optional | Dependency resolution result from install analysis | --- @@ -155,7 +155,7 @@ List packages response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **packages** | `Object[]` | ✅ | List of installed packages | +| **packages** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }[]` | ✅ | List of installed packages | | **total** | `number` | ✅ | Total package count | diff --git a/content/docs/references/api/plugin-rest-api.mdx b/content/docs/references/api/plugin-rest-api.mdx index 45aee6497d..f8c0b07a4a 100644 --- a/content/docs/references/api/plugin-rest-api.mdx +++ b/content/docs/references/api/plugin-rest-api.mdx @@ -173,10 +173,10 @@ const result = ErrorHandlingConfig.parse(data); | **includeInternal** | `boolean` | ✅ | Include internal endpoints in documentation | | **generateSchemas** | `boolean` | ✅ | Auto-generate schemas from Zod definitions | | **includeExamples** | `boolean` | ✅ | Include request/response examples | -| **servers** | `Object[]` | optional | Server URLs for API | -| **contact** | `Object` | optional | API contact information | -| **license** | `Object` | optional | API license information | -| **securitySchemes** | `Record` | optional | Security scheme definitions | +| **servers** | `{ url: string; description?: string }[]` | optional | Server URLs for API | +| **contact** | `{ name?: string; url?: string; email?: string }` | optional | API contact information | +| **license** | `{ name: string; url?: string }` | optional | API license information | +| **securitySchemes** | `Record; scheme?: string; bearerFormat?: string }>` | optional | Security scheme definitions | --- @@ -253,14 +253,14 @@ const result = ErrorHandlingConfig.parse(data); | **enabled** | `boolean` | ✅ | Enable REST API plugin | | **basePath** | `string` | ✅ | Base path for all API routes | | **version** | `string` | ✅ | API version identifier | -| **routes** | `Object[]` | ✅ | Route registrations | -| **validation** | `Object` | optional | Request validation configuration | -| **responseEnvelope** | `Object` | optional | Response envelope configuration | -| **errorHandling** | `Object` | optional | Error handling configuration | -| **openApi** | `Object` | optional | OpenAPI documentation configuration | -| **globalMiddleware** | `Object[]` | optional | Global middleware stack | -| **cors** | `Object` | optional | CORS configuration | -| **performance** | `Object` | optional | Performance optimization settings | +| **routes** | `{ prefix: string; service: string; category: Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>; methods?: string[]; … }[]` | ✅ | Route registrations | +| **validation** | `{ enabled: boolean; mode: Enum<'strict' \| 'permissive' \| 'strip'>; validateBody: boolean; validateQuery: boolean; … }` | optional | Request validation configuration | +| **responseEnvelope** | `{ enabled: boolean; includeMetadata: boolean; includeTimestamp: boolean; includeRequestId: boolean; … }` | optional | Response envelope configuration | +| **errorHandling** | `{ enabled: boolean; includeStackTrace: boolean; logErrors: boolean; exposeInternalErrors: boolean; … }` | optional | Error handling configuration | +| **openApi** | `{ enabled: boolean; version: Enum<'3.0.0' \| '3.0.1' \| '3.0.2' \| '3.0.3' \| '3.1.0'>; title: string; description?: string; … }` | optional | OpenAPI documentation configuration | +| **globalMiddleware** | `{ name: string; type: Enum<'authentication' \| 'authorization' \| 'logging' \| 'validation' \| 'transformation' \| 'error' \| 'custom'>; enabled: boolean; order: integer; … }[]` | optional | Global middleware stack | +| **cors** | `{ enabled: boolean; origins?: string[]; methods?: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>[]; credentials: boolean }` | optional | CORS configuration | +| **performance** | `{ enableCompression: boolean; enableETag: boolean; enableCaching: boolean; defaultCacheTtl: integer }` | optional | Performance optimization settings | --- @@ -296,10 +296,10 @@ const result = ErrorHandlingConfig.parse(data); | **service** | `string` | ✅ | Core service name (metadata, data, auth, etc.) | | **category** | `Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>` | ✅ | Primary category for this route group | | **methods** | `string[]` | optional | Protocol method names implemented | -| **endpoints** | `Object[]` | optional | Endpoint definitions | -| **middleware** | `Object[]` | optional | Middleware stack for this route group | +| **endpoints** | `{ method: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>; path: string; handler: string; category: Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>; … }[]` | optional | Endpoint definitions | +| **middleware** | `{ name: string; type: Enum<'authentication' \| 'authorization' \| 'logging' \| 'validation' \| 'transformation' \| 'error' \| 'custom'>; enabled: boolean; order: integer; … }[]` | optional | Middleware stack for this route group | | **authRequired** | `boolean` | ✅ | Whether authentication is required by default | -| **documentation** | `Object` | optional | Documentation metadata for this route group | +| **documentation** | `{ title?: string; description?: string; tags?: string[] }` | optional | Documentation metadata for this route group | --- @@ -328,8 +328,8 @@ const result = ErrorHandlingConfig.parse(data); | :--- | :--- | :--- | :--- | | **timestamp** | `string` | ✅ | ISO 8601 timestamp | | **adapter** | `string` | ✅ | Adapter name (e.g. "hono", "express", "nextjs") | -| **summary** | `Object` | ✅ | | -| **entries** | `Object[]` | ✅ | Per-endpoint coverage entries | +| **summary** | `{ total: integer; implemented: integer; stub: integer; planned: integer }` | ✅ | | +| **entries** | `{ path: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>; category: Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>; handlerStatus: Enum<'implemented' \| 'stub' \| 'planned'>; … }[]` | ✅ | Per-endpoint coverage entries | --- diff --git a/content/docs/references/api/protocol.mdx b/content/docs/references/api/protocol.mdx index 45d38d2d32..3a0224acb5 100644 --- a/content/docs/references/api/protocol.mdx +++ b/content/docs/references/api/protocol.mdx @@ -11,7 +11,7 @@ Returns the live action/node registry — the platform's built-in actions plus any plugin-contributed ones — backing the designer palette and flow -validation. Each entry is a canonical [ActionDescriptorSchema](ActionDescriptorSchema). +validation. Each entry is a canonical `ActionDescriptorSchema`. **Source:** `packages/spec/src/api/protocol.zod.ts` @@ -48,7 +48,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **insights** | `Object[]` | ✅ | Generated insights | +| **insights** | `{ type: string; title: string; description: string; confidence?: number; … }[]` | ✅ | Generated insights | --- @@ -100,7 +100,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **suggestions** | `Object[]` | ✅ | Suggested values | +| **suggestions** | `{ value: any; label: string; confidence?: number; reason?: string }[]` | ✅ | Suggested values | --- @@ -111,7 +111,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **actions** | `Object[]` | ✅ | Registered action descriptors (built-in + plugin) | +| **actions** | `{ type: string; version: string; name: string; description?: string; … }[]` | ✅ | Registered action descriptors (built-in + plugin) | | **total** | `integer` | ✅ | Number of descriptors returned (after any filters) | @@ -149,7 +149,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | -| **request** | `Object` | ✅ | Batch operation request | +| **request** | `{ operation: Enum<'create' \| 'update' \| 'upsert' \| 'delete'>; records: { id?: string; data?: Record; externalId?: string }[]; options?: object }` | ✅ | Batch operation request | --- @@ -161,13 +161,13 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | optional | Operation type that was performed | | **total** | `number` | ✅ | Total number of records in the batch | | **succeeded** | `number` | ✅ | Number of records that succeeded | | **failed** | `number` | ✅ | Number of records that failed | -| **results** | `Object[]` | ✅ | Detailed results for each record | +| **results** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record; … }[]` | ✅ | Detailed results for each record | --- @@ -255,7 +255,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name (snake_case) | -| **data** | `Object` | ✅ | View definition to create | +| **data** | `{ list?: object; form?: object; listViews?: Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>; formViews?: Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }` | ✅ | View definition to create | --- @@ -268,7 +268,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | | **viewId** | `string` | ✅ | Created view identifier | -| **view** | `Object` | ✅ | Created view definition | +| **view** | `{ list?: object; form?: object; listViews?: Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>; formViews?: Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }` | ✅ | Created view definition | --- @@ -307,7 +307,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | | **ids** | `string[]` | ✅ | Array of record IDs to delete | -| **options** | `Object` | optional | Delete options | +| **options** | `{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }` | optional | Delete options | --- @@ -319,13 +319,13 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | optional | Operation type that was performed | | **total** | `number` | ✅ | Total number of records in the batch | | **succeeded** | `number` | ✅ | Number of records that succeeded | | **failed** | `number` | ✅ | Number of records that failed | -| **results** | `Object[]` | ✅ | Detailed results for each record | +| **results** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record; … }[]` | ✅ | Detailed results for each record | --- @@ -387,7 +387,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | The unique machine name of the object to query (e.g. "account"). | -| **query** | `[__schema0](./__schema0)` | optional | Structured query definition (filter, sort, select, pagination). | +| **query** | `{ object: string; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; where?: any; search?: object; … }` | optional | Structured query definition (filter, sort, select, pagination). | --- @@ -453,11 +453,11 @@ const result = AiInsightsRequest.parse(data); | **name** | `string` | optional | | | **version** | `string` | ✅ | | | **environment** | `Enum<'production' \| 'sandbox' \| 'development'>` | optional | | -| **routes** | `Object` | optional | | -| **locale** | `Object` | optional | | -| **services** | `Record` | optional | Per-service availability map keyed by CoreServiceName | -| **capabilities** | `Record` | optional | Hierarchical capability descriptors for frontend intelligent adaptation | -| **schemaDiscovery** | `Object` | optional | Schema discovery endpoints for API toolchain integration | +| **routes** | `{ data: string; metadata: string; discovery?: string; ui?: string; … }` | optional | | +| **locale** | `{ default: string; supported: string[]; timezone: string }` | optional | | +| **services** | `Record; handlerReady?: boolean; route?: string; … }>` | optional | Per-service availability map keyed by CoreServiceName | +| **capabilities** | `Record; description?: string }>` | optional | Hierarchical capability descriptors for frontend intelligent adaptation | +| **schemaDiscovery** | `{ openapi?: string; graphql?: string; jsonSchema?: string }` | optional | Schema discovery endpoints for API toolchain integration | | **metadata** | `Record` | optional | Custom metadata key-value pairs for extensibility | | **apiName** | `string` | optional | API name (deprecated — use name) | @@ -480,7 +480,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **objects** | `Record` | ✅ | Effective object permissions keyed by object name | +| **objects** | `Record` | ✅ | Effective object permissions keyed by object name | | **systemPermissions** | `string[]` | ✅ | Effective system-level permissions | @@ -506,7 +506,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | | **locale** | `string` | ✅ | Locale code | -| **labels** | `Record` | ✅ | Field labels keyed by field name | +| **labels** | `Record }>` | ✅ | Field labels keyed by field name | --- @@ -527,7 +527,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **locales** | `Object[]` | ✅ | Available locales | +| **locales** | `{ code: string; label: string; isDefault: boolean }[]` | ✅ | Available locales | --- @@ -540,7 +540,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **type** | `string` | ✅ | Metadata type name | | **name** | `string` | ✅ | Item name | -| **cacheRequest** | `Object` | optional | Cache validation parameters | +| **cacheRequest** | `{ ifNoneMatch?: string; ifModifiedSince?: string; cacheControl?: object }` | optional | Cache validation parameters | | **locale** | `string` | optional | Resolved response locale. Folded into the ETag so a language switch never returns a stale-locale 304 — metadata is translated *after* the cache validator check (issue #1319). | @@ -553,9 +553,9 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **data** | `any` | optional | Metadata payload (omitted for 304 Not Modified) | -| **etag** | `Object` | optional | ETag for this resource version | +| **etag** | `{ value: string; weak: boolean }` | optional | ETag for this resource version | | **lastModified** | `string` | optional | Last modification timestamp | -| **cacheControl** | `Object` | optional | Cache control directives | +| **cacheControl** | `{ directives: Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]; maxAge?: number; staleWhileRevalidate?: number; staleIfError?: number }` | optional | Cache control directives | | **notModified** | `boolean` | ✅ | True if resource has not been modified (304 response) | | **version** | `string` | optional | Metadata version identifier | @@ -629,7 +629,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **types** | `string[]` | ✅ | Available metadata type names (e.g., "object", "plugin", "view") | -| **entries** | `Object[]` | optional | Enriched per-type registry entries (Phase 3a) | +| **entries** | `{ type: string; label: string; description?: string; filePatterns: string[]; … }[]` | optional | Enriched per-type registry entries (Phase 3a) | --- @@ -650,7 +650,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **preferences** | `Object` | ✅ | Current notification preferences | +| **preferences** | `{ email: boolean; push: boolean; inApp: boolean; digest: Enum<'none' \| 'daily' \| 'weekly'>; … }` | ✅ | Current notification preferences | --- @@ -673,8 +673,8 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | -| **permissions** | `Object` | ✅ | Object-level permissions | -| **fieldPermissions** | `Record` | optional | Field-level permissions keyed by field name | +| **permissions** | `{ allowCreate: boolean; allowRead: boolean; allowEdit: boolean; allowDelete: boolean; … }` | ✅ | Object-level permissions | +| **fieldPermissions** | `Record` | optional | Field-level permissions keyed by field name | --- @@ -697,7 +697,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **channel** | `string` | ✅ | Channel name | -| **members** | `Object[]` | ✅ | Active members and their presence state | +| **members** | `{ userId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; metadata?: Record }[]` | ✅ | Active members and their presence state | --- @@ -722,7 +722,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **locale** | `string` | ✅ | Locale code | -| **translations** | `Object` | ✅ | Translation data | +| **translations** | `{ objects?: Record }>; … }>; apps?: Record }>; messages?: Record; validationMessages?: Record; … }` | ✅ | Translation data | --- @@ -745,11 +745,11 @@ const result = AiInsightsRequest.parse(data); | 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. | +| **list** | `{ name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }` | optional | | +| **form** | `{ type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }` | optional | | +| **listViews** | `Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>` | optional | Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047) | +| **formViews** | `Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>` | optional | Additional named form views | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -780,7 +780,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | -| **view** | `Object` | ✅ | View definition | +| **view** | `{ list?: object; form?: object; listViews?: Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>; formViews?: Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }` | ✅ | View definition | --- @@ -803,7 +803,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | -| **workflows** | `Object[]` | ✅ | Active state-machine workflows for this object | +| **workflows** | `{ id: string; description?: string; contextSchema?: Record; initial: string; … }[]` | ✅ | Active state-machine workflows for this object | --- @@ -828,7 +828,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | | **recordId** | `string` | ✅ | Record ID | -| **state** | `Object` | ✅ | Current workflow state and available transitions | +| **state** | `{ currentState: string; availableTransitions: { name: string; targetState: string; label?: string; requiresApproval: boolean }[]; history?: { fromState: string; toState: string; action: string; userId: string; … }[] }` | ✅ | Current workflow state and available transitions | --- @@ -874,7 +874,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **notifications** | `Object[]` | ✅ | List of notifications | +| **notifications** | `{ id: string; type: string; title: string; body: string; … }[]` | ✅ | List of notifications | | **unreadCount** | `number` | ✅ | Total number of unread notifications | | **cursor** | `string` | optional | Next page cursor | @@ -900,7 +900,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | -| **views** | `Object[]` | ✅ | Array of view definitions | +| **views** | `{ list?: object; form?: object; listViews?: Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>; formViews?: Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }[]` | ✅ | Array of view definitions | --- @@ -960,7 +960,7 @@ const result = AiInsightsRequest.parse(data); | **push** | `boolean` | ✅ | Receive push notifications | | **inApp** | `boolean` | ✅ | Receive in-app notifications | | **digest** | `Enum<'none' \| 'daily' \| 'weekly'>` | ✅ | Email digest frequency | -| **channels** | `Record` | optional | Per-channel notification preferences | +| **channels** | `Record` | optional | Per-channel notification preferences | --- @@ -1118,7 +1118,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **channel** | `string` | ✅ | Channel to set presence in | -| **state** | `Object` | ✅ | Presence state to set | +| **state** | `{ userId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; metadata?: Record }` | ✅ | Presence state to set | --- @@ -1190,8 +1190,8 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | -| **records** | `Object[]` | ✅ | Array of updates | -| **options** | `Object` | optional | Update options | +| **records** | `{ id: string; data: Record }[]` | ✅ | Array of updates | +| **options** | `{ atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean }` | optional | Update options | --- @@ -1203,13 +1203,13 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | | **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | optional | Operation type that was performed | | **total** | `number` | ✅ | Total number of records in the batch | | **succeeded** | `number` | ✅ | Number of records that succeeded | | **failed** | `number` | ✅ | Number of records that failed | -| **results** | `Object[]` | ✅ | Detailed results for each record | +| **results** | `{ id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record; … }[]` | ✅ | Detailed results for each record | --- @@ -1220,7 +1220,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **preferences** | `Object` | ✅ | Preferences to update | +| **preferences** | `{ email?: boolean; push?: boolean; inApp?: boolean; digest?: Enum<'none' \| 'daily' \| 'weekly'>; … }` | ✅ | Preferences to update | --- @@ -1231,7 +1231,7 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **preferences** | `Object` | ✅ | Updated notification preferences | +| **preferences** | `{ email: boolean; push: boolean; inApp: boolean; digest: Enum<'none' \| 'daily' \| 'weekly'>; … }` | ✅ | Updated notification preferences | --- @@ -1244,7 +1244,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name (snake_case) | | **viewId** | `string` | ✅ | View identifier | -| **data** | `Object` | ✅ | Partial view data to update | +| **data** | `{ list?: object; form?: object; listViews?: Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>; formViews?: Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }` | ✅ | Partial view data to update | --- @@ -1257,7 +1257,7 @@ const result = AiInsightsRequest.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name | | **viewId** | `string` | ✅ | Updated view identifier | -| **view** | `Object` | ✅ | Updated view definition | +| **view** | `{ list?: object; form?: object; listViews?: Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>; formViews?: Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>; … }` | ✅ | Updated view definition | --- @@ -1269,8 +1269,8 @@ const result = AiInsightsRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **currentState** | `string` | ✅ | Current workflow state name | -| **availableTransitions** | `Object[]` | ✅ | Available transitions from current state | -| **history** | `Object[]` | optional | State transition history | +| **availableTransitions** | `{ name: string; targetState: string; label?: string; requiresApproval: boolean }[]` | ✅ | Available transitions from current state | +| **history** | `{ fromState: string; toState: string; action: string; userId: string; … }[]` | optional | State transition history | --- @@ -1299,7 +1299,7 @@ const result = AiInsightsRequest.parse(data); | **object** | `string` | ✅ | Object name | | **recordId** | `string` | ✅ | Record ID | | **success** | `boolean` | ✅ | Whether the transition succeeded | -| **state** | `Object` | ✅ | New workflow state after transition | +| **state** | `{ currentState: string; availableTransitions: { name: string; targetState: string; label?: string; requiresApproval: boolean }[]; history?: { fromState: string; toState: string; action: string; userId: string; … }[] }` | ✅ | New workflow state after transition | --- diff --git a/content/docs/references/api/query-adapter.mdx b/content/docs/references/api/query-adapter.mdx index 4d966b6768..c383246eb5 100644 --- a/content/docs/references/api/query-adapter.mdx +++ b/content/docs/references/api/query-adapter.mdx @@ -9,7 +9,7 @@ API Query DSL Adapter Protocol Defines mapping rules between the internal unified query DSL -(defined in `data/query.zod.ts`) and external API protocol formats: +(defined in `[data/query.zod.ts](/docs/references/data/query)`) and external API protocol formats: REST, GraphQL, and OData. @@ -17,13 +17,13 @@ This enables ObjectStack to expose a single internal query representation while supporting multiple API standards for external consumers. -@see data/query.zod.ts - Unified internal query DSL +See also: [data/query.zod.ts](/docs/references/data/query) - Unified internal query DSL -@see api/rest-server.zod.ts - REST API configuration +See also: [api/rest-server.zod.ts](/docs/references/api/rest-server) - REST API configuration -@see api/graphql.zod.ts - GraphQL API configuration +See also: [api/graphql.zod.ts](/docs/references/api/graphql) - GraphQL API configuration -@see api/odata.zod.ts - OData API configuration +See also: [api/odata.zod.ts](/docs/references/api/odata) - OData API configuration **Source:** `packages/spec/src/api/query-adapter.zod.ts` @@ -49,8 +49,8 @@ const result = GraphQLQueryAdapter.parse(data); | :--- | :--- | :--- | :--- | | **filterArgName** | `string` | ✅ | GraphQL filter argument name | | **filterStyle** | `Enum<'nested' \| 'flat' \| 'array'>` | ✅ | GraphQL filter nesting style | -| **pagination** | `Object` | optional | Pagination argument name mappings | -| **sorting** | `Object` | optional | Sort argument mapping | +| **pagination** | `{ limitArg: string; offsetArg: string; firstArg: string; afterArg: string }` | optional | Pagination argument name mappings | +| **sorting** | `{ argName: string; format: Enum<'enum' \| 'array'> }` | optional | Sort argument mapping | --- @@ -64,7 +64,7 @@ const result = GraphQLQueryAdapter.parse(data); | **version** | `Enum<'v2' \| 'v4'>` | ✅ | OData version | | **usePrefix** | `boolean` | ✅ | Use $ prefix for system query options ($filter vs filter) | | **stringFunctions** | `Enum<'contains' \| 'startswith' \| 'endswith' \| 'tolower' \| 'toupper' \| 'trim' \| 'concat' \| 'substring' \| 'length'>[]` | optional | Supported OData string functions | -| **expand** | `Object` | optional | $expand configuration | +| **expand** | `{ enabled: boolean; maxDepth: integer }` | optional | $expand configuration | --- @@ -89,10 +89,10 @@ const result = GraphQLQueryAdapter.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **operatorMappings** | `Object[]` | optional | Custom operator mappings | -| **rest** | `Object` | optional | REST query adapter configuration | -| **graphql** | `Object` | optional | GraphQL query adapter configuration | -| **odata** | `Object` | optional | OData query adapter configuration | +| **operatorMappings** | `{ operator: string; rest?: string; graphql?: string; odata?: string }[]` | optional | Custom operator mappings | +| **rest** | `{ filterStyle: Enum<'bracket' \| 'dot' \| 'flat' \| 'rsql'>; pagination?: object; sorting?: object; fieldsParam: string }` | optional | REST query adapter configuration | +| **graphql** | `{ filterArgName: string; filterStyle: Enum<'nested' \| 'flat' \| 'array'>; pagination?: object; sorting?: object }` | optional | GraphQL query adapter configuration | +| **odata** | `{ version: Enum<'v2' \| 'v4'>; usePrefix: boolean; stringFunctions?: Enum<'contains' \| 'startswith' \| 'endswith' \| 'tolower' \| 'toupper' \| 'trim' \| 'concat' \| 'substring' \| 'length'>[]; expand?: object }` | optional | OData query adapter configuration | --- @@ -115,8 +115,8 @@ const result = GraphQLQueryAdapter.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **filterStyle** | `Enum<'bracket' \| 'dot' \| 'flat' \| 'rsql'>` | ✅ | REST filter parameter encoding style | -| **pagination** | `Object` | optional | Pagination parameter name mappings | -| **sorting** | `Object` | optional | Sort parameter mapping | +| **pagination** | `{ limitParam: string; offsetParam: string; cursorParam: string; pageParam: string }` | optional | Pagination parameter name mappings | +| **sorting** | `{ param: string; format: Enum<'comma' \| 'array' \| 'pipe'> }` | optional | Sort parameter mapping | | **fieldsParam** | `string` | ✅ | Field selection parameter name | diff --git a/content/docs/references/api/realtime-shared.mdx b/content/docs/references/api/realtime-shared.mdx index 60dd9fc9df..197b8bbc23 100644 --- a/content/docs/references/api/realtime-shared.mdx +++ b/content/docs/references/api/realtime-shared.mdx @@ -21,9 +21,9 @@ realtime protocol (SSE/Polling/WebSocket) and the WebSocket collaboration protoc - `websocket.zod.ts` — Collaboration protocol (Cursor, OT editing, Advanced presence) -@see realtime.zod.ts for transport-layer configuration +See also: realtime.zod.ts for transport-layer configuration -@see websocket.zod.ts for collaborative editing protocol +See also: websocket.zod.ts for collaborative editing protocol **Source:** `packages/spec/src/api/realtime-shared.zod.ts` diff --git a/content/docs/references/api/realtime.mdx b/content/docs/references/api/realtime.mdx index e58285ef7e..9d63132416 100644 --- a/content/docs/references/api/realtime.mdx +++ b/content/docs/references/api/realtime.mdx @@ -33,7 +33,7 @@ const result = RealtimeConfig.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable realtime synchronization | | **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol | -| **subscriptions** | `Object[]` | optional | Default subscriptions | +| **subscriptions** | `{ id: string; events: { type: Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>; object?: string; filters?: any }[]; transport: Enum<'websocket' \| 'sse' \| 'polling'>; channel?: string }[]` | optional | Default subscriptions | --- @@ -89,7 +89,7 @@ const result = RealtimeConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique subscription identifier | -| **events** | `Object[]` | ✅ | Array of events to subscribe to | +| **events** | `{ type: Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>; object?: string; filters?: any }[]` | ✅ | Array of events to subscribe to | | **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol to use | | **channel** | `string` | optional | Optional channel name for grouping subscriptions | diff --git a/content/docs/references/api/registry.mdx b/content/docs/references/api/registry.mdx index 4d0bd6587e..f53f86ae24 100644 --- a/content/docs/references/api/registry.mdx +++ b/content/docs/references/api/registry.mdx @@ -99,9 +99,9 @@ const result = ApiDiscoveryQuery.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **apis** | `Object[]` | ✅ | Matching API entries | +| **apis** | `{ id: string; name: string; type: Enum<'rest' \| 'graphql' \| 'odata' \| 'websocket' \| 'file' \| 'auth' \| 'metadata' \| 'plugin' \| 'webhook' \| 'rpc'>; version: string; … }[]` | ✅ | Matching API entries | | **total** | `integer` | ✅ | Total matching APIs | -| **filters** | `Object` | optional | Applied query filters | +| **filters** | `{ type?: Enum<'rest' \| 'graphql' \| 'odata' \| 'websocket' \| 'file' \| 'auth' \| 'metadata' \| 'plugin' \| 'webhook' \| 'rpc'>; tags?: string[]; status?: Enum<'active' \| 'deprecated' \| 'experimental' \| 'beta'>; pluginSource?: string; … }` | optional | Applied query filters | --- @@ -119,16 +119,16 @@ const result = ApiDiscoveryQuery.parse(data); | **description** | `string` | optional | Detailed endpoint description | | **operationId** | `string` | optional | Unique operation identifier | | **tags** | `string[]` | ✅ | Tags for categorization | -| **parameters** | `Object[]` | ✅ | Endpoint parameters | -| **requestBody** | `Object` | optional | Request body specification | -| **responses** | `Object[]` | ✅ | Possible responses | -| **rateLimit** | `Object` | optional | Endpoint specific rate limiting | +| **parameters** | `{ name: string; in: Enum<'path' \| 'query' \| 'header' \| 'body' \| 'cookie'>; description?: string; required: boolean; … }[]` | ✅ | Endpoint parameters | +| **requestBody** | `{ description?: string; required: boolean; contentType: string; schema?: any; … }` | optional | Request body specification | +| **responses** | `{ statusCode: integer \| Enum<'2xx' \| '3xx' \| '4xx' \| '5xx'>; description: string; contentType: string; schema?: any \| { $ref: object }; … }[]` | ✅ | Possible responses | +| **rateLimit** | `{ enabled: boolean; windowMs: integer; maxRequests: integer }` | optional | Endpoint specific rate limiting | | **security** | `Record[]` | optional | Security requirements (e.g. [`{"bearerAuth": []}`]) | | **requiredPermissions** | `string[]` | ✅ | Required RBAC permissions (e.g., "customer.read", "manage_users") | | **priority** | `integer` | ✅ | Route priority for conflict resolution (0-1000, higher = more important) | | **protocolConfig** | `Record` | optional | Protocol-specific configuration for custom protocols (gRPC, tRPC, etc.) | | **deprecated** | `boolean` | ✅ | Whether endpoint is deprecated | -| **externalDocs** | `Object` | optional | External documentation link | +| **externalDocs** | `{ description?: string; url: string }` | optional | External documentation link | --- @@ -158,7 +158,7 @@ const result = ApiDiscoveryQuery.parse(data); | **in** | `Enum<'path' \| 'query' \| 'header' \| 'body' \| 'cookie'>` | ✅ | Parameter location | | **description** | `string` | optional | Parameter description | | **required** | `boolean` | ✅ | Whether parameter is required | -| **schema** | `Object \| Object` | ✅ | Parameter schema definition | +| **schema** | `{ type: Enum<'string' \| 'number' \| 'integer' \| 'boolean' \| 'array' \| 'object'>; format?: string; enum?: any[]; default?: any; … } \| { $ref: object }` | ✅ | Parameter schema definition | | **example** | `any` | optional | Example value | @@ -190,11 +190,11 @@ const result = ApiDiscoveryQuery.parse(data); | :--- | :--- | :--- | :--- | | **version** | `string` | ✅ | Registry version | | **conflictResolution** | `Enum<'error' \| 'priority' \| 'first-wins' \| 'last-wins'>` | ✅ | Strategy for handling route conflicts | -| **apis** | `Object[]` | ✅ | All registered APIs | +| **apis** | `{ id: string; name: string; type: Enum<'rest' \| 'graphql' \| 'odata' \| 'websocket' \| 'file' \| 'auth' \| 'metadata' \| 'plugin' \| 'webhook' \| 'rpc'>; version: string; … }[]` | ✅ | All registered APIs | | **totalApis** | `integer` | ✅ | Total number of registered APIs | | **totalEndpoints** | `integer` | ✅ | Total number of endpoints | -| **byType** | `Record` | optional | APIs grouped by protocol type | -| **byStatus** | `Record` | optional | APIs grouped by status | +| **byType** | `Record; version: string; … }[]>` | optional | APIs grouped by protocol type | +| **byStatus** | `Record; version: string; … }[]>` | optional | APIs grouped by status | | **updatedAt** | `string` | optional | Last registry update time | @@ -212,12 +212,12 @@ const result = ApiDiscoveryQuery.parse(data); | **version** | `string` | ✅ | API version (e.g., v1, 2024-01) | | **basePath** | `string` | ✅ | Base URL path for this API | | **description** | `string` | optional | API description | -| **endpoints** | `Object[]` | ✅ | Registered endpoints | +| **endpoints** | `{ id: string; method?: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>; path: string; summary?: string; … }[]` | ✅ | Registered endpoints | | **config** | `Record` | optional | Protocol-specific configuration | -| **metadata** | `Object` | optional | Additional metadata | +| **metadata** | `{ owner?: string; status: Enum<'active' \| 'deprecated' \| 'experimental' \| 'beta'>; tags: string[]; pluginSource?: string; … }` | optional | Additional metadata | | **termsOfService** | `string` | optional | Terms of service URL | -| **contact** | `Object` | optional | Contact information | -| **license** | `Object` | optional | License information | +| **contact** | `{ name?: string; url?: string; email?: string }` | optional | Contact information | +| **license** | `{ name: string; url?: string }` | optional | License information | --- @@ -231,8 +231,8 @@ const result = ApiDiscoveryQuery.parse(data); | **statusCode** | `integer \| Enum<'2xx' \| '3xx' \| '4xx' \| '5xx'>` | ✅ | HTTP status code | | **description** | `string` | ✅ | Response description | | **contentType** | `string` | ✅ | Response content type | -| **schema** | `any \| Object` | optional | Response body schema | -| **headers** | `Record` | optional | Response headers | +| **schema** | `any \| { $ref: object }` | optional | Response body schema | +| **headers** | `Record` | optional | Response headers | | **example** | `any` | optional | Example response | @@ -307,7 +307,7 @@ Dynamic ObjectQL reference | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **$ref** | `Object` | ✅ | Dynamic reference to ObjectQL object | +| **$ref** | `{ objectId: string; includeFields?: string[]; excludeFields?: string[]; includeRelated?: string[] }` | ✅ | Dynamic reference to ObjectQL object | --- diff --git a/content/docs/references/api/rest-server.mdx b/content/docs/references/api/rest-server.mdx index 2b7bdd76a5..50d4921ffe 100644 --- a/content/docs/references/api/rest-server.mdx +++ b/content/docs/references/api/rest-server.mdx @@ -55,7 +55,7 @@ const result = BatchEndpointsConfig.parse(data); | :--- | :--- | :--- | :--- | | **maxBatchSize** | `integer` | ✅ | Maximum records per batch operation | | **enableBatchEndpoint** | `boolean` | ✅ | Enable POST /data/:object/batch endpoint | -| **operations** | `Object` | optional | Enable/disable specific batch operations | +| **operations** | `{ createMany: boolean; updateMany: boolean; deleteMany: boolean; upsertMany: boolean }` | optional | Enable/disable specific batch operations | | **defaultAtomic** | `boolean` | ✅ | Default atomic/transaction mode for batch operations | @@ -95,8 +95,8 @@ const result = BatchEndpointsConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **operations** | `Object` | optional | Enable/disable operations | -| **patterns** | `Record` | optional | Custom URL patterns for operations | +| **operations** | `{ create: boolean; read: boolean; update: boolean; delete: boolean; … }` | optional | Enable/disable operations | +| **patterns** | `Record; path: string; summary?: string; description?: string }>` | optional | Custom URL patterns for operations | | **dataPrefix** | `string` | ✅ | URL prefix for data endpoints | | **objectParamStyle** | `Enum<'path' \| 'query'>` | ✅ | How object name is passed (path param or query param) | @@ -122,10 +122,10 @@ const result = BatchEndpointsConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **endpoints** | `Object[]` | ✅ | All generated endpoints | +| **endpoints** | `{ id: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>; path: string; object: string; … }[]` | ✅ | All generated endpoints | | **total** | `integer` | ✅ | Total number of endpoints | -| **byObject** | `Record` | optional | Endpoints grouped by object | -| **byOperation** | `Record` | optional | Endpoints grouped by operation | +| **byObject** | `Record; path: string; object: string; … }[]>` | optional | Endpoints grouped by object | +| **byOperation** | `Record; path: string; object: string; … }[]>` | optional | Endpoints grouped by operation | --- @@ -142,7 +142,7 @@ const result = BatchEndpointsConfig.parse(data); | **object** | `string` | ✅ | Object name (snake_case) | | **operation** | `Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'list'> \| string` | ✅ | Operation type | | **handler** | `string` | ✅ | Handler function identifier | -| **metadata** | `Object` | optional | | +| **metadata** | `{ summary?: string; description?: string; tags?: string[]; deprecated?: boolean }` | optional | | --- @@ -156,7 +156,7 @@ const result = BatchEndpointsConfig.parse(data); | **prefix** | `string` | ✅ | URL prefix for metadata endpoints | | **enableCache** | `boolean` | ✅ | Enable HTTP cache headers (ETag, Last-Modified) | | **cacheTtl** | `integer` | ✅ | Cache TTL in seconds | -| **endpoints** | `Object` | optional | Enable/disable specific endpoints | +| **endpoints** | `{ types: boolean; items: boolean; item: boolean; schema: boolean }` | optional | Enable/disable specific endpoints | --- @@ -167,8 +167,8 @@ const result = BatchEndpointsConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **webhooks** | `Record` | optional | OpenAPI 3.1 webhooks (top-level webhook definitions) | -| **callbacks** | `Record` | optional | OpenAPI 3.1 callbacks (async response definitions) | +| **webhooks** | `Record; payloadSchema: string; … }>` | optional | OpenAPI 3.1 webhooks (top-level webhook definitions) | +| **callbacks** | `Record; url: string }[]>` | optional | OpenAPI 3.1 callbacks (async response definitions) | | **jsonSchemaDialect** | `string` | ✅ | JSON Schema dialect for schema definitions | | **pathItemReferences** | `boolean` | ✅ | Allow $ref in path items (OpenAPI 3.1 feature) | @@ -193,8 +193,8 @@ const result = BatchEndpointsConfig.parse(data); | **enableProjectScoping** | `boolean` | ✅ | Enable project-scoped routing for data/meta/AI APIs | | **projectResolution** | `Enum<'required' \| 'optional' \| 'auto'>` | ✅ | Project ID resolution strategy | | **requireAuth** | `boolean` | ✅ | Reject anonymous requests on ALL HTTP surfaces that reach object data (REST /data, /meta, GraphQL, raw-hono /data) with HTTP 401 (secure-by-default; set false to serve them publicly) | -| **documentation** | `Object` | optional | OpenAPI/Swagger documentation config | -| **responseFormat** | `Object` | optional | Response format options | +| **documentation** | `{ enabled: boolean; title: string; description?: string; version?: string; … }` | optional | OpenAPI/Swagger documentation config | +| **responseFormat** | `{ envelope: boolean; includeMetadata: boolean; includePagination: boolean }` | optional | Response format options | --- @@ -205,12 +205,12 @@ const result = BatchEndpointsConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **api** | `Object` | optional | REST API configuration | -| **crud** | `Object` | optional | CRUD endpoints configuration | -| **metadata** | `Object` | optional | Metadata endpoints configuration | -| **batch** | `Object` | optional | Batch endpoints configuration | -| **routes** | `Object` | optional | Route generation configuration | -| **openApi31** | `Object` | optional | OpenAPI 3.1 extensions configuration | +| **api** | `{ version: string; basePath: string; apiPath?: string; enableCrud: boolean; … }` | optional | REST API configuration | +| **crud** | `{ operations?: object; patterns?: Record; path: string; summary?: string; description?: string }>; dataPrefix: string; objectParamStyle: Enum<'path' \| 'query'> }` | optional | CRUD endpoints configuration | +| **metadata** | `{ prefix: string; enableCache: boolean; cacheTtl: integer; endpoints?: object }` | optional | Metadata endpoints configuration | +| **batch** | `{ maxBatchSize: integer; enableBatchEndpoint: boolean; operations?: object; defaultAtomic: boolean }` | optional | Batch endpoints configuration | +| **routes** | `{ includeObjects?: string[]; excludeObjects?: string[]; nameTransform: Enum<'none' \| 'plural' \| 'kebab-case' \| 'camelCase'>; overrides?: Record }> }` | optional | Route generation configuration | +| **openApi31** | `{ webhooks?: Record; payloadSchema: string; … }>; callbacks?: Record; url: string }[]>; jsonSchemaDialect: string; pathItemReferences: boolean }` | optional | OpenAPI 3.1 extensions configuration | --- @@ -224,7 +224,7 @@ const result = BatchEndpointsConfig.parse(data); | **includeObjects** | `string[]` | optional | Specific objects to generate routes for (empty = all) | | **excludeObjects** | `string[]` | optional | Objects to exclude from route generation | | **nameTransform** | `Enum<'none' \| 'plural' \| 'kebab-case' \| 'camelCase'>` | ✅ | Transform object names in URLs | -| **overrides** | `Record` | optional | Per-object route customization | +| **overrides** | `Record }>` | optional | Per-object route customization | --- diff --git a/content/docs/references/api/router.mdx b/content/docs/references/api/router.mdx index f81caad0ca..681d0b230c 100644 --- a/content/docs/references/api/router.mdx +++ b/content/docs/references/api/router.mdx @@ -66,9 +66,9 @@ const result = RouteCategory.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **basePath** | `string` | ✅ | Global API prefix | -| **mounts** | `Object` | ✅ | | -| **cors** | `Object` | optional | | -| **staticMounts** | `Object[]` | optional | | +| **mounts** | `{ data: string; metadata: string; auth: string; automation: string; … }` | ✅ | | +| **cors** | `{ enabled: boolean; origins: string \| string[]; methods?: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>[]; credentials: boolean; … }` | optional | | +| **staticMounts** | `{ path: string; directory: string; cacheControl?: string }[]` | optional | | --- diff --git a/content/docs/references/api/storage.mdx b/content/docs/references/api/storage.mdx index 070532a186..7a8dd6516e 100644 --- a/content/docs/references/api/storage.mdx +++ b/content/docs/references/api/storage.mdx @@ -36,7 +36,7 @@ const result = CompleteChunkedUploadRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **uploadId** | `string` | ✅ | Multipart upload session ID | -| **parts** | `Object[]` | ✅ | Ordered list of uploaded parts for assembly | +| **parts** | `{ chunkIndex: integer; eTag: string }[]` | ✅ | Ordered list of uploaded parts for assembly | --- @@ -48,9 +48,9 @@ const result = CompleteChunkedUploadRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ fileId: string; key: string; size: integer; mimeType: string; … }` | ✅ | | --- @@ -89,9 +89,9 @@ const result = CompleteChunkedUploadRequest.parse(data); | 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` | ✅ | Uploaded file metadata | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ path: string; name: string; size: integer; mimeType: string; … }` | ✅ | Uploaded file metadata | --- @@ -135,9 +135,9 @@ const result = CompleteChunkedUploadRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ uploadId: string; resumeToken: string; fileId: string; totalChunks: integer; … }` | ✅ | | --- @@ -149,9 +149,9 @@ const result = CompleteChunkedUploadRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ uploadUrl: string; downloadUrl?: string; fileId: string; method: Enum<'PUT' \| 'POST'>; … }` | ✅ | | --- @@ -176,9 +176,9 @@ const result = CompleteChunkedUploadRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ chunkIndex: integer; eTag: string; bytesReceived: integer }` | ✅ | | --- @@ -190,9 +190,9 @@ const result = CompleteChunkedUploadRequest.parse(data); | 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` | ✅ | | +| **error** | `{ code: string; message: string; category?: string; details?: any; … }` | optional | Error details if success is false | +| **meta** | `{ timestamp: string; duration?: number; requestId?: string; traceId?: string }` | optional | Response metadata | +| **data** | `{ uploadId: string; fileId: string; filename: string; totalSize: integer; … }` | ✅ | | --- diff --git a/content/docs/references/api/versioning.mdx b/content/docs/references/api/versioning.mdx index c380786c40..d0ecfcc888 100644 --- a/content/docs/references/api/versioning.mdx +++ b/content/docs/references/api/versioning.mdx @@ -68,7 +68,7 @@ const result = VersionDefinition.parse(data); | **resolved** | `string` | ✅ | Resolved API version for this request | | **supported** | `string[]` | ✅ | All supported version identifiers | | **deprecated** | `string[]` | optional | Deprecated version identifiers | -| **versions** | `Object[]` | optional | Full version definitions with lifecycle metadata | +| **versions** | `{ version: string; status: Enum<'preview' \| 'current' \| 'supported' \| 'deprecated' \| 'retired'>; releasedAt: string; deprecatedAt?: string; … }[]` | optional | Full version definitions with lifecycle metadata | --- diff --git a/content/docs/references/api/websocket.mdx b/content/docs/references/api/websocket.mdx index 1ad71725c0..3775e75a4b 100644 --- a/content/docs/references/api/websocket.mdx +++ b/content/docs/references/api/websocket.mdx @@ -36,7 +36,7 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'ack'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **ackMessageId** | `string` | ✅ | ID of the message being acknowledged | | **success** | `boolean` | ✅ | Whether the operation was successful | @@ -52,9 +52,9 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'cursor'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **cursor** | `Object` | ✅ | Cursor position | +| **cursor** | `{ userId: string; sessionId: string; documentId: string; position?: object; … }` | ✅ | Cursor position | --- @@ -68,8 +68,8 @@ const result = AckMessage.parse(data); | **userId** | `string` | ✅ | User identifier | | **sessionId** | `string` | ✅ | Session identifier | | **documentId** | `string` | ✅ | Document identifier being edited | -| **position** | `Object` | optional | Cursor position in document | -| **selection** | `Object` | optional | Selection range (if text is selected) | +| **position** | `{ line: integer; column: integer }` | optional | Cursor position in document | +| **selection** | `{ start: object; end: object }` | optional | Selection range (if text is selected) | | **color** | `string` | optional | Cursor color for visual representation | | **userName** | `string` | optional | Display name of user | | **lastUpdate** | `string` | ✅ | ISO 8601 datetime of last cursor update | @@ -100,9 +100,9 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'edit'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **operation** | `Object` | ✅ | Edit operation | +| **operation** | `{ operationId: string; documentId: string; userId: string; sessionId: string; … }` | ✅ | Edit operation | --- @@ -118,8 +118,8 @@ const result = AckMessage.parse(data); | **userId** | `string` | ✅ | User who performed the edit | | **sessionId** | `string` | ✅ | Session identifier | | **type** | `Enum<'insert' \| 'delete' \| 'replace'>` | ✅ | Type of edit operation | -| **position** | `Object` | ✅ | Starting position of the operation | -| **endPosition** | `Object` | optional | Ending position (for delete/replace operations) | +| **position** | `{ line: integer; column: integer }` | ✅ | Starting position of the operation | +| **endPosition** | `{ line: integer; column: integer }` | optional | Ending position (for delete/replace operations) | | **content** | `string` | optional | Content to insert/replace | | **version** | `integer` | ✅ | Document version before this operation | | **timestamp** | `string` | ✅ | ISO 8601 datetime when operation was created | @@ -146,7 +146,7 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'error'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **code** | `string` | ✅ | Error code | | **message** | `string` | ✅ | Error message | @@ -161,10 +161,10 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **conditions** | `Object[]` | optional | Array of filter conditions | -| **and** | `[#](./#)[]` | optional | AND logical combination of filters | -| **or** | `[#](./#)[]` | optional | OR logical combination of filters | -| **not** | `[#](./#)` | optional | NOT logical negation of filter | +| **conditions** | `{ field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'exists' \| 'regex'>; value?: any }[]` | optional | Array of filter conditions | +| **and** | `[EventFilter](#eventfilter)[]` | optional | AND logical combination of filters | +| **or** | `[EventFilter](#eventfilter)[]` | optional | OR logical combination of filters | +| **not** | `[EventFilter](#eventfilter)` | optional | NOT logical negation of filter | --- @@ -189,7 +189,7 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'event'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **subscriptionId** | `string` | ✅ | Subscription ID this event belongs to | | **eventName** | `string` | ✅ | Event name | @@ -212,7 +212,7 @@ const result = AckMessage.parse(data); | **subscriptionId** | `string` | ✅ | Unique subscription identifier | | **events** | `string[]` | ✅ | Event patterns to subscribe to (supports wildcards, e.g., "record.*", "user.created") | | **objects** | `string[]` | optional | Object names to filter events by (e.g., ["account", "contact"]) | -| **filters** | `[__schema0](./__schema0)` | optional | Advanced filter conditions for event payloads | +| **filters** | `{ conditions?: { field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'exists' \| 'regex'>; value?: any }[]; and?: object[]; or?: object[]; not?: object }` | optional | Advanced filter conditions for event payloads | | **channels** | `string[]` | optional | Channel names for scoped subscriptions | @@ -246,7 +246,7 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'ping'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | @@ -259,7 +259,7 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'pong'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **pingMessageId** | `string` | optional | ID of ping message being responded to | @@ -273,9 +273,9 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'presence'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **presence** | `Object` | ✅ | Presence state | +| **presence** | `{ userId: string; sessionId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; … }` | ✅ | Presence state | --- @@ -322,7 +322,7 @@ const result = AckMessage.parse(data); | **recordId** | `string` | ✅ | Record identifier being edited | | **fieldName** | `string` | ✅ | Field name being edited | | **position** | `number` | ✅ | Cursor position (character offset from start) | -| **selection** | `Object` | optional | Text selection range (if text is selected) | +| **selection** | `{ start: number; end: number }` | optional | Text selection range (if text is selected) | --- @@ -349,9 +349,9 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'subscribe'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscription** | `Object` | ✅ | Subscription configuration | +| **subscription** | `{ subscriptionId: string; events: string[]; objects?: string[]; filters?: { conditions?: { field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'exists' \| 'regex'>; value?: any }[]; and?: object[]; or?: object[]; not?: object }; … }` | ✅ | Subscription configuration | --- @@ -363,9 +363,9 @@ const result = AckMessage.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'unsubscribe'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **request** | `Object` | ✅ | Unsubscribe request | +| **request** | `{ subscriptionId: string }` | ✅ | Unsubscribe request | --- @@ -428,9 +428,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'subscribe'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscription** | `Object` | ✅ | Subscription configuration | +| **subscription** | `{ subscriptionId: string; events: string[]; objects?: string[]; filters?: { conditions?: { field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'exists' \| 'regex'>; value?: any }[]; and?: object[]; or?: object[]; not?: object }; … }` | ✅ | Subscription configuration | --- @@ -443,9 +443,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'unsubscribe'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **request** | `Object` | ✅ | Unsubscribe request | +| **request** | `{ subscriptionId: string }` | ✅ | Unsubscribe request | --- @@ -458,7 +458,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'event'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **subscriptionId** | `string` | ✅ | Subscription ID this event belongs to | | **eventName** | `string` | ✅ | Event name | @@ -477,9 +477,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'presence'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **presence** | `Object` | ✅ | Presence state | +| **presence** | `{ userId: string; sessionId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; … }` | ✅ | Presence state | --- @@ -492,9 +492,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'cursor'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **cursor** | `Object` | ✅ | Cursor position | +| **cursor** | `{ userId: string; sessionId: string; documentId: string; position?: object; … }` | ✅ | Cursor position | --- @@ -507,9 +507,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'edit'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **operation** | `Object` | ✅ | Edit operation | +| **operation** | `{ operationId: string; documentId: string; userId: string; sessionId: string; … }` | ✅ | Edit operation | --- @@ -522,7 +522,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'ack'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **ackMessageId** | `string` | ✅ | ID of the message being acknowledged | | **success** | `boolean` | ✅ | Whether the operation was successful | @@ -539,7 +539,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'error'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **code** | `string` | ✅ | Error code | | **message** | `string` | ✅ | Error message | @@ -556,7 +556,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'ping'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | --- @@ -570,7 +570,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | +| **type** | `'pong'` | ✅ | | | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | | **pingMessageId** | `string` | optional | ID of ping message being responded to | diff --git a/content/docs/references/automation/approval.mdx b/content/docs/references/automation/approval.mdx index 540685e9d6..d462d20272 100644 --- a/content/docs/references/automation/approval.mdx +++ b/content/docs/references/automation/approval.mdx @@ -66,11 +66,11 @@ const result = ApprovalDecision.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **approvers** | `Object[]` | ✅ | Allowed approvers for this node | +| **approvers** | `{ type: Enum<'user' \| 'role' \| 'position' \| 'team' \| 'department' \| 'manager' \| 'field' \| 'queue'>; value?: string }[]` | ✅ | Allowed approvers for this node | | **behavior** | `Enum<'first_response' \| 'unanimous'>` | ✅ | How to combine multiple approvers | | **lockRecord** | `boolean` | ✅ | Lock the record from editing while pending | | **approvalStatusField** | `string` | optional | Business-object field to mirror request status onto | -| **escalation** | `Object` | optional | Per-node SLA escalation | +| **escalation** | `{ enabled: boolean; timeoutHours: number; action: Enum<'reassign' \| 'auto_approve' \| 'auto_reject' \| 'notify'>; escalateTo?: string; … }` | optional | Per-node SLA escalation | | **maxRevisions** | `integer` | ✅ | Max send-backs for revision before auto-reject (0 = send-back disabled) | diff --git a/content/docs/references/automation/bpmn-interop.mdx b/content/docs/references/automation/bpmn-interop.mdx index 31fe954a61..435cdb55a0 100644 --- a/content/docs/references/automation/bpmn-interop.mdx +++ b/content/docs/references/automation/bpmn-interop.mdx @@ -76,7 +76,7 @@ Options for exporting an ObjectStack flow as BPMN 2.0 XML | **version** | `Enum<'2.0' \| '2.0.2'>` | ✅ | Target BPMN specification version | | **includeLayout** | `boolean` | ✅ | Include BPMN DI layout data from canvas positions | | **includeExtensions** | `boolean` | ✅ | Include ObjectStack extensions in BPMN extensionElements | -| **customMappings** | `Object[]` | optional | Custom element mappings for export | +| **customMappings** | `{ bpmnType: string; flowNodeAction: string; bidirectional: boolean; notes?: string }[]` | optional | Custom element mappings for export | | **prettyPrint** | `boolean` | ✅ | Pretty-print XML output with indentation | | **namespacePrefix** | `string` | ✅ | XML namespace prefix for BPMN elements | @@ -92,7 +92,7 @@ Options for importing BPMN 2.0 XML into an ObjectStack flow | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **unmappedStrategy** | `Enum<'skip' \| 'warn' \| 'error' \| 'comment'>` | ✅ | How to handle unmapped BPMN elements | -| **customMappings** | `Object[]` | optional | Custom element mappings to override or extend defaults | +| **customMappings** | `{ bpmnType: string; flowNodeAction: string; bidirectional: boolean; notes?: string }[]` | optional | Custom element mappings to override or extend defaults | | **importLayout** | `boolean` | ✅ | Import BPMN DI layout positions into canvas node coordinates | | **importDocumentation** | `boolean` | ✅ | Import BPMN documentation elements as node descriptions | | **flowName** | `string` | optional | Override flow name (defaults to BPMN process name) | @@ -110,7 +110,7 @@ Result of a BPMN import/export operation | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Whether the operation completed successfully | -| **diagnostics** | `Object[]` | ✅ | Diagnostic messages from the operation | +| **diagnostics** | `{ severity: Enum<'info' \| 'warning' \| 'error'>; message: string; bpmnElementId?: string; nodeId?: string }[]` | ✅ | Diagnostic messages from the operation | | **mappedCount** | `integer` | ✅ | Number of elements successfully mapped | | **unmappedCount** | `integer` | ✅ | Number of elements that could not be mapped | diff --git a/content/docs/references/automation/connector.mdx b/content/docs/references/automation/connector.mdx index 2a1a7c6c09..6e489b005a 100644 --- a/content/docs/references/automation/connector.mdx +++ b/content/docs/references/automation/connector.mdx @@ -34,10 +34,10 @@ const result = Connector.parse(data); | **icon** | `string` | optional | Connector icon | | **category** | `Enum<'crm' \| 'payment' \| 'communication' \| 'storage' \| 'analytics' \| 'database' \| 'marketing' \| 'accounting' \| 'hr' \| 'productivity' \| 'ecommerce' \| 'support' \| 'devtools' \| 'social' \| 'other'>` | ✅ | Connector category | | **baseUrl** | `string` | optional | API base URL | -| **authentication** | `Object` | ✅ | Authentication config | -| **operations** | `Object[]` | optional | Connector operations | -| **triggers** | `Object[]` | optional | Connector triggers | -| **rateLimit** | `Object` | optional | Rate limiting | +| **authentication** | `{ type: Enum<'none' \| 'apiKey' \| 'basic' \| 'bearer' \| 'oauth1' \| 'oauth2' \| 'custom'>; fields?: { name: string; label: string; type: Enum<'text' \| 'password' \| 'url' \| 'select'>; description?: string; … }[]; oauth2?: object; test?: object }` | ✅ | Authentication config | +| **operations** | `{ id: string; name: string; description?: string; type: Enum<'read' \| 'write' \| 'delete' \| 'search' \| 'trigger' \| 'action'>; … }[]` | optional | Connector operations | +| **triggers** | `{ id: string; name: string; description?: string; type: Enum<'webhook' \| 'polling' \| 'stream'>; … }[]` | optional | Connector triggers | +| **rateLimit** | `{ requestsPerSecond?: number; requestsPerMinute?: number; requestsPerHour?: number }` | optional | Rate limiting | | **author** | `string` | optional | Connector author | | **documentation** | `string` | optional | Documentation URL | | **homepage** | `string` | optional | Homepage URL | @@ -75,20 +75,20 @@ const result = Connector.parse(data); | **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 | +| **source** | `{ object?: string; filters?: any; fields?: string[]; connectorInstanceId?: string; … }` | ✅ | Data source | +| **destination** | `{ object?: string; connectorInstanceId?: string; operation: Enum<'insert' \| 'update' \| 'upsert' \| 'delete' \| 'sync'>; mapping?: Record \| { source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any }[]; … }` | ✅ | 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 | +| **schedule** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **retry** | `{ maxAttempts?: integer; backoffMs?: integer }` | optional | Retry configuration | +| **validation** | `{ required?: string[]; unique?: string[]; custom?: { name: string; condition: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; message: string }[] }` | optional | Validation rules | +| **errorHandling** | `{ onValidationError?: Enum<'skip' \| 'fail' \| 'log'>; onSyncError?: Enum<'skip' \| 'fail' \| 'retry'>; notifyOnError?: string[] }` | optional | Error handling | +| **optimization** | `{ parallelBatches?: boolean; cacheEnabled?: boolean; compressionEnabled?: boolean }` | optional | Performance optimization | +| **audit** | `{ logLevel?: Enum<'none' \| 'error' \| 'warn' \| 'info' \| 'debug'>; retainLogsForDays?: integer; trackChanges?: boolean }` | 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 index 497ad61cbb..d827234e01 100644 --- a/content/docs/references/automation/control-flow.mdx +++ b/content/docs/references/automation/control-flow.mdx @@ -33,7 +33,7 @@ marker; the body is the edges *between* them in the main graph), or We adopt **(B)**. Each container holds its body as a self-contained -[FlowRegionSchema](FlowRegionSchema) (`config.body` for `loop`, `config.branches[]` for +`FlowRegionSchema` (`config.body` for `loop`, `config.branches[]` for `parallel`, `config.try`/`config.catch` for `try_catch`). The reasons: @@ -63,11 +63,11 @@ 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`, +The canonical construct type ids are `LOOP_NODE_TYPE` (`loop`, -pre-existing), [PARALLEL_NODE_TYPE](PARALLEL_NODE_TYPE) (`parallel`), and +pre-existing), `PARALLEL_NODE_TYPE` (`parallel`), and -[TRY_CATCH_NODE_TYPE](TRY_CATCH_NODE_TYPE) (`try_catch`). These are distinct from the BPMN +`TRY_CATCH_NODE_TYPE` (`try_catch`). These are distinct from the BPMN interop node types (`parallel_gateway` / `join_gateway` / `boundary_event`), @@ -95,8 +95,8 @@ const result = FlowRegion.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **nodes** | `Object[]` | ✅ | Region body nodes (single-entry/single-exit sub-graph) | -| **edges** | `Object[]` | optional | Region body edges | +| **nodes** | `{ id: string; type: string; label: string; config?: Record; … }[]` | ✅ | Region body nodes (single-entry/single-exit sub-graph) | +| **edges** | `{ id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; … }[]` | optional | Region body edges | --- @@ -111,7 +111,7 @@ const result = FlowRegion.parse(data); | **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) | +| **body** | `{ nodes: { id: string; type: string; label: string; config?: Record; … }[]; edges?: { id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; … }[] }` | optional | Loop body region (omit for legacy flat-graph loops) | --- @@ -123,8 +123,8 @@ const result = FlowRegion.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **name** | `string` | optional | Branch label | -| **nodes** | `Object[]` | ✅ | Branch body nodes | -| **edges** | `Object[]` | optional | Branch body edges | +| **nodes** | `{ id: string; type: string; label: string; config?: Record; … }[]` | ✅ | Branch body nodes | +| **edges** | `{ id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; … }[]` | optional | Branch body edges | --- @@ -135,7 +135,7 @@ const result = FlowRegion.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **branches** | `Object[]` | ✅ | Branch regions executed concurrently; implicit join at block end | +| **branches** | `{ name?: string; nodes: { id: string; type: string; label: string; config?: Record; … }[]; edges?: { id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; … }[] }[]` | ✅ | Branch regions executed concurrently; implicit join at block end | --- @@ -146,10 +146,10 @@ const result = FlowRegion.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **try** | `Object` | ✅ | Protected region | -| **catch** | `Object` | optional | Handler region run when the try region fails | +| **try** | `{ nodes: { id: string; type: string; label: string; config?: Record; … }[]; edges?: { id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; … }[] }` | ✅ | Protected region | +| **catch** | `{ nodes: { id: string; type: string; label: string; config?: Record; … }[]; edges?: { id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **retry** | `{ maxRetries?: integer; retryDelayMs?: integer; backoffMultiplier?: number; maxRetryDelayMs?: integer; … }` | 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 fc67127810..b5338c91e3 100644 --- a/content/docs/references/automation/etl.mdx +++ b/content/docs/references/automation/etl.mdx @@ -51,11 +51,11 @@ Supports complex operations: joins, aggregations, filtering, custom SQL. **When to upgrade:** -- Need full connector lifecycle (auth, webhooks, rate limits) → Use [Enterprise Connector](../integration/connector.zod.ts) +- Need full connector lifecycle (auth, webhooks, rate limits) → Use [Enterprise Connector](/docs/references/integration/connector) -@see [./sync.zod.ts](./sync.zod.ts) for Level 1 (simple sync) +See also: `./sync.zod.ts` for Level 1 (simple sync) -@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration) +See also: [../[integration/connector.zod.ts](/docs/references/integration/connector)](/docs/references/integration/connector) for Level 3 (enterprise integration) ## Use Cases @@ -83,11 +83,11 @@ Supports complex operations: joins, aggregations, filtering, custom SQL. - Split monolithic databases into microservices -@see https://airbyte.com/ +See also: https://airbyte.com/ -@see https://docs.fivetran.com/ +See also: https://docs.fivetran.com/ -@see https://nifi.apache.org/ +See also: https://nifi.apache.org/ @example @@ -187,14 +187,14 @@ const result = ETLDestination.parse(data); | **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 | +| **source** | `{ type: Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>; connector?: string; config: Record; incremental?: object }` | ✅ | Data source | +| **destination** | `{ type: Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>; connector?: string; config: Record; writeMode?: Enum<'append' \| 'overwrite' \| 'upsert' \| 'merge'>; … }` | ✅ | Data destination | +| **transformations** | `{ name?: string; type: Enum<'map' \| 'filter' \| 'aggregate' \| 'join' \| 'script' \| 'lookup' \| 'split' \| 'merge' \| 'normalize' \| 'deduplicate'>; config: Record; continueOnError?: boolean }[]` | optional | Transformation pipeline | | **syncMode** | `Enum<'full' \| 'incremental' \| 'cdc'>` | optional | Sync mode | -| **schedule** | `string \| Object` | optional | Cron schedule expression | +| **schedule** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Cron schedule expression | | **enabled** | `boolean` | optional | Pipeline enabled status | -| **retry** | `Object` | optional | Retry configuration | -| **notifications** | `Object` | optional | Notification settings | +| **retry** | `{ maxAttempts?: integer; backoffMs?: integer }` | optional | Retry configuration | +| **notifications** | `{ onSuccess?: string[]; onFailure?: string[] }` | optional | Notification settings | | **tags** | `string[]` | optional | Pipeline tags | | **metadata** | `Record` | optional | Custom metadata | @@ -213,8 +213,8 @@ const result = ETLDestination.parse(data); | **startedAt** | `string` | ✅ | Start time | | **completedAt** | `string` | optional | Completion time | | **durationMs** | `number` | optional | Duration in ms | -| **stats** | `Object` | optional | Run statistics | -| **error** | `Object` | optional | Error information | +| **stats** | `{ recordsRead: integer; recordsWritten: integer; recordsErrored: integer; bytesProcessed: integer }` | optional | Run statistics | +| **error** | `{ message: string; code?: string; details?: any }` | optional | Error information | | **logs** | `string[]` | optional | Execution logs | @@ -243,7 +243,7 @@ const result = ETLDestination.parse(data); | **type** | `Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>` | ✅ | Source type | | **connector** | `string` | optional | Connector ID | | **config** | `Record` | ✅ | Source configuration | -| **incremental** | `Object` | optional | Incremental extraction config | +| **incremental** | `{ enabled: boolean; cursorField: string; cursorValue?: any }` | optional | Incremental extraction config | --- diff --git a/content/docs/references/automation/execution.mdx b/content/docs/references/automation/execution.mdx index 01fba062b0..4a42191dde 100644 --- a/content/docs/references/automation/execution.mdx +++ b/content/docs/references/automation/execution.mdx @@ -106,8 +106,8 @@ const result = Checkpoint.parse(data); | **flowName** | `string` | ✅ | Machine name of the executed flow | | **flowVersion** | `integer` | optional | Version of the flow that was executed | | **status** | `Enum<'pending' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'cancelled' \| 'timed_out' \| 'retrying'>` | ✅ | Current execution status | -| **trigger** | `Object` | ✅ | What triggered this execution | -| **steps** | `Object[]` | ✅ | Ordered list of executed steps | +| **trigger** | `{ type: string; recordId?: string; object?: string; userId?: string; … }` | ✅ | What triggered this execution | +| **steps** | `{ nodeId: string; nodeType: string; nodeLabel?: string; status: Enum<'success' \| 'failure' \| 'skipped'>; … }[]` | ✅ | Ordered list of executed steps | | **variables** | `Record` | optional | Final state of flow variables | | **startedAt** | `string` | ✅ | Execution start timestamp | | **completedAt** | `string` | optional | Execution completion timestamp | @@ -149,7 +149,7 @@ const result = Checkpoint.parse(data); | **durationMs** | `integer` | optional | Step execution duration in milliseconds | | **input** | `Record` | optional | Input data passed to the node | | **output** | `Record` | optional | Output data produced by the node | -| **error** | `Object` | optional | Error details if step failed | +| **error** | `{ code: string; message: string; stack?: string }` | optional | Error details if step failed | | **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 | @@ -166,7 +166,7 @@ const result = Checkpoint.parse(data); | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Schedule instance ID | | **flowName** | `string` | ✅ | Flow machine name | -| **cronExpression** | `string \| Object` | ✅ | Cron expression — cron`0 9 * * MON-FRI` | +| **cronExpression** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx index 52ae1fec90..3e163f3884 100644 --- a/content/docs/references/automation/flow.mdx +++ b/content/docs/references/automation/flow.mdx @@ -54,13 +54,13 @@ const result = Flow.parse(data); | **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 | +| **variables** | `{ name: string; type: string; isInput?: boolean; isOutput?: boolean }[]` | optional | Flow variables | +| **nodes** | `{ id: string; type: string; label: string; config?: Record; … }[]` | ✅ | Flow nodes | +| **edges** | `{ id: string; source: string; target: string; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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. | +| **errorHandling** | `{ strategy?: Enum<'fail' \| 'retry' \| 'continue'>; maxRetries?: integer; retryDelayMs?: integer; backoffMultiplier?: number; … }` | optional | Flow-level error handling configuration | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -81,7 +81,7 @@ const result = Flow.parse(data); | **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. | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -99,13 +99,13 @@ const result = Flow.parse(data); | **type** | `string` | ✅ | Action type — a built-in FlowNodeAction id or a plugin-registered node type. Validated against the live action registry at registerFlow() (ADR-0018), not by a closed enum. | | **label** | `string` | ✅ | Node label | | **config** | `Record` | optional | Node configuration | -| **connectorConfig** | `Object` | optional | | -| **position** | `Object` | optional | | +| **connectorConfig** | `{ connectorId: string; actionId: string; input: Record }` | optional | | +| **position** | `{ x: number; y: number }` | optional | | | **timeoutMs** | `integer` | optional | Maximum execution time for this node in milliseconds | -| **inputSchema** | `Record` | optional | Input parameter schema for this node | -| **outputSchema** | `Record` | optional | Output schema declaration for this node | -| **waitEventConfig** | `Object` | optional | Configuration for wait node event resumption | -| **boundaryConfig** | `Object` | optional | Configuration for boundary events attached to host nodes | +| **inputSchema** | `Record; required: boolean; description?: string }>` | optional | Input parameter schema for this node | +| **outputSchema** | `Record; description?: string }>` | optional | Output schema declaration for this node | +| **waitEventConfig** | `{ eventType: Enum<'timer' \| 'signal' \| 'webhook' \| 'manual' \| 'condition'>; timerDuration?: string; signalName?: string; timeoutMs?: integer; … }` | optional | Configuration for wait node event resumption | +| **boundaryConfig** | `{ attachedToNodeId: string; eventType: Enum<'error' \| 'timer' \| 'signal' \| 'cancel'>; interrupting: boolean; errorCode?: string; … }` | optional | Configuration for boundary events attached to host nodes | --- @@ -160,7 +160,7 @@ const result = Flow.parse(data); | :--- | :--- | :--- | :--- | | **flowName** | `string` | ✅ | Flow machine name | | **version** | `integer` | ✅ | Version number | -| **definition** | `Object` | ✅ | Complete flow definition snapshot | +| **definition** | `{ name: string; label: string; description?: string; successMessage?: string; … }` | ✅ | 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/state-machine.mdx b/content/docs/references/automation/state-machine.mdx index 264d16daae..6ecf8900b4 100644 --- a/content/docs/references/automation/state-machine.mdx +++ b/content/docs/references/automation/state-machine.mdx @@ -105,8 +105,8 @@ Type: `string` | **description** | `string` | optional | | | **contextSchema** | `Record` | optional | Zod Schema for the machine context/memory | | **initial** | `string` | ✅ | Initial State ID | -| **states** | `Record` | ✅ | State Nodes | -| **on** | `Record` | optional | | +| **states** | `Record; entry?: string \| { type: string; params?: Record }[]; exit?: string \| { type: string; params?: Record }[]; on?: Record }; actions?: string \| { type: string; params?: Record }[]; description?: string } \| { target?: string; cond?: string \| { type: string; params?: Record }; actions?: string \| { type: string; params?: Record }[]; description?: string }[]>; … }>` | ✅ | State Nodes | +| **on** | `Record }; actions?: string \| { type: string; params?: Record }[]; description?: string } \| { target?: string; cond?: string \| { type: string; params?: Record }; actions?: string \| { type: string; params?: Record }[]; description?: string }[]>` | optional | | --- @@ -118,13 +118,13 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **type** | `Enum<'atomic' \| 'compound' \| 'parallel' \| 'final' \| 'history'>` | ✅ | | -| **entry** | `string \| Object[]` | optional | Actions to run when entering this state | -| **exit** | `string \| Object[]` | optional | Actions to run when leaving this state | -| **on** | `Record` | optional | Map of Event Type -> Transition Definition | -| **always** | `Object[]` | optional | | +| **entry** | `string \| { type: string; params?: Record }[]` | optional | Actions to run when entering this state | +| **exit** | `string \| { type: string; params?: Record }[]` | optional | Actions to run when leaving this state | +| **on** | `Record }; actions?: string \| { type: string; params?: Record }[]; description?: string } \| { target?: string; cond?: string \| { type: string; params?: Record }; actions?: string \| { type: string; params?: Record }[]; description?: string }[]>` | optional | Map of Event Type -> Transition Definition | +| **always** | `{ target?: string; cond?: string \| { type: string; params?: Record }; actions?: string \| { type: string; params?: Record }[]; description?: string }[]` | optional | | | **initial** | `string` | optional | Initial child state (if compound) | -| **states** | `Record` | optional | | -| **meta** | `Object` | optional | | +| **states** | `Record` | optional | | +| **meta** | `{ label?: string; description?: string; color?: string; aiInstructions?: string }` | optional | | --- @@ -136,8 +136,8 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **target** | `string` | optional | Target State ID | -| **cond** | `string \| Object` | optional | Condition (Guard) required to take this path | -| **actions** | `string \| Object[]` | optional | Actions to execute during transition | +| **cond** | `string \| { type: string; params?: Record }` | optional | Condition (Guard) required to take this path | +| **actions** | `string \| { type: string; params?: Record }[]` | optional | Actions to execute during transition | | **description** | `string` | optional | Human readable description of this rule | diff --git a/content/docs/references/automation/sync.mdx b/content/docs/references/automation/sync.mdx index 0d703ad020..0a24ffd467 100644 --- a/content/docs/references/automation/sync.mdx +++ b/content/docs/references/automation/sync.mdx @@ -51,13 +51,13 @@ For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (L - Need multi-source joins → Use [ETL Pipeline](./etl.zod.ts) -- Need complex authentication/webhooks → Use [Enterprise Connector](../integration/connector.zod.ts) +- Need complex authentication/webhooks → Use [Enterprise Connector](/docs/references/integration/connector) - Need aggregations or data warehousing → Use [ETL Pipeline](./etl.zod.ts) -@see [./etl.zod.ts](./etl.zod.ts) for Level 2 (data engineering) +See also: `./etl.zod.ts` for Level 2 (data engineering) -@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration) +See also: [../[integration/connector.zod.ts](/docs/references/integration/connector)](/docs/references/integration/connector) for Level 3 (enterprise integration) ## Use Cases @@ -85,11 +85,11 @@ For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (L - Business intelligence -@see https://help.salesforce.com/s/articleView?id=sf.platform_connect_about.htm +See also: https://help.salesforce.com/s/articleView?id=sf.platform_connect_about.htm -@see https://segment.com/docs/connections/sync/ +See also: https://segment.com/docs/connections/sync/ -@see https://www.getcensus.com/ +See also: https://www.getcensus.com/ @example @@ -160,7 +160,7 @@ const result = DataDestinationConfig.parse(data); | **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 | +| **mapping** | `Record \| { source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any }[]` | optional | Field mappings | | **externalResource** | `string` | optional | External resource ID | | **matchKey** | `string[]` | optional | Match key fields | @@ -205,8 +205,8 @@ const result = DataDestinationConfig.parse(data); | **startedAt** | `string` | ✅ | Start time | | **completedAt** | `string` | optional | Completion time | | **durationMs** | `number` | optional | Duration in ms | -| **stats** | `Object` | optional | Execution statistics | -| **errors** | `Object[]` | optional | Errors | +| **stats** | `{ recordsProcessed: integer; recordsInserted: integer; recordsUpdated: integer; recordsDeleted: integer; … }` | optional | Execution statistics | +| **errors** | `{ recordId?: string; field?: string; message: string; code?: string }[]` | optional | Errors | | **logs** | `string[]` | optional | Execution logs | diff --git a/content/docs/references/automation/trigger-registry.mdx b/content/docs/references/automation/trigger-registry.mdx index 07d8c539f1..f8230c8d24 100644 --- a/content/docs/references/automation/trigger-registry.mdx +++ b/content/docs/references/automation/trigger-registry.mdx @@ -13,7 +13,7 @@ Inspired by Zapier, n8n, and Workato connector architectures. ## When to use Trigger Registry vs. Integration Connector? -**Use `automation/trigger-registry.zod.ts` when:** +**Use `[automation/trigger-registry.zod.ts](/docs/references/automation/trigger-registry)` when:** - Building simple automation triggers (e.g., "when Slack message received, create task") @@ -25,7 +25,7 @@ Inspired by Zapier, n8n, and Workato connector architectures. - Webhook-based or polling triggers for automation workflows -**Use `integration/connector.zod.ts` when:** +**Use `[integration/connector.zod.ts](/docs/references/integration/connector)` when:** - Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) @@ -63,11 +63,11 @@ Inspired by Zapier, n8n, and Workato connector architectures. - Simple API calls to third-party services -@see https://zapier.com/developer/documentation/v2/ +See also: https://zapier.com/developer/documentation/v2/ -@see https://docs.n8n.io/integrations/creating-nodes/ +See also: https://docs.n8n.io/integrations/creating-nodes/ -@see ../../integration/connector.zod.ts for enterprise connectors +See also: ../../[integration/connector.zod.ts](/docs/references/integration/connector) for enterprise connectors @example @@ -127,7 +127,7 @@ const result = AuthField.parse(data); | **description** | `string` | optional | Field description | | **required** | `boolean` | ✅ | Required field | | **default** | `string` | optional | Default value | -| **options** | `Object[]` | optional | Select field options | +| **options** | `{ label: string; value: string }[]` | optional | Select field options | | **placeholder** | `string` | optional | Placeholder text | @@ -140,9 +140,9 @@ const result = AuthField.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **type** | `Enum<'none' \| 'apiKey' \| 'basic' \| 'bearer' \| 'oauth1' \| 'oauth2' \| 'custom'>` | ✅ | Authentication type | -| **fields** | `Object[]` | optional | Authentication fields | -| **oauth2** | `Object` | optional | OAuth 2.0 configuration | -| **test** | `Object` | optional | Authentication test configuration | +| **fields** | `{ name: string; label: string; type: Enum<'text' \| 'password' \| 'url' \| 'select'>; description?: string; … }[]` | optional | Authentication fields | +| **oauth2** | `{ authorizationUrl: string; tokenUrl: string; scopes?: string[]; clientIdField: string; … }` | optional | OAuth 2.0 configuration | +| **test** | `{ url?: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE'> }` | optional | Authentication test configuration | --- @@ -215,7 +215,7 @@ const result = AuthField.parse(data); | **name** | `string` | ✅ | Operation name | | **description** | `string` | optional | Operation description | | **type** | `Enum<'read' \| 'write' \| 'delete' \| 'search' \| 'trigger' \| 'action'>` | ✅ | Operation type | -| **inputSchema** | `Object[]` | optional | Input parameters | +| **inputSchema** | `{ name: string; label: string; description?: string; type: Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'date' \| 'file'>; … }[]` | optional | Input parameters | | **outputSchema** | `Record` | optional | Output schema | | **sampleOutput** | `any` | optional | Sample output | | **supportsPagination** | `boolean` | ✅ | Supports pagination | diff --git a/content/docs/references/automation/webhook.mdx b/content/docs/references/automation/webhook.mdx index da84d21f92..385e53cade 100644 --- a/content/docs/references/automation/webhook.mdx +++ b/content/docs/references/automation/webhook.mdx @@ -41,8 +41,8 @@ const result = Webhook.parse(data); | **body** | `any` | optional | Request body payload (if not using default record data) | | **payloadFields** | `string[]` | optional | Fields to include. Empty = All | | **includeSession** | `boolean` | ✅ | Include user session info | -| **authentication** | `Object` | optional | Authentication configuration | -| **retryPolicy** | `Object` | optional | Retry policy configuration | +| **authentication** | `{ type: Enum<'none' \| 'bearer' \| 'basic' \| 'api-key'>; credentials?: Record }` | optional | Authentication configuration | +| **retryPolicy** | `{ maxRetries: integer; backoffStrategy: Enum<'exponential' \| 'linear' \| 'fixed'>; initialDelayMs: integer; maxDelayMs: integer }` | optional | Retry policy configuration | | **timeoutMs** | `integer` | ✅ | Request timeout in milliseconds | | **secret** | `string` | optional | Signing secret for HMAC signature verification | | **isActive** | `boolean` | ✅ | Whether webhook is active | @@ -61,7 +61,7 @@ const result = Webhook.parse(data); | **name** | `string` | ✅ | Webhook receiver unique name (lowercase snake_case) | | **path** | `string` | ✅ | URL Path (e.g. /webhooks/stripe) | | **verificationType** | `Enum<'none' \| 'header_token' \| 'hmac' \| 'ip_whitelist'>` | ✅ | | -| **verificationParams** | `Object` | optional | | +| **verificationParams** | `{ header?: string; secret?: string; ips?: string[] }` | optional | | | **action** | `Enum<'trigger_flow' \| 'script' \| 'upsert_record'>` | ✅ | | | **target** | `string` | ✅ | Flow ID or Script name | diff --git a/content/docs/references/cloud/app-store.mdx b/content/docs/references/cloud/app-store.mdx index 0077cbc064..2e60ecb9c5 100644 --- a/content/docs/references/cloud/app-store.mdx +++ b/content/docs/references/cloud/app-store.mdx @@ -73,11 +73,11 @@ const result = AppDiscoveryRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **featured** | `Object[]` | optional | | -| **recommended** | `Object[]` | optional | | -| **trending** | `Object[]` | optional | | -| **newArrivals** | `Object[]` | optional | | -| **collections** | `Object[]` | optional | | +| **featured** | `{ listingId: string; name: string; tagline?: string; iconUrl?: string; … }[]` | optional | | +| **recommended** | `{ listingId: string; name: string; tagline?: string; iconUrl?: string; … }[]` | optional | | +| **trending** | `{ listingId: string; name: string; tagline?: string; iconUrl?: string; … }[]` | optional | | +| **newArrivals** | `{ listingId: string; name: string; tagline?: string; iconUrl?: string; … }[]` | optional | | +| **collections** | `{ id: string; name: string; description?: string; coverImageUrl?: string; … }[]` | optional | | --- @@ -147,7 +147,7 @@ const result = AppDiscoveryRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | | +| **items** | `{ listingId: string; packageId: string; name: string; iconUrl?: string; … }[]` | ✅ | | | **total** | `integer` | ✅ | | | **page** | `integer` | ✅ | | | **pageSize** | `integer` | ✅ | | @@ -176,11 +176,11 @@ const result = AppDiscoveryRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | | +| **items** | `{ id: string; listingId: string; userId: string; displayName?: string; … }[]` | ✅ | | | **total** | `integer` | ✅ | | | **page** | `integer` | ✅ | | | **pageSize** | `integer` | ✅ | | -| **ratingSummary** | `Object` | optional | | +| **ratingSummary** | `{ averageRating: number; totalRatings: integer; distribution: object }` | optional | | --- @@ -273,7 +273,7 @@ const result = AppDiscoveryRequest.parse(data); | **appVersion** | `string` | optional | App version being reviewed | | **moderationStatus** | `Enum<'pending' \| 'approved' \| 'flagged' \| 'rejected'>` | ✅ | | | **helpfulCount** | `integer` | ✅ | | -| **publisherResponse** | `Object` | optional | Publisher response to review | +| **publisherResponse** | `{ body: string; respondedAt: string }` | optional | Publisher response to review | | **submittedAt** | `string` | ✅ | | | **updatedAt** | `string` | optional | | diff --git a/content/docs/references/cloud/developer-portal.mdx b/content/docs/references/cloud/developer-portal.mdx index 6dd328f84e..d6145cfc76 100644 --- a/content/docs/references/cloud/developer-portal.mdx +++ b/content/docs/references/cloud/developer-portal.mdx @@ -93,7 +93,7 @@ const result = AnalyticsTimeRange.parse(data); | **category** | `string` | ✅ | Marketplace category | | **tags** | `string[]` | optional | | | **iconUrl** | `string` | optional | | -| **screenshots** | `Object[]` | optional | | +| **screenshots** | `{ url: string; caption?: string }[]` | optional | | | **documentationUrl** | `string` | optional | | | **supportUrl** | `string` | optional | | | **repositoryUrl** | `string` | optional | | @@ -154,9 +154,9 @@ const result = AnalyticsTimeRange.parse(data); | :--- | :--- | :--- | :--- | | **listingId** | `string` | ✅ | | | **timeRange** | `Enum<'last_7d' \| 'last_30d' \| 'last_90d' \| 'last_365d' \| 'all_time'>` | ✅ | | -| **summary** | `Object` | ✅ | | -| **timeSeries** | `Record` | optional | Time series keyed by metric name | -| **ratingDistribution** | `Object` | optional | | +| **summary** | `{ totalInstalls: integer; activeInstalls: integer; totalUninstalls: integer; averageRating?: number; … }` | ✅ | | +| **timeSeries** | `Record` | optional | Time series keyed by metric name | +| **ratingDistribution** | `{ 1: integer; 2: integer; 3: integer; 4: integer; … }` | optional | | --- @@ -198,7 +198,7 @@ const result = AnalyticsTimeRange.parse(data); | **category** | `string` | optional | | | **tags** | `string[]` | optional | | | **iconUrl** | `string` | optional | | -| **screenshots** | `Object[]` | optional | | +| **screenshots** | `{ url: string; caption?: string }[]` | optional | | | **documentationUrl** | `string` | optional | | | **supportUrl** | `string` | optional | | | **repositoryUrl** | `string` | optional | | @@ -217,7 +217,7 @@ const result = AnalyticsTimeRange.parse(data); | **version** | `string` | ✅ | Semver version (e.g., 2.1.0-beta.1) | | **channel** | `Enum<'alpha' \| 'beta' \| 'rc' \| 'stable'>` | ✅ | | | **releaseNotes** | `string` | optional | Release notes (Markdown) | -| **changelog** | `Object[]` | optional | Structured changelog entries | +| **changelog** | `{ type: Enum<'added' \| 'changed' \| 'fixed' \| 'removed' \| 'deprecated' \| 'security'>; description: string }[]` | optional | Structured changelog entries | | **minPlatformVersion** | `string` | optional | | | **artifactUrl** | `string` | optional | Built package artifact URL | | **artifactChecksum** | `string` | optional | SHA-256 checksum | diff --git a/content/docs/references/cloud/environment-package.mdx b/content/docs/references/cloud/environment-package.mdx index ae3c578c32..41f0d68a1f 100644 --- a/content/docs/references/cloud/environment-package.mdx +++ b/content/docs/references/cloud/environment-package.mdx @@ -110,7 +110,7 @@ List of packages installed in an environment | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **packages** | `Object[]` | ✅ | Packages installed in this environment | +| **packages** | `{ id: string; environmentId: string; packageVersionId: string; packageId: string; … }[]` | ✅ | Packages installed in this environment | | **total** | `number` | ✅ | Total count | diff --git a/content/docs/references/cloud/environment.mdx b/content/docs/references/cloud/environment.mdx index d242727795..b2d56abb3a 100644 --- a/content/docs/references/cloud/environment.mdx +++ b/content/docs/references/cloud/environment.mdx @@ -230,8 +230,8 @@ Public exposure of this environment artifacts (private | unlisted | public). | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **environment** | `Object` | ✅ | Provisioned environment (includes database addressing) | -| **credential** | `Object` | ✅ | Freshly-minted credential for the environment DB | +| **environment** | `{ id: string; organizationId: string; displayName: string; isDefault: boolean; … }` | ✅ | Provisioned environment (includes database addressing) | +| **credential** | `{ id: string; environmentId: string; secretCiphertext: string; encryptionKeyId: string; … }` | ✅ | Freshly-minted credential for the environment DB | | **durationMs** | `number` | ✅ | Total provisioning duration in milliseconds | | **warnings** | `string[]` | optional | Non-fatal warnings emitted during provisioning | @@ -261,7 +261,7 @@ Public exposure of this environment artifacts (private | unlisted | public). | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **defaultEnvironment** | `Object` | ✅ | Default environment that was created | +| **defaultEnvironment** | `{ environment: object; credential: object; durationMs: number; warnings?: string[] }` | ✅ | Default environment that was created | | **durationMs** | `number` | ✅ | Total bootstrap duration in milliseconds | | **warnings** | `string[]` | optional | Non-fatal warnings | diff --git a/content/docs/references/cloud/marketplace-admin.mdx b/content/docs/references/cloud/marketplace-admin.mdx index a6ca5b4da3..d4edc104c7 100644 --- a/content/docs/references/cloud/marketplace-admin.mdx +++ b/content/docs/references/cloud/marketplace-admin.mdx @@ -190,7 +190,7 @@ const result = CuratedCollection.parse(data); | **submissionId** | `string` | ✅ | Submission being reviewed | | **reviewerId** | `string` | ✅ | Platform reviewer ID | | **decision** | `Enum<'approved' \| 'rejected' \| 'changes-requested'>` | optional | Final decision | -| **criteria** | `Object[]` | optional | Review checklist results | +| **criteria** | `{ id: string; category: Enum<'security' \| 'performance' \| 'quality' \| 'ux' \| 'documentation' \| 'policy' \| 'compatibility'>; description: string; required: boolean; … }[]` | optional | Review checklist results | | **rejectionReasons** | `Enum<'security-vulnerability' \| 'policy-violation' \| 'quality-below-standard' \| 'misleading-metadata' \| 'incompatible' \| 'duplicate' \| 'insufficient-documentation' \| 'other'>[]` | optional | | | **feedback** | `string` | optional | Detailed review feedback (Markdown) | | **internalNotes** | `string` | optional | Internal reviewer notes | diff --git a/content/docs/references/cloud/marketplace.mdx b/content/docs/references/cloud/marketplace.mdx index 025b13d553..ca79b108e2 100644 --- a/content/docs/references/cloud/marketplace.mdx +++ b/content/docs/references/cloud/marketplace.mdx @@ -168,7 +168,7 @@ Install from marketplace request | **licenseKey** | `string` | optional | License key for paid packages | | **settings** | `Record` | optional | User-provided settings at install time | | **enableOnInstall** | `boolean` | ✅ | Whether to enable immediately after install | -| **artifactRef** | `Object` | optional | Artifact reference for direct installation | +| **artifactRef** | `{ url: string; sha256: string; size: integer; format: Enum<'tgz' \| 'zip'>; … }` | optional | Artifact reference for direct installation | | **tenantId** | `string` | optional | Tenant identifier | @@ -209,7 +209,7 @@ Public-facing package listing on the marketplace | **category** | `Enum<'crm' \| 'erp' \| 'hr' \| 'finance' \| 'project' \| 'collaboration' \| 'analytics' \| 'integration' \| 'automation' \| 'ai' \| 'security' \| 'developer-tools' \| 'ui-theme' \| 'storage' \| 'other'>` | ✅ | Package category | | **tags** | `string[]` | optional | Search tags | | **iconUrl** | `string` | optional | Package icon URL | -| **screenshots** | `Object[]` | optional | Screenshots | +| **screenshots** | `{ url: string; caption?: string }[]` | optional | Screenshots | | **documentationUrl** | `string` | optional | Documentation URL | | **supportUrl** | `string` | optional | Support URL | | **repositoryUrl** | `string` | optional | Source repository URL | @@ -217,11 +217,11 @@ Public-facing package listing on the marketplace | **priceInCents** | `integer` | optional | Price in cents (e.g. 999 = $9.99) | | **latestVersion** | `string` | ✅ | Latest published version | | **minPlatformVersion** | `string` | optional | Minimum ObjectStack platform version | -| **versions** | `Object[]` | optional | Published versions | -| **stats** | `Object` | optional | Aggregate marketplace statistics | +| **versions** | `{ version: string; releaseDate: string; releaseNotes?: string; minPlatformVersion?: string; … }[]` | optional | Published versions | +| **stats** | `{ totalInstalls: integer; activeInstalls: integer; averageRating?: number; totalRatings: integer; … }` | optional | Aggregate marketplace statistics | | **publishedAt** | `string` | optional | First published timestamp | | **updatedAt** | `string` | optional | Last updated timestamp | -| **translations** | `Record` | optional | Locale-keyed overrides for name / tagline / description / screenshot captions | +| **translations** | `Record` | optional | Locale-keyed overrides for name / tagline / description / screenshot captions | --- @@ -256,11 +256,11 @@ Marketplace search response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | Search result listings | +| **items** | `{ id: string; packageId: string; packageType: Enum<'app'>; publisherId: string; … }[]` | ✅ | Search result listings | | **total** | `integer` | ✅ | Total matching results | | **page** | `integer` | ✅ | Current page number | | **pageSize** | `integer` | ✅ | Items per page | -| **facets** | `Object` | optional | Aggregation facets for refining search | +| **facets** | `{ categories?: { category: Enum<'crm' \| 'erp' \| 'hr' \| 'finance' \| 'project' \| 'collaboration' \| 'analytics' \| 'integration' \| 'automation' \| 'ai' \| 'security' \| 'developer-tools' \| 'ui-theme' \| 'storage' \| 'other'>; count: integer }[]; pricing?: { model: Enum<'free' \| 'freemium' \| 'paid' \| 'subscription' \| 'usage-based' \| 'contact-sales'>; count: integer }[] }` | optional | Aggregation facets for refining search | --- @@ -281,7 +281,7 @@ Developer submission of a package version for review | **artifactUrl** | `string` | ✅ | Package artifact URL for review | | **releaseNotes** | `string` | optional | Release notes for this version | | **isNewListing** | `boolean` | ✅ | Whether this is a new listing submission | -| **scanResults** | `Object` | optional | Automated scan results | +| **scanResults** | `{ passed: boolean; securityScore?: number; compatibilityCheck?: boolean; issues?: { severity: Enum<'critical' \| 'high' \| 'medium' \| 'low' \| 'info'>; message: string; file?: string; line?: number }[] }` | optional | Automated scan results | | **reviewerNotes** | `string` | optional | Notes from the platform reviewer | | **submittedAt** | `string` | optional | Submission timestamp | | **reviewedAt** | `string` | optional | Review completion timestamp | diff --git a/content/docs/references/cloud/package-version.mdx b/content/docs/references/cloud/package-version.mdx index 46086489ef..b37e6cd5f0 100644 --- a/content/docs/references/cloud/package-version.mdx +++ b/content/docs/references/cloud/package-version.mdx @@ -71,7 +71,7 @@ Package manifest snapshot embedded in a package version | **description** | `string` | optional | Short description | | **scope** | `Enum<'platform' \| 'environment'>` | ✅ | Package scope | | **minPlatformVersion** | `string` | optional | Minimum required platform version (semver) | -| **dependencies** | `Object[]` | ✅ | Package dependencies | +| **dependencies** | `{ packageId: string; versionRange: string; optional: boolean }[]` | ✅ | Package dependencies | | **metadataTypes** | `string[]` | ✅ | Metadata types provided by this package | | **migrations** | `string[]` | ✅ | Migration script identifiers (ordered) | | **configurationSchema** | `Record` | optional | JSON Schema for per-installation configuration properties | diff --git a/content/docs/references/cloud/package.mdx b/content/docs/references/cloud/package.mdx index 23b883252a..ac0d155557 100644 --- a/content/docs/references/cloud/package.mdx +++ b/content/docs/references/cloud/package.mdx @@ -61,7 +61,7 @@ Register a new package in the Control Plane | **license** | `string` | optional | | | **publisher** | `Enum<'objectstack' \| 'partner' \| 'community' \| 'private'>` | optional | Package publisher provenance tier | | **isStarter** | `boolean` | optional | | -| **translations** | `Record` | optional | Locale-keyed overrides; missing keys fall back to base columns | +| **translations** | `Record` | optional | Locale-keyed overrides; missing keys fall back to base columns | | **createdBy** | `string` | ✅ | User ID creating the package | @@ -87,7 +87,7 @@ Register a new package in the Control Plane | **license** | `string` | optional | SPDX license identifier (e.g. MIT, Apache-2.0) | | **publisher** | `Enum<'objectstack' \| 'partner' \| 'community' \| 'private'>` | ✅ | Package publisher provenance tier | | **isStarter** | `boolean` | ✅ | If true, surfaces in the Create Project blueprint picker as a starter template | -| **translations** | `Record` | optional | Locale-keyed overrides for display_name / description / readme | +| **translations** | `Record` | optional | Locale-keyed overrides for display_name / description / readme | | **createdAt** | `string` | ✅ | Creation timestamp (ISO-8601) | | **updatedAt** | `string` | ✅ | Last update timestamp (ISO-8601) | | **createdBy** | `string` | ✅ | User ID that created the package | @@ -167,7 +167,7 @@ Update mutable package metadata | **license** | `string` | optional | | | **publisher** | `Enum<'objectstack' \| 'partner' \| 'community' \| 'private'>` | optional | Package publisher provenance tier | | **isStarter** | `boolean` | optional | | -| **translations** | `Record` | optional | Locale-keyed overrides; missing keys fall back to base columns | +| **translations** | `Record` | optional | Locale-keyed overrides; missing keys fall back to base columns | --- diff --git a/content/docs/references/cloud/template-manifest.mdx b/content/docs/references/cloud/template-manifest.mdx index 4fcaa942df..ce1b6b7868 100644 --- a/content/docs/references/cloud/template-manifest.mdx +++ b/content/docs/references/cloud/template-manifest.mdx @@ -48,12 +48,12 @@ objectstack.manifest.json — template / package source descriptor | **license** | `string` | optional | | | **publisher** | `Enum<'objectstack' \| 'partner' \| 'community' \| 'private'>` | optional | Package publisher provenance tier | | **isStarter** | `boolean` | optional | | -| **translations** | `Record` | optional | Locale-keyed overrides; missing keys fall back to base columns | +| **translations** | `Record` | optional | Locale-keyed overrides; missing keys fall back to base columns | | **name** | `string` | ✅ | CLI slug (kebab-case, no namespace prefix) | | **specVersion** | `string` | ✅ | Compatible @objectstack/spec semver range | | **skills** | `string[]` | optional | Skill ids exercised by this template (for docs / picker) | -| **preview** | `Object` | optional | | -| **scaffold** | `Object` | optional | | +| **preview** | `{ screenshots?: string[]; demoUrl?: string }` | optional | | +| **scaffold** | `{ variables?: Record; postInstall?: string[] }` | optional | | | **readmePath** | `string` | optional | Path (relative to manifest) to long-form README | diff --git a/content/docs/references/cloud/tenant.mdx b/content/docs/references/cloud/tenant.mdx index 45eac0602f..932dd8c4f6 100644 --- a/content/docs/references/cloud/tenant.mdx +++ b/content/docs/references/cloud/tenant.mdx @@ -90,7 +90,7 @@ const result = PackageInstallation.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **tenant** | `Object` | ✅ | Provisioned tenant database | +| **tenant** | `{ id: string; organizationId: string; databaseName: string; databaseUrl: string; … }` | ✅ | Provisioned tenant database | | **durationMs** | `number` | ✅ | Provisioning duration in milliseconds | | **warnings** | `string[]` | optional | Provisioning warnings | diff --git a/content/docs/references/data/analytics.mdx b/content/docs/references/data/analytics.mdx index 682bb2959d..eccf3d83f7 100644 --- a/content/docs/references/data/analytics.mdx +++ b/content/docs/references/data/analytics.mdx @@ -57,8 +57,8 @@ const result = AggregationMetricType.parse(data); | **cube** | `string` | optional | Target cube name (optional when provided externally, e.g. in API request wrapper) | | **measures** | `string[]` | ✅ | List of metrics to calculate | | **dimensions** | `string[]` | optional | List of dimensions to group by | -| **where** | `[__schema0](./__schema0)` | optional | Filtering criteria (canonical Query DSL FilterCondition) | -| **timeDimensions** | `Object[]` | optional | | +| **where** | `any` | optional | Filtering criteria (canonical Query DSL FilterCondition) | +| **timeDimensions** | `{ dimension: string; granularity?: Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; dateRange?: string \| string[] }[]` | optional | | | **order** | `Record>` | optional | | | **limit** | `number` | optional | | | **offset** | `number` | optional | | @@ -77,10 +77,10 @@ const result = AggregationMetricType.parse(data); | **title** | `string` | optional | | | **description** | `string` | optional | | | **sql** | `string` | ✅ | Base SQL statement or Table Name | -| **measures** | `Record` | ✅ | Quantitative metrics | -| **dimensions** | `Record` | ✅ | Qualitative attributes | -| **joins** | `Record` | optional | | -| **refreshKey** | `Object` | optional | | +| **measures** | `Record; … }>` | ✅ | Quantitative metrics | +| **dimensions** | `Record; … }>` | ✅ | Qualitative attributes | +| **joins** | `Record; sql: string }>` | optional | | +| **refreshKey** | `{ every?: string; sql?: string }` | optional | | | **public** | `boolean` | ✅ | | @@ -139,7 +139,7 @@ const result = AggregationMetricType.parse(data); | **description** | `string` | optional | | | **type** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'number' \| 'string' \| 'boolean'>` | ✅ | | | **sql** | `string` | ✅ | SQL expression or field reference | -| **filters** | `Object[]` | optional | | +| **filters** | `{ sql: string }[]` | optional | | | **format** | `string` | optional | | diff --git a/content/docs/references/data/data-engine.mdx b/content/docs/references/data/data-engine.mdx index c4e6bfae52..d82962b04f 100644 --- a/content/docs/references/data/data-engine.mdx +++ b/content/docs/references/data/data-engine.mdx @@ -39,7 +39,7 @@ const result = BaseEngineOptions.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | --- @@ -52,10 +52,10 @@ Options for DataEngine.aggregate operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **filter** | `Record \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **filter** | `Record \| any` | optional | Data Engine query filter conditions | | **groupBy** | `string[]` | optional | | -| **aggregations** | `Object[]` | optional | | +| **aggregations** | `{ field: string; method: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct'>; alias?: string }[]` | optional | | --- @@ -66,9 +66,9 @@ Options for DataEngine.aggregate operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'aggregate'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | ✅ | | +| **query** | `{ context?: object; where?: Record \| any; groupBy?: string[]; aggregations?: { function: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; alias: string; distinct?: boolean; … }[]; … }` | ✅ | | --- @@ -79,8 +79,8 @@ Options for DataEngine.aggregate operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **requests** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | | +| **method** | `'batch'` | ✅ | | +| **requests** | `{ method: 'find'; object: string; query?: object } \| { method: 'findOne'; object: string; query?: object } \| { method: 'insert'; object: string; data: Record \| Record[]; options?: object } \| { method: 'update'; object: string; data: Record; id?: string \| number; … } \| { method: 'delete'; object: string; id?: string \| number; options?: object } \| { method: 'count'; object: string; query?: object } \| { method: 'aggregate'; object: string; query: object } \| { method: 'execute'; command: any; options?: Record } \| { method: 'vectorFind'; object: string; vector: number[]; where?: Record \| any; … }[]` | ✅ | | | **transaction** | `boolean` | optional | | @@ -94,8 +94,8 @@ Options for DataEngine.count operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **filter** | `Record \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **filter** | `Record \| any` | optional | Data Engine query filter conditions | --- @@ -106,9 +106,9 @@ Options for DataEngine.count operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'count'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | optional | | +| **query** | `{ context?: object; where?: Record \| any; filter?: Record \| any }` | optional | | --- @@ -121,8 +121,8 @@ Options for DataEngine.delete operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **filter** | `Record \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **filter** | `Record \| any` | optional | Data Engine query filter conditions | | **multi** | `boolean` | optional | | @@ -134,10 +134,10 @@ Options for DataEngine.delete operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'delete'` | ✅ | | | **object** | `string` | ✅ | | | **id** | `string \| number` | optional | ID for single delete, or use where in options | -| **options** | `Object` | optional | | +| **options** | `{ context?: object; where?: Record \| any; multi?: boolean; filter?: Record \| any }` | optional | | --- @@ -148,7 +148,7 @@ Options for DataEngine.delete operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'execute'` | ✅ | | | **command** | `any` | ✅ | | | **options** | `Record` | optional | | @@ -171,7 +171,7 @@ Type: `Record` #### Option 2 -Reference: [__schema0](./__schema0) +Reference: any --- @@ -184,9 +184,9 @@ Reference: [__schema0](./__schema0) | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'findOne'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | optional | | +| **query** | `{ context?: object; where?: Record \| any; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; orderBy?: { field: string; order: Enum<'asc' \| 'desc'> }[]; … }` | optional | | --- @@ -197,9 +197,9 @@ Reference: [__schema0](./__schema0) | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'find'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | optional | | +| **query** | `{ context?: object; where?: Record \| any; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; orderBy?: { field: string; order: Enum<'asc' \| 'desc'> }[]; … }` | optional | | --- @@ -212,7 +212,7 @@ Options for DataEngine.insert operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | | **returning** | `boolean` | optional | | @@ -224,10 +224,10 @@ Options for DataEngine.insert operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'insert'` | ✅ | | | **object** | `string` | ✅ | | | **data** | `Record \| Record[]` | ✅ | | -| **options** | `Object` | optional | Options for DataEngine.insert operations | +| **options** | `{ context?: object; returning?: boolean }` | optional | Options for DataEngine.insert operations | --- @@ -240,10 +240,10 @@ Query options for IDataEngine.find() operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **filter** | `Record \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **filter** | `Record \| any` | optional | Data Engine query filter conditions | | **select** | `string[]` | optional | | -| **sort** | `Record> \| Record \| Object[]` | optional | Sort order definition | +| **sort** | `Record> \| Record \| { field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sort order definition | | **limit** | `integer` | optional | | | **skip** | `integer` | optional | | | **top** | `integer` | optional | | @@ -266,9 +266,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'find'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | optional | | +| **query** | `{ context?: object; where?: Record \| any; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; orderBy?: { field: string; order: Enum<'asc' \| 'desc'> }[]; … }` | optional | | --- @@ -278,9 +278,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'findOne'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | optional | | +| **query** | `{ context?: object; where?: Record \| any; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; orderBy?: { field: string; order: Enum<'asc' \| 'desc'> }[]; … }` | optional | | --- @@ -290,10 +290,10 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'insert'` | ✅ | | | **object** | `string` | ✅ | | | **data** | `Record \| Record[]` | ✅ | | -| **options** | `Object` | optional | Options for DataEngine.insert operations | +| **options** | `{ context?: object; returning?: boolean }` | optional | Options for DataEngine.insert operations | --- @@ -303,11 +303,11 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'update'` | ✅ | | | **object** | `string` | ✅ | | | **data** | `Record` | ✅ | | | **id** | `string \| number` | optional | ID for single update, or use where in options | -| **options** | `Object` | optional | | +| **options** | `{ context?: object; where?: Record \| any; upsert?: boolean; multi?: boolean; … }` | optional | | --- @@ -317,10 +317,10 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'delete'` | ✅ | | | **object** | `string` | ✅ | | | **id** | `string \| number` | optional | ID for single delete, or use where in options | -| **options** | `Object` | optional | | +| **options** | `{ context?: object; where?: Record \| any; multi?: boolean; filter?: Record \| any }` | optional | | --- @@ -330,9 +330,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'count'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | optional | | +| **query** | `{ context?: object; where?: Record \| any; filter?: Record \| any }` | optional | | --- @@ -342,9 +342,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'aggregate'` | ✅ | | | **object** | `string` | ✅ | | -| **query** | `Object` | ✅ | | +| **query** | `{ context?: object; where?: Record \| any; groupBy?: string[]; aggregations?: { function: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; alias: string; distinct?: boolean; … }[]; … }` | ✅ | | --- @@ -354,8 +354,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **requests** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | | +| **method** | `'batch'` | ✅ | | +| **requests** | `{ method: 'find'; object: string; query?: object } \| { method: 'findOne'; object: string; query?: object } \| { method: 'insert'; object: string; data: Record \| Record[]; options?: object } \| { method: 'update'; object: string; data: Record; id?: string \| number; … } \| { method: 'delete'; object: string; id?: string \| number; options?: object } \| { method: 'count'; object: string; query?: object } \| { method: 'aggregate'; object: string; query: object } \| { method: 'execute'; command: any; options?: Record } \| { method: 'vectorFind'; object: string; vector: number[]; where?: Record \| any; … }[]` | ✅ | | | **transaction** | `boolean` | optional | | --- @@ -366,7 +366,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'execute'` | ✅ | | | **command** | `any` | ✅ | | | **options** | `Record` | optional | | @@ -378,10 +378,10 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'vectorFind'` | ✅ | | | **object** | `string` | ✅ | | | **vector** | `number[]` | ✅ | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | +| **where** | `Record \| any` | optional | | | **fields** | `string[]` | optional | | | **limit** | `integer` | optional | | | **threshold** | `number` | optional | | @@ -407,13 +407,13 @@ Type: `Record>` #### Option 2 -Type: `Record` +Type: `Record` --- #### Option 3 -Type: `Object[]` +Type: `{ field: string; order: Enum<'asc' | 'desc'> }[]` --- @@ -428,8 +428,8 @@ Options for DataEngine.update operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **filter** | `Record \| [__schema0](./__schema0)` | optional | Data Engine query filter conditions | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **filter** | `Record \| any` | optional | Data Engine query filter conditions | | **upsert** | `boolean` | optional | | | **multi** | `boolean` | optional | | | **returning** | `boolean` | optional | | @@ -443,11 +443,11 @@ Options for DataEngine.update operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'update'` | ✅ | | | **object** | `string` | ✅ | | | **data** | `Record` | ✅ | | | **id** | `string \| number` | optional | ID for single update, or use where in options | -| **options** | `Object` | optional | | +| **options** | `{ context?: object; where?: Record \| any; upsert?: boolean; multi?: boolean; … }` | optional | | --- @@ -458,10 +458,10 @@ Options for DataEngine.update operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | +| **method** | `'vectorFind'` | ✅ | | | **object** | `string` | ✅ | | | **vector** | `number[]` | ✅ | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | +| **where** | `Record \| any` | optional | | | **fields** | `string[]` | optional | | | **limit** | `integer` | optional | | | **threshold** | `number` | optional | | @@ -477,10 +477,10 @@ QueryAST-aligned options for DataEngine.aggregate operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **where** | `Record \| any` | optional | | | **groupBy** | `string[]` | optional | | -| **aggregations** | `Object[]` | optional | | +| **aggregations** | `{ function: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; alias: string; distinct?: boolean; … }[]` | optional | | | **timezone** | `string` | optional | | @@ -494,8 +494,8 @@ QueryAST-aligned options for DataEngine.count operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **where** | `Record \| any` | optional | | --- @@ -508,8 +508,8 @@ QueryAST-aligned options for DataEngine.delete operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **where** | `Record \| any` | optional | | | **multi** | `boolean` | optional | | @@ -523,16 +523,16 @@ QueryAST-aligned query options for IDataEngine.find() operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | -| **fields** | `[__schema1](./__schema1)[]` | optional | | -| **orderBy** | `Object[]` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **where** | `Record \| any` | optional | | +| **fields** | `string \| { field: string; fields?: object[]; alias?: string }[]` | optional | | +| **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | | | **limit** | `number` | optional | | | **offset** | `number` | optional | | | **top** | `number` | optional | | | **cursor** | `Record` | optional | | -| **search** | `Object` | optional | | -| **expand** | `Record` | optional | | +| **search** | `{ query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | | +| **expand** | `Record` | optional | | | **distinct** | `boolean` | optional | | @@ -546,8 +546,8 @@ QueryAST-aligned options for DataEngine.update operations | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | optional | | -| **where** | `Record \| [__schema0](./__schema0)` | optional | | +| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional | | +| **where** | `Record \| any` | optional | | | **upsert** | `boolean` | optional | | | **multi** | `boolean` | optional | | | **returning** | `boolean` | optional | | diff --git a/content/docs/references/data/datasource.mdx b/content/docs/references/data/datasource.mdx index 6d3df13f0f..0bea2ed219 100644 --- a/content/docs/references/data/datasource.mdx +++ b/content/docs/references/data/datasource.mdx @@ -35,17 +35,17 @@ const result = Datasource.parse(data); | **label** | `string` | optional | Display label | | **driver** | `string` | ✅ | Underlying driver type | | **config** | `Record` | ✅ | Driver specific configuration | -| **pool** | `Object` | optional | Connection pool settings | +| **pool** | `{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }` | optional | Connection pool settings | | **readReplicas** | `Record[]` | optional | Read-only replica configurations | -| **capabilities** | `Object` | optional | Capability overrides | -| **healthCheck** | `Object` | optional | Datasource health check configuration | -| **ssl** | `Object` | optional | SSL/TLS configuration for secure database connections | -| **retryPolicy** | `Object` | optional | Connection retry policy for transient failures | +| **capabilities** | `{ transactions: boolean; queryFilters: boolean; queryAggregations: boolean; querySorting: boolean; … }` | optional | Capability overrides | +| **healthCheck** | `{ enabled: boolean; intervalMs: number; timeoutMs: number }` | optional | Datasource health check configuration | +| **ssl** | `{ enabled: boolean; rejectUnauthorized: boolean; ca?: string; cert?: string; … }` | optional | SSL/TLS configuration for secure database connections | +| **retryPolicy** | `{ maxRetries: number; baseDelayMs: number; maxDelayMs: number; backoffMultiplier: number }` | optional | Connection retry policy for transient failures | | **description** | `string` | optional | Internal description | | **active** | `boolean` | ✅ | Is datasource enabled | | **autoConnect** | `boolean` | ✅ | Force a live driver connection at boot even when managed + unrouted (ADR-0062 D2). | | **schemaMode** | `Enum<'managed' \| 'external' \| 'validate-only'>` | ✅ | Schema ownership mode | -| **external** | `Object` | optional | External datasource federation settings (schemaMode != "managed") | +| **external** | `{ label?: string; allowedSchemas?: string[]; allowWrites: boolean; validation: object; … }` | optional | External datasource federation settings (schemaMode != "managed") | | **origin** | `Enum<'code' \| 'runtime'>` | ✅ | Datasource provenance (server-managed, read-only) | @@ -83,7 +83,7 @@ const result = Datasource.parse(data); | **description** | `string` | optional | | | **icon** | `string` | optional | | | **configSchema** | `Record` | ✅ | JSON Schema for connection configuration | -| **capabilities** | `Object` | optional | | +| **capabilities** | `{ transactions: boolean; queryFilters: boolean; queryAggregations: boolean; querySorting: boolean; … }` | optional | | --- @@ -102,7 +102,7 @@ External datasource federation settings (schemaMode != "managed") | **label** | `string` | optional | Display label, e.g. "Snowflake — ANALYTICS / PROD" | | **allowedSchemas** | `string[]` | optional | Whitelist of remote schemas/databases that may be exposed. | | **allowWrites** | `boolean` | ✅ | Global write gate. Individual objects must also opt in via object.external.writable. | -| **validation** | `Object` | ✅ | Boot/drift validation policy | +| **validation** | `{ onMismatch: Enum<'fail' \| 'warn' \| 'ignore'>; checkOnBoot: boolean; checkIntervalMs?: number }` | ✅ | Boot/drift validation policy | | **credentialsRef** | `string` | optional | Reference into the secrets store; never inline credentials. | | **queryTimeoutMs** | `number` | ✅ | Hard cap on per-query execution time. | | **requirePermission** | `string` | optional | Optional convenience: gate the entire datasource behind a single role. | diff --git a/content/docs/references/data/document.mdx b/content/docs/references/data/document.mdx index fe53ddd393..05fa7adcf9 100644 --- a/content/docs/references/data/document.mdx +++ b/content/docs/references/data/document.mdx @@ -64,10 +64,10 @@ const result = Document.parse(data); | **fileSize** | `number` | ✅ | File size in bytes | | **category** | `string` | optional | Document category | | **tags** | `string[]` | optional | Document tags | -| **versioning** | `Object` | optional | Version control | -| **template** | `Object` | optional | Document template | -| **eSignature** | `Object` | optional | E-signature config | -| **access** | `Object` | optional | Access control | +| **versioning** | `{ enabled: boolean; versions: { versionNumber: number; createdAt: number; createdBy: string; size: number; … }[]; majorVersion: number; minorVersion: number }` | optional | Version control | +| **template** | `{ id: string; name: string; description?: string; fileUrl: string; … }` | optional | Document template | +| **eSignature** | `{ provider: Enum<'docusign' \| 'adobe-sign' \| 'hellosign' \| 'custom'>; enabled: boolean; signers: { email: string; name: string; role: string; order: number }[]; expirationDays: number; … }` | optional | E-signature config | +| **access** | `{ isPublic: boolean; sharedWith?: string[]; expiresAt?: number }` | optional | Access control | | **metadata** | `Record` | optional | Custom metadata | @@ -84,7 +84,7 @@ const result = Document.parse(data); | **description** | `string` | optional | Template description | | **fileUrl** | `string` | ✅ | Template file URL | | **fileType** | `string` | ✅ | File MIME type | -| **placeholders** | `Object[]` | ✅ | Template placeholders | +| **placeholders** | `{ key: string; label: string; type: Enum<'text' \| 'number' \| 'date' \| 'image'>; required: boolean }[]` | ✅ | Template placeholders | --- @@ -114,7 +114,7 @@ const result = Document.parse(data); | :--- | :--- | :--- | :--- | | **provider** | `Enum<'docusign' \| 'adobe-sign' \| 'hellosign' \| 'custom'>` | ✅ | E-signature provider | | **enabled** | `boolean` | ✅ | E-signature enabled | -| **signers** | `Object[]` | ✅ | Document signers | +| **signers** | `{ email: string; name: string; role: string; order: number }[]` | ✅ | Document signers | | **expirationDays** | `number` | ✅ | Expiration days | | **reminderDays** | `number` | ✅ | Reminder interval days | diff --git a/content/docs/references/data/driver-nosql.mdx b/content/docs/references/data/driver-nosql.mdx index 1bd6e6ec6c..e25bc0aed6 100644 --- a/content/docs/references/data/driver-nosql.mdx +++ b/content/docs/references/data/driver-nosql.mdx @@ -32,8 +32,8 @@ const result = AggregationPipeline.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **collection** | `string` | ✅ | Collection/table name | -| **stages** | `Object[]` | ✅ | Aggregation pipeline stages | -| **options** | `Object` | optional | Query options | +| **stages** | `{ operator: string; options: Record }[]` | ✅ | Aggregation pipeline stages | +| **options** | `{ consistency?: Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>; readFromSecondary?: boolean; projection?: Record; timeout?: integer; … }` | optional | Query options | --- @@ -122,16 +122,16 @@ const result = AggregationPipeline.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Driver instance name | -| **type** | `string` | ✅ | Driver type must be "nosql" | -| **capabilities** | `Object` | ✅ | Driver capability flags | +| **type** | `'nosql'` | ✅ | Driver type must be "nosql" | +| **capabilities** | `{ create: boolean; read: boolean; update: boolean; delete: boolean; … }` | ✅ | Driver capability flags | | **connectionString** | `string` | optional | Database connection string (driver-specific format) | -| **poolConfig** | `Object` | optional | Connection pool configuration | +| **poolConfig** | `{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }` | optional | Connection pool configuration | | **databaseType** | `Enum<'mongodb' \| 'couchdb' \| 'dynamodb' \| 'cassandra' \| 'redis' \| 'elasticsearch' \| 'neo4j' \| 'orientdb'>` | ✅ | Specific NoSQL database type | -| **dataTypeMapping** | `Object` | ✅ | NoSQL data type mapping configuration | +| **dataTypeMapping** | `{ text: string; number: string; boolean: string; date: string; … }` | ✅ | NoSQL data type mapping configuration | | **consistency** | `Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>` | optional | Consistency level for operations | -| **replication** | `Object` | optional | Replication configuration | -| **sharding** | `Object` | optional | Sharding configuration | -| **schemaValidation** | `Object` | optional | Document schema validation | +| **replication** | `{ enabled: boolean; replicaSetName?: string; replicas?: integer; readPreference?: Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>; … }` | optional | Replication configuration | +| **sharding** | `{ enabled: boolean; shardKey?: string; shardingStrategy?: Enum<'hash' \| 'range' \| 'zone'>; numShards?: integer }` | optional | Sharding configuration | +| **schemaValidation** | `{ enabled: boolean; validationLevel?: Enum<'strict' \| 'moderate' \| 'off'>; validationAction?: Enum<'error' \| 'warn'>; jsonSchema?: Record }` | optional | Document schema validation | | **region** | `string` | optional | AWS region (for managed NoSQL services) | | **accessKeyId** | `string` | optional | AWS access key ID | | **secretAccessKey** | `string` | optional | AWS secret access key | @@ -150,7 +150,7 @@ const result = AggregationPipeline.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Index name | | **type** | `Enum<'single' \| 'compound' \| 'unique' \| 'text' \| 'geospatial' \| 'hashed' \| 'ttl' \| 'sparse'>` | ✅ | Index type | -| **fields** | `Object[]` | ✅ | Fields to index | +| **fields** | `{ field: string; order?: Enum<'asc' \| 'desc' \| 'text' \| '2dsphere'> }[]` | ✅ | Fields to index | | **unique** | `boolean` | ✅ | Enforce uniqueness | | **sparse** | `boolean` | ✅ | Sparse index | | **expireAfterSeconds** | `integer` | optional | TTL in seconds | @@ -203,7 +203,7 @@ const result = AggregationPipeline.parse(data); | :--- | :--- | :--- | :--- | | **consistency** | `Enum<'all' \| 'quorum' \| 'one' \| 'local_quorum' \| 'each_quorum' \| 'eventual'>` | optional | Consistency level override | | **readFromSecondary** | `boolean` | optional | Allow reading from secondary replicas | -| **projection** | `Record` | optional | Field projection | +| **projection** | `Record` | optional | Field projection | | **timeout** | `integer` | optional | Query timeout (ms) | | **useCursor** | `boolean` | optional | Use cursor instead of loading all results | | **batchSize** | `integer` | optional | Cursor batch size | diff --git a/content/docs/references/data/driver-sql.mdx b/content/docs/references/data/driver-sql.mdx index 37d288249d..c28f86bd4d 100644 --- a/content/docs/references/data/driver-sql.mdx +++ b/content/docs/references/data/driver-sql.mdx @@ -64,14 +64,14 @@ const result = DataTypeMapping.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Driver instance name | -| **type** | `string` | ✅ | Driver type must be "sql" | -| **capabilities** | `Object` | ✅ | Driver capability flags | +| **type** | `'sql'` | ✅ | Driver type must be "sql" | +| **capabilities** | `{ create: boolean; read: boolean; update: boolean; delete: boolean; … }` | ✅ | Driver capability flags | | **connectionString** | `string` | optional | Database connection string (driver-specific format) | -| **poolConfig** | `Object` | optional | Connection pool configuration | +| **poolConfig** | `{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }` | optional | Connection pool configuration | | **dialect** | `Enum<'postgresql' \| 'mysql' \| 'sqlite' \| 'mssql' \| 'oracle' \| 'mariadb'>` | ✅ | SQL database dialect | -| **dataTypeMapping** | `Object` | ✅ | SQL data type mapping configuration | +| **dataTypeMapping** | `{ text: string; number: string; boolean: string; date: string; … }` | ✅ | SQL data type mapping configuration | | **ssl** | `boolean` | ✅ | Enable SSL/TLS connection | -| **sslConfig** | `Object` | optional | SSL/TLS configuration (required when ssl is true) | +| **sslConfig** | `{ rejectUnauthorized: boolean; ca?: string; cert?: string; key?: string }` | optional | SSL/TLS configuration (required when ssl is true) | --- diff --git a/content/docs/references/data/driver.mdx b/content/docs/references/data/driver.mdx index 9a43861b08..8bfdab665d 100644 --- a/content/docs/references/data/driver.mdx +++ b/content/docs/references/data/driver.mdx @@ -77,9 +77,9 @@ const result = DriverCapabilities.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Driver instance name | | **type** | `Enum<'sql' \| 'nosql' \| 'cache' \| 'search' \| 'graph' \| 'timeseries'>` | ✅ | Driver type category | -| **capabilities** | `Object` | ✅ | Driver capability flags | +| **capabilities** | `{ create: boolean; read: boolean; update: boolean; delete: boolean; … }` | ✅ | Driver capability flags | | **connectionString** | `string` | optional | Database connection string (driver-specific format) | -| **poolConfig** | `Object` | optional | Connection pool configuration | +| **poolConfig** | `{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }` | optional | Connection pool configuration | --- diff --git a/content/docs/references/data/external-catalog.mdx b/content/docs/references/data/external-catalog.mdx index b663340618..fe26c773a5 100644 --- a/content/docs/references/data/external-catalog.mdx +++ b/content/docs/references/data/external-catalog.mdx @@ -45,7 +45,7 @@ const result = ExternalCatalog.parse(data); | **datasource** | `string` | ✅ | Datasource.name this catalog snapshots. | | **snapshotAt** | `string` | ✅ | When the snapshot was taken (ISO 8601). | | **dialect** | `string` | optional | Remote SQL dialect, when known. | -| **tables** | `Object[]` | ✅ | Snapshotted remote tables. | +| **tables** | `{ remoteSchema?: string; remoteName: string; columns: { name: string; sqlType: string; nullable: boolean; primaryKey: boolean; … }[]; indexes?: { name: string; columns: string[]; unique: boolean }[]; … }[]` | ✅ | Snapshotted remote tables. | --- @@ -73,8 +73,8 @@ const result = ExternalCatalog.parse(data); | :--- | :--- | :--- | :--- | | **remoteSchema** | `string` | optional | Remote schema/database qualifier | | **remoteName** | `string` | ✅ | Remote table/view name | -| **columns** | `Object[]` | ✅ | Remote columns | -| **indexes** | `Object[]` | optional | Remote indexes, when introspectable | +| **columns** | `{ name: string; sqlType: string; nullable: boolean; primaryKey: boolean; … }[]` | ✅ | Remote columns | +| **indexes** | `{ name: string; columns: string[]; unique: boolean }[]` | optional | Remote indexes, when introspectable | | **rowCountEstimate** | `number` | optional | Approximate row count | diff --git a/content/docs/references/data/external-lookup.mdx b/content/docs/references/data/external-lookup.mdx index 06577f05ab..2a4e935d7a 100644 --- a/content/docs/references/data/external-lookup.mdx +++ b/content/docs/references/data/external-lookup.mdx @@ -71,7 +71,7 @@ const result = ExternalDataSource.parse(data); | **name** | `string` | ✅ | Data source name | | **type** | `Enum<'odata' \| 'rest-api' \| 'graphql' \| 'custom'>` | ✅ | Protocol type | | **endpoint** | `string` | ✅ | API endpoint URL | -| **authentication** | `Object` | ✅ | Authentication | +| **authentication** | `{ type: Enum<'oauth2' \| 'api-key' \| 'basic' \| 'none'>; config: Record }` | ✅ | Authentication | --- @@ -84,7 +84,7 @@ const result = ExternalDataSource.parse(data); | :--- | :--- | :--- | :--- | | **source** | `string` | ✅ | Source field name | | **target** | `string` | ✅ | Target field name | -| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | +| **transform** | `{ type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }` | optional | Transformation to apply | | **defaultValue** | `any` | optional | Default if source is null/undefined | | **type** | `string` | optional | Field type | | **readonly** | `boolean` | optional | Read-only field | @@ -99,15 +99,15 @@ const result = ExternalDataSource.parse(data); | 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 | +| **dataSource** | `{ id: string; name: string; type: Enum<'odata' \| 'rest-api' \| 'graphql' \| 'custom'>; endpoint: string; … }` | ✅ | External data source | +| **query** | `{ endpoint: string; method?: Enum<'GET' \| 'POST'>; parameters?: Record }` | ✅ | Query configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | ✅ | Field mappings | +| **caching** | `{ enabled?: boolean; ttl?: number; strategy?: Enum<'lru' \| 'lfu' \| 'ttl'> }` | optional | Caching configuration | +| **fallback** | `{ enabled?: boolean; defaultValue?: any; showError?: boolean }` | optional | Fallback configuration | +| **rateLimit** | `{ requestsPerSecond: number; burstSize?: number }` | optional | Rate limiting | +| **retry** | `{ maxRetries?: number; initialDelayMs?: number; maxDelayMs?: number; backoffMultiplier?: number; … }` | optional | Retry configuration with exponential backoff | +| **transform** | `{ request?: object; response?: object }` | optional | Request/response transformation pipeline | +| **pagination** | `{ type?: Enum<'offset' \| 'cursor' \| 'page'>; pageSize?: number; maxPages?: number }` | optional | Pagination configuration for external data | --- diff --git a/content/docs/references/data/feed.mdx b/content/docs/references/data/feed.mdx index 21e9ee58ef..ce30737cc7 100644 --- a/content/docs/references/data/feed.mdx +++ b/content/docs/references/data/feed.mdx @@ -64,11 +64,11 @@ const result = FeedActor.parse(data); | **type** | `Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>` | ✅ | Activity type | | **object** | `string` | ✅ | Object name (e.g., "account") | | **recordId** | `string` | ✅ | Record ID this feed item belongs to | -| **actor** | `Object` | ✅ | Who performed this action | +| **actor** | `{ type: Enum<'user' \| 'system' \| 'service' \| 'automation'>; id: string; name?: string; avatarUrl?: string; … }` | ✅ | Who performed this action | | **body** | `string` | optional | Rich text body (Markdown supported) | -| **mentions** | `Object[]` | optional | Mentioned users/teams/records | -| **changes** | `Object[]` | optional | Field-level changes | -| **reactions** | `Object[]` | optional | Emoji reactions on this item | +| **mentions** | `{ type: Enum<'user' \| 'team' \| 'record'>; id: string; name: string; offset: integer; … }[]` | optional | Mentioned users/teams/records | +| **changes** | `{ field: string; fieldLabel?: string; oldValue?: any; newValue?: any; … }[]` | optional | Field-level changes | +| **reactions** | `{ emoji: string; userIds: string[]; count: integer }[]` | optional | Emoji reactions on this item | | **parentId** | `string` | optional | Parent feed item ID for threaded replies | | **replyCount** | `integer` | ✅ | Number of replies | | **pinned** | `boolean` | ✅ | Whether the feed item is pinned to the top of the timeline | diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx index 12f77712ec..3253e89243 100644 --- a/content/docs/references/data/field.mdx +++ b/content/docs/references/data/field.mdx @@ -86,7 +86,7 @@ const result = Address.parse(data); | :--- | :--- | :--- | :--- | | **uniqueness** | `boolean` | ✅ | Enforce unique values across all records | | **completeness** | `number` | ✅ | Minimum ratio of non-null values (0-1, default: 0 = no requirement) | -| **accuracy** | `Object` | optional | Accuracy validation configuration | +| **accuracy** | `{ source: string; threshold: number }` | optional | Accuracy validation configuration | --- @@ -114,7 +114,7 @@ const result = Address.parse(data); | **scale** | `number` | optional | Decimal places | | **min** | `number` | optional | Minimum value | | **max** | `number` | optional | Maximum value | -| **options** | `Object[]` | optional | Static options for select/multiselect | +| **options** | `{ label: string; value: string; color?: string; default?: boolean; … }[]` | 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 | @@ -122,32 +122,32 @@ const result = Address.parse(data); | **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). | +| **relatedList** | `boolean \| 'primary'` | 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. | +| **lookupColumns** | `string \| { field: string; label?: string; width?: string; type?: string }[]` | 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. | +| **lookupFilters** | `{ field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'lt' \| 'gte' \| 'lte' \| 'contains' \| 'in' \| 'notIn'>; value: any }[]` | optional | Base filters restricting which records are selectable (e.g. only active). Structured, picker-honoured form of referenceFilters. | +| **dependsOn** | `string \| { field: string; param?: string }[]` | 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` | +| **expression** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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. | +| **summaryOperations** | `{ object: string; field: string; function: Enum<'count' \| 'sum' \| 'min' \| 'max' \| 'avg'>; relationshipField?: string }` | 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 | +| **currencyConfig** | `{ precision?: integer; currencyMode?: Enum<'dynamic' \| 'fixed'>; defaultCurrency?: string }` | 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 | +| **vectorConfig** | `{ dimensions: integer; distanceMetric?: Enum<'cosine' \| 'euclidean' \| 'dotProduct' \| 'manhattan'>; normalized?: boolean; indexed?: boolean; … }` | optional | Configuration for vector field type (AI/ML embeddings) | +| **fileAttachmentConfig** | `{ minSize?: number; maxSize?: number; allowedTypes?: string[]; blockedTypes?: string[]; … }` | 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`. | +| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Predicate (CEL) — field is shown only when TRUE (else hidden). e.g. P`record.type == 'invoice'` | +| **readonlyWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Predicate (CEL) — field is read-only when TRUE. e.g. P`record.status == 'paid'` | +| **requiredWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Predicate (CEL) — field is required when TRUE. Canonical name for `conditionalRequired`. | +| **conditionalRequired** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 — never editable in forms, AND server-enforced on UPDATE: a non-system write to this field is silently dropped from the payload (#2948/#3003; symmetric with `readonlyWhen`). INSERT may still seed it (defaultValue, import). | @@ -238,7 +238,7 @@ const result = Address.parse(data); | **storageProvider** | `string` | optional | Object storage provider name (references ObjectStorageConfig) | | **storageBucket** | `string` | optional | Target bucket name | | **storagePrefix** | `string` | optional | Storage path prefix (e.g., "uploads/documents/") | -| **imageValidation** | `Object` | optional | Image-specific validation rules | +| **imageValidation** | `{ minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number; … }` | optional | Image-specific validation rules | | **allowMultiple** | `boolean` | ✅ | Allow multiple file uploads (overrides field.multiple) | | **allowReplace** | `boolean` | ✅ | Allow replacing existing files | | **allowDelete** | `boolean` | ✅ | Allow deleting uploaded files | @@ -277,7 +277,7 @@ const result = Address.parse(data); | **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` | +| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | --- diff --git a/content/docs/references/data/filter.mdx b/content/docs/references/data/filter.mdx index aaef8677e8..aa1134beba 100644 --- a/content/docs/references/data/filter.mdx +++ b/content/docs/references/data/filter.mdx @@ -83,7 +83,7 @@ const result = EqualityOperator.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **where** | `[__schema0](./__schema0)` | optional | | +| **where** | `any` | optional | | --- diff --git a/content/docs/references/data/hook-body.mdx b/content/docs/references/data/hook-body.mdx index 85b6bc2e21..20d08cff5a 100644 --- a/content/docs/references/data/hook-body.mdx +++ b/content/docs/references/data/hook-body.mdx @@ -57,7 +57,7 @@ L1 expression body — pure formula, no IO | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **language** | `string` | ✅ | | +| **language** | `'expression'` | ✅ | | | **source** | `string` | ✅ | Formula expression source | @@ -79,7 +79,7 @@ L1 expression body — pure formula, no IO | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **language** | `string` | ✅ | | +| **language** | `'expression'` | ✅ | | | **source** | `string` | ✅ | Formula expression source | --- @@ -92,7 +92,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **language** | `string` | ✅ | | +| **language** | `'js'` | ✅ | | | **source** | `string` | ✅ | Function body source | | **capabilities** | `Enum<'api.read' \| 'api.write' \| 'api.transaction' \| 'crypto.uuid' \| 'crypto.hash' \| 'log'>[]` | ✅ | Granted capability tokens | | **timeoutMs** | `integer` | optional | Per-invocation timeout (ms) | @@ -125,7 +125,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **language** | `string` | ✅ | | +| **language** | `'js'` | ✅ | | | **source** | `string` | ✅ | Function body source | | **capabilities** | `Enum<'api.read' \| 'api.write' \| 'api.transaction' \| 'crypto.uuid' \| 'crypto.hash' \| 'log'>[]` | ✅ | Granted capability tokens | | **timeoutMs** | `integer` | optional | Per-invocation timeout (ms) | diff --git a/content/docs/references/data/hook.mdx b/content/docs/references/data/hook.mdx index eb505018ed..def918c502 100644 --- a/content/docs/references/data/hook.mdx +++ b/content/docs/references/data/hook.mdx @@ -37,11 +37,11 @@ const result = HookContext.parse(data); | **input** | `Record` | ✅ | Mutable input parameters | | **result** | `any` | optional | Operation result (After hooks only) | | **previous** | `Record` | optional | Record state before operation | -| **session** | `Object` | optional | Current session context | +| **session** | `{ userId?: string; tenantId?: string; roles?: string[]; accessToken?: string; … }` | optional | Current session context | | **transaction** | `any` | optional | Database transaction handle | | **ql** | `any` | ✅ | ObjectQL Engine Reference | | **api** | `any` | optional | Cross-object data access (ScopedContext) | -| **user** | `Object` | optional | Current user info shortcut | +| **user** | `{ id?: string; name?: string; email?: string }` | optional | Current user info shortcut | --- diff --git a/content/docs/references/data/mapping.mdx b/content/docs/references/data/mapping.mdx index 58357da0d8..9e12f350ba 100644 --- a/content/docs/references/data/mapping.mdx +++ b/content/docs/references/data/mapping.mdx @@ -34,7 +34,7 @@ const result = FieldMapping.parse(data); | **source** | `string \| string[]` | ✅ | Source column header(s) | | **target** | `string \| string[]` | ✅ | Target object field(s) | | **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | ✅ | | -| **params** | `Object` | optional | | +| **params** | `{ value?: any; object?: string; fromField?: string; toField?: string; … }` | optional | | --- @@ -49,10 +49,10 @@ const result = FieldMapping.parse(data); | **label** | `string` | optional | | | **sourceFormat** | `Enum<'csv' \| 'json' \| 'xml' \| 'sql'>` | ✅ | | | **targetObject** | `string` | ✅ | Target Object Name | -| **fieldMapping** | `Object[]` | ✅ | | +| **fieldMapping** | `{ source: string \| string[]; target: string \| string[]; transform: Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>; params?: object }[]` | ✅ | | | **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | ✅ | | | **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) | -| **extractQuery** | `[__schema0](./__schema0)` | optional | Query to run for export only | +| **extractQuery** | `{ object: string; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; where?: any; search?: object; … }` | optional | Query to run for export only | | **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | ✅ | | | **batchSize** | `number` | ✅ | | diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx index 5d3e2918c2..25fbc6161d 100644 --- a/content/docs/references/data/object.mdx +++ b/content/docs/references/data/object.mdx @@ -67,10 +67,10 @@ 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). | -| **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). | -| **archive** | `Object` | optional | Cold-store archival (LifecycleService Archiver) — audit-class hot→cold hand-off. | +| **retention** | `{ maxAge: string; onlyWhen?: Record }` | optional | Age-based retention window enforced by the LifecycleService Reaper. | +| **ttl** | `{ field: string; expireAfter: string }` | optional | Per-row TTL auto-expiry (transient/event classes). | +| **storage** | `{ strategy: 'rotation'; shards: integer; unit: Enum<'day' \| 'week' \| 'month'> }` | optional | Physical storage strategy for high-frequency telemetry (LifecycleService Rotator). | +| **archive** | `{ after: string; to: string; keep?: string }` | optional | Cold-store archival (LifecycleService Archiver) — audit-class hot→cold hand-off. | | **reclaim** | `boolean` | optional | Run driver space reclamation (SQLite incremental_vacuum) after sweeping this object. Default true for non-record classes. | @@ -105,37 +105,37 @@ const result = ApiMethod.parse(data); | **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. | +| **userActions** | `{ create?: boolean; import?: boolean; edit?: boolean \| { enabled?: boolean; visibleWhen?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; disabledWhen?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }; delete?: boolean \| { enabled?: boolean; visibleWhen?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; disabledWhen?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }; … }` | optional | Per-object override of the resolved CRUD affordance matrix. | +| **systemFields** | `'false' \| { tenant?: boolean; owner?: boolean; audit?: boolean }` | 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). | +| **external** | `{ remoteName?: string; remoteSchema?: string; writable?: boolean; columnMap?: Record; … }` | optional | Remote table binding for federated (external) objects. | +| **fields** | `Record; description?: string; … }>` | ✅ | Field definitions map. Keys must be snake_case identifiers. | +| **indexes** | `{ name?: string; fields: string[]; type?: Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>; unique?: boolean; … }[]` | optional | Database performance indexes | +| **fieldGroups** | `{ key: string; label: string; icon?: string; description?: string; … }[]` | optional | Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema. | +| **tenancy** | `{ enabled: boolean; tenantField?: string }` | optional | Multi-tenancy configuration for SaaS applications | +| **access** | `{ default?: Enum<'public' \| 'private'> }` | optional | [ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default). | +| **requiredPermissions** | `string[] \| { read?: string[]; create?: string[]; update?: string[]; delete?: string[] }` | 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** | `{ enabled: boolean; field?: string; cascadeDelete?: boolean }` | optional | Soft delete (trash/recycle bin) configuration | +| **versioning** | `{ enabled: boolean; strategy: Enum<'snapshot' \| 'delta' \| 'event-sourcing'>; retentionDays?: number; versionField?: string }` | optional | Record versioning and history tracking configuration | +| **lifecycle** | `{ class: Enum<'record' \| 'audit' \| 'telemetry' \| 'transient' \| 'event'>; retention?: object; ttl?: object; storage?: object; … }` | optional | Data lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService. | +| **validations** | `any[]` | optional | Object-level validation rules | +| **activityMilestones** | `{ field: string; value: string; summary: string; type?: string }[]` | 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. | +| **recordName** | `{ type: Enum<'text' \| 'autonumber'>; displayFormat?: string; startNumber?: integer }` | optional | Record name generation configuration (Salesforce pattern) | +| **titleFormat** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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) | +| **stageField** | `string \| 'false'` | 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; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: 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 | +| **search** | `{ fields: string[]; displayFields?: string[]; filters?: string[] }` | optional | Search engine configuration | +| **enable** | `{ trackHistory?: boolean; searchable?: boolean; apiEnabled?: boolean; apiMethods?: Enum<'get' \| 'list' \| 'create' \| 'update' \| 'delete' \| 'upsert' \| 'bulk' \| 'aggregate' \| 'history' \| 'search' \| 'restore' \| 'purge' \| 'import' \| 'export'>[]; … }` | 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) | +| **publicSharing** | `{ enabled?: boolean; allowedAudiences?: Enum<'public' \| 'link_only' \| 'signed_in' \| 'email'>[]; allowedPermissions?: Enum<'view' \| 'comment' \| 'edit'>[]; maxExpiryDays?: integer; … }` | 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. | +| **actions** | `{ name: string; label: string; objectName?: string; icon?: string; … }[]` | optional | Actions associated with this object (auto-populated from top-level actions via objectName) | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -185,12 +185,12 @@ const result = ApiMethod.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **extend** | `string` | ✅ | Target object name (FQN) to extend | -| **fields** | `Record` | optional | Fields to add/override | +| **fields** | `Record; description?: string; … }>` | 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 | +| **validations** | `any[]` | optional | Additional validation rules to merge into the target object | +| **indexes** | `{ name?: string; fields: string[]; type?: Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>; unique?: boolean; … }[]` | optional | Additional indexes to merge into the target object | | **priority** | `integer` | optional | Merge priority (higher = applied later) | @@ -293,8 +293,8 @@ Boolean-or-predicates override for a built-in row CRUD affordance. | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | optional | Object-level on/off for the generic affordance; same meaning as the bare boolean form. Omitted → managedBy bucket default. | -| **visibleWhen** | `string \| Object` | optional | Per-record CEL predicate; false → hide the row button for that record. Fail-closed. | -| **disabledWhen** | `string \| Object` | optional | Per-record CEL predicate; true → render the row button disabled for that record. Fail-soft. | +| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Per-record CEL predicate; false → hide the row button for that record. Fail-closed. | +| **disabledWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Per-record CEL predicate; true → render the row button disabled for that record. Fail-soft. | --- diff --git a/content/docs/references/data/query.mdx b/content/docs/references/data/query.mdx index 2724050baa..62263ab5d0 100644 --- a/content/docs/references/data/query.mdx +++ b/content/docs/references/data/query.mdx @@ -51,7 +51,7 @@ const result = AggregationFunction.parse(data); | **field** | `string` | optional | Field to aggregate (optional for COUNT(*)) | | **alias** | `string` | ✅ | Result column alias | | **distinct** | `boolean` | optional | Apply DISTINCT before aggregation | -| **filter** | `[__schema0](./__schema0)` | optional | Filter/Condition to apply to the aggregation (FILTER WHERE clause) | +| **filter** | `any` | optional | Filter/Condition to apply to the aggregation (FILTER WHERE clause) | --- @@ -88,7 +88,7 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **field** | `string` | ✅ | | -| **fields** | `[#](./#)[]` | optional | | +| **fields** | `[FieldNode](#fieldnode)[]` | optional | | | **alias** | `string` | optional | | --- @@ -151,8 +151,8 @@ Type: `string` | **strategy** | `Enum<'auto' \| 'database' \| 'hash' \| 'loop'>` | optional | Execution strategy hint | | **object** | `string` | ✅ | Object/table to join | | **alias** | `string` | optional | Table alias | -| **on** | `[__schema0](./__schema0)` | ✅ | Join condition | -| **subquery** | `[__schema1](./__schema1)` | optional | Subquery instead of object | +| **on** | `any` | ✅ | Join condition | +| **subquery** | `{ object: string; fields?: string \| { field: string; fields?: object[]; alias?: string }[]; where?: any; search?: object; … }` | optional | Subquery instead of object | --- @@ -188,21 +188,21 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name (e.g. account) | -| **fields** | `[__schema0](./__schema0)[]` | optional | Fields to retrieve | -| **where** | `[__schema1](./__schema1)` | optional | Filtering criteria (WHERE) | -| **search** | `Object` | optional | Full-text search configuration ($search parameter) | -| **orderBy** | `Object[]` | optional | Sorting instructions (ORDER BY) | +| **fields** | `string \| { field: string; fields?: object[]; alias?: string }[]` | optional | Fields to retrieve | +| **where** | `any` | optional | Filtering criteria (WHERE) | +| **search** | `{ query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }` | optional | Full-text search configuration ($search parameter) | +| **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sorting instructions (ORDER BY) | | **limit** | `number` | optional | Max records to return (LIMIT) | | **offset** | `number` | optional | Records to skip (OFFSET) | | **top** | `number` | optional | Alias for limit (OData compatibility) | | **cursor** | `Record` | optional | Cursor for keyset pagination | -| **joins** | `Object[]` | optional | Explicit Table Joins | -| **aggregations** | `Object[]` | optional | Aggregation functions | -| **groupBy** | `string \| Object[]` | optional | GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing) | -| **having** | `[__schema1](./__schema1)` | optional | HAVING clause for aggregation filtering | -| **windowFunctions** | `Object[]` | optional | Window functions with OVER clause | +| **joins** | `{ type: Enum<'inner' \| 'left' \| 'right' \| 'full'>; strategy?: Enum<'auto' \| 'database' \| 'hash' \| 'loop'>; object: string; alias?: string; … }[]` | optional | Explicit Table Joins | +| **aggregations** | `{ function: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; alias: string; distinct?: boolean; … }[]` | optional | Aggregation functions | +| **groupBy** | `string \| { field: string; dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; alias?: string }[]` | optional | GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing) | +| **having** | `any` | optional | HAVING clause for aggregation filtering | +| **windowFunctions** | `{ function: Enum<'row_number' \| 'rank' \| 'dense_rank' \| 'percent_rank' \| 'lag' \| 'lead' \| 'first_value' \| 'last_value' \| 'sum' \| 'avg' \| 'count' \| 'min' \| 'max'>; field?: string; alias: string; over: object }[]` | optional | Window functions with OVER clause | | **distinct** | `boolean` | optional | SELECT DISTINCT flag | -| **expand** | `Record` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (`fields`) and filter (`where`, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent `limit`/`offset`/`orderBy` are NOT applied on this path. | +| **expand** | `Record` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (`fields`) and filter (`where`, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent `limit`/`offset`/`orderBy` are NOT applied on this path. | --- @@ -249,7 +249,7 @@ Type: `string` | **function** | `Enum<'row_number' \| 'rank' \| 'dense_rank' \| 'percent_rank' \| 'lag' \| 'lead' \| 'first_value' \| 'last_value' \| 'sum' \| 'avg' \| 'count' \| 'min' \| 'max'>` | ✅ | Window function name | | **field** | `string` | optional | Field to operate on (for aggregate window functions) | | **alias** | `string` | ✅ | Result column alias | -| **over** | `Object` | ✅ | Window specification (OVER clause) | +| **over** | `{ partitionBy?: string[]; orderBy?: { field: string; order: Enum<'asc' \| 'desc'> }[]; frame?: object }` | ✅ | Window specification (OVER clause) | --- @@ -261,8 +261,8 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **partitionBy** | `string[]` | optional | PARTITION BY fields | -| **orderBy** | `Object[]` | optional | ORDER BY specification | -| **frame** | `Object` | optional | Window frame specification | +| **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | ORDER BY specification | +| **frame** | `{ type?: Enum<'rows' \| 'range'>; start?: string; end?: string }` | optional | Window frame specification | --- diff --git a/content/docs/references/data/seed-loader.mdx b/content/docs/references/data/seed-loader.mdx index 6986738a48..289787b32e 100644 --- a/content/docs/references/data/seed-loader.mdx +++ b/content/docs/references/data/seed-loader.mdx @@ -61,7 +61,7 @@ Complete object dependency graph for seed data loading | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **nodes** | `Object[]` | ✅ | All objects in the dependency graph | +| **nodes** | `{ object: string; dependsOn: string[]; references: { field: string; targetObject: string; targetField: string; fieldType: Enum<'lookup' \| 'master_detail' \| 'user'> }[] }[]` | ✅ | All objects in the dependency graph | | **insertOrder** | `string[]` | ✅ | Topologically sorted insert order | | **circularDependencies** | `string[][]` | ✅ | Circular dependency chains (e.g., [["a", "b", "a"]]) | @@ -78,7 +78,7 @@ Object node in the seed data dependency graph | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object name (snake_case) | | **dependsOn** | `string[]` | ✅ | Objects this object depends on | -| **references** | `Object[]` | ✅ | Field-level reference details | +| **references** | `{ field: string; targetObject: string; targetField: string; fieldType: Enum<'lookup' \| 'master_detail' \| 'user'> }[]` | ✅ | Field-level reference details | --- @@ -126,8 +126,8 @@ Identity context for resolving os.user / os.org in seed CEL values | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **user** | `Object` | optional | Subject bound to os.user in seed CEL expressions | -| **org** | `Object` | optional | Organization bound to os.org in seed CEL expressions | +| **user** | `{ id: string; role?: string; email?: string }` | optional | Subject bound to os.user in seed CEL expressions | +| **org** | `{ id: string; tier?: string }` | optional | Organization bound to os.org in seed CEL expressions | --- @@ -149,7 +149,7 @@ Result of loading a single dataset | **total** | `integer` | ✅ | Total records in dataset | | **referencesResolved** | `integer` | ✅ | References resolved via externalId | | **referencesDeferred** | `integer` | ✅ | References deferred to second pass | -| **errors** | `Object[]` | ✅ | Reference resolution errors | +| **errors** | `{ sourceObject: string; field: string; targetObject: string; targetField: string; … }[]` | ✅ | Reference resolution errors | --- @@ -170,7 +170,7 @@ Seed data loader configuration | **transaction** | `boolean` | ✅ | Wrap entire load in a transaction (all-or-nothing) | | **env** | `Enum<'prod' \| 'dev' \| 'test'>` | optional | Only load datasets matching this environment | | **organizationId** | `string` | optional | Target organization id for per-tenant seed replay | -| **identity** | `Object` | optional | Identity bound to os.user / os.org when resolving CEL seed values | +| **identity** | `{ user?: object; org?: object }` | optional | Identity bound to os.user / os.org when resolving CEL seed values | --- @@ -183,8 +183,8 @@ Seed loader request with datasets and configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **seeds** | `Object[]` | ✅ | Seeds to load | -| **config** | `Object` | ✅ | Loader configuration | +| **seeds** | `{ object: string; externalId: string; mode: Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>; env: Enum<'prod' \| 'dev' \| 'test'>[]; … }[]` | ✅ | Seeds to load | +| **config** | `{ dryRun: boolean; haltOnError: boolean; multiPass: boolean; defaultMode: Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>; … }` | ✅ | Loader configuration | --- @@ -199,10 +199,10 @@ Complete seed loader result | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Overall success status | | **dryRun** | `boolean` | ✅ | Whether this was a dry-run | -| **dependencyGraph** | `Object` | ✅ | Object dependency graph | -| **results** | `Object[]` | ✅ | Per-object load results | -| **errors** | `Object[]` | ✅ | All reference resolution errors | -| **summary** | `Object` | ✅ | Summary statistics | +| **dependencyGraph** | `{ nodes: { object: string; dependsOn: string[]; references: { field: string; targetObject: string; targetField: string; fieldType: Enum<'lookup' \| 'master_detail' \| 'user'> }[] }[]; insertOrder: string[]; circularDependencies: string[][] }` | ✅ | Object dependency graph | +| **results** | `{ object: string; mode: Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>; inserted: integer; updated: integer; … }[]` | ✅ | Per-object load results | +| **errors** | `{ sourceObject: string; field: string; targetObject: string; targetField: string; … }[]` | ✅ | All reference resolution errors | +| **summary** | `{ objectsProcessed: integer; totalRecords: integer; totalInserted: integer; totalUpdated: integer; … }` | ✅ | Summary statistics | --- diff --git a/content/docs/references/data/validation.mdx b/content/docs/references/data/validation.mdx index f40770416d..4b1c90eb24 100644 --- a/content/docs/references/data/validation.mdx +++ b/content/docs/references/data/validation.mdx @@ -132,10 +132,10 @@ const result = ConditionalValidation.parse(data); | **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 | +| **type** | `'conditional'` | ✅ | | +| **when** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). e.g. P`record.type == 'enterprise'` | +| **then** | `{ name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| [ConditionalValidation](#conditionalvalidation)` | ✅ | Validation rule to apply when condition is true | +| **otherwise** | `{ name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| { name: string; label?: string; description?: string; active?: boolean; … } \| [ConditionalValidation](#conditionalvalidation)` | optional | Validation rule to apply when condition is false | --- @@ -155,8 +155,8 @@ const result = ConditionalValidation.parse(data); | **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` | +| **type** | `'cross_field'` | ✅ | | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL) comparing fields. e.g. P`record.end_date > record.start_date` | | **fields** | `string[]` | ✅ | Fields involved in the validation | @@ -177,7 +177,7 @@ const result = ConditionalValidation.parse(data); | **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | | **severity** | `Enum<'error' \| 'warning' \| 'info'>` | ✅ | | | **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | +| **type** | `'format'` | ✅ | | | **field** | `string` | ✅ | | | **regex** | `string` | optional | | | **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | @@ -200,7 +200,7 @@ const result = ConditionalValidation.parse(data); | **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | | **severity** | `Enum<'error' \| 'warning' \| 'info'>` | ✅ | | | **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | +| **type** | `'json_schema'` | ✅ | | | **field** | `string` | ✅ | JSON field to validate | | **schema** | `Record` | ✅ | JSON Schema object definition | @@ -222,8 +222,8 @@ const result = ConditionalValidation.parse(data); | **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` | +| **type** | `'script'` | ✅ | | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0` | --- @@ -243,7 +243,7 @@ const result = ConditionalValidation.parse(data); | **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | | **severity** | `Enum<'error' \| 'warning' \| 'info'>` | ✅ | | | **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | +| **type** | `'state_machine'` | ✅ | | | **field** | `string` | ✅ | State field (e.g. status) | | **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | @@ -273,8 +273,8 @@ This schema accepts one of the following structures: | **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` | +| **type** | `'script'` | ✅ | | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0` | --- @@ -295,7 +295,7 @@ This schema accepts one of the following structures: | **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` | ✅ | | +| **type** | `'state_machine'` | ✅ | | | **field** | `string` | ✅ | State field (e.g. status) | | **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | @@ -318,7 +318,7 @@ This schema accepts one of the following structures: | **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` | ✅ | | +| **type** | `'format'` | ✅ | | | **field** | `string` | ✅ | | | **regex** | `string` | optional | | | **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | @@ -342,8 +342,8 @@ This schema accepts one of the following structures: | **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` | +| **type** | `'cross_field'` | ✅ | | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL) comparing fields. e.g. P`record.end_date > record.start_date` | | **fields** | `string[]` | ✅ | Fields involved in the validation | --- @@ -365,7 +365,7 @@ This schema accepts one of the following structures: | **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` | ✅ | | +| **type** | `'json_schema'` | ✅ | | | **field** | `string` | ✅ | JSON field to validate | | **schema** | `Record` | ✅ | JSON Schema object definition | @@ -388,10 +388,10 @@ This schema accepts one of the following structures: | **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 | +| **type** | `'conditional'` | ✅ | | +| **when** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). e.g. P`record.type == 'enterprise'` | +| **then** | `[ValidationRule](#validationrule)` | ✅ | Validation rule to apply when condition is true | +| **otherwise** | `[ValidationRule](#validationrule)` | optional | Validation rule to apply when condition is false | --- diff --git a/content/docs/references/identity/eval-user.mdx b/content/docs/references/identity/eval-user.mdx index 142f58d4a5..15d42dff60 100644 --- a/content/docs/references/identity/eval-user.mdx +++ b/content/docs/references/identity/eval-user.mdx @@ -25,7 +25,7 @@ it is written. behavior is the footgun this eliminates. -@see docs/adr/0068-unified-user-context-and-built-in-identity-roles.md +See also: docs/adr/0068-unified-user-context-and-built-in-identity-roles.md **Source:** `packages/spec/src/identity/eval-user.zod.ts` diff --git a/content/docs/references/identity/scim.mdx b/content/docs/references/identity/scim.mdx index 6103f4d46d..0df9ae0e8a 100644 --- a/content/docs/references/identity/scim.mdx +++ b/content/docs/references/identity/scim.mdx @@ -71,9 +71,9 @@ de-provisioning, and synchronization. - **Google Workspace**: Google's identity management -@see https://datatracker.ietf.org/doc/html/rfc7643 +See also: https://datatracker.ietf.org/doc/html/rfc7643 -@see https://datatracker.ietf.org/doc/html/rfc7644 +See also: https://datatracker.ietf.org/doc/html/rfc7644 **Source:** `packages/spec/src/identity/scim.zod.ts` @@ -130,8 +130,8 @@ const result = SCIMAddress.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | ✅ | SCIM schema URIs (BulkRequest) | -| **operations** | `Object[]` | ✅ | Bulk operations to execute (minimum 1) | +| **schemas** | `'urn:ietf:params:scim:api:messages:2.0:BulkRequest'[]` | ✅ | SCIM schema URIs (BulkRequest) | +| **operations** | `{ method: Enum<'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>; path: string; bulkId?: string; data?: Record; … }[]` | ✅ | Bulk operations to execute (minimum 1) | | **failOnErrors** | `integer` | optional | Stop processing after this many errors | @@ -143,8 +143,8 @@ const result = SCIMAddress.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | ✅ | SCIM schema URIs (BulkResponse) | -| **operations** | `Object[]` | ✅ | Results for each bulk operation | +| **schemas** | `'urn:ietf:params:scim:api:messages:2.0:BulkResponse'[]` | ✅ | SCIM schema URIs (BulkResponse) | +| **operations** | `{ method: Enum<'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>; bulkId?: string; location?: string; status: string; … }[]` | ✅ | Results for each bulk operation | --- @@ -189,7 +189,7 @@ const result = SCIMAddress.parse(data); | **organization** | `string` | optional | Organization | | **division** | `string` | optional | Division | | **department** | `string` | optional | Department | -| **manager** | `Object` | optional | Manager reference | +| **manager** | `{ value: string; $ref?: string; displayName?: string }` | optional | Manager reference | --- @@ -218,8 +218,8 @@ const result = SCIMAddress.parse(data); | **id** | `string` | optional | Unique resource identifier | | **externalId** | `string` | optional | External identifier from client system | | **displayName** | `string` | ✅ | Group display name (REQUIRED) | -| **members** | `Object[]` | optional | Group members | -| **meta** | `Object` | optional | Resource metadata | +| **members** | `{ value: string; $ref?: string; type?: Enum<'User' \| 'Group'>; display?: string }[]` | optional | Group members | +| **meta** | `{ resourceType?: string; created?: string; lastModified?: string; location?: string; … }` | optional | Resource metadata | --- @@ -246,7 +246,7 @@ const result = SCIMAddress.parse(data); | :--- | :--- | :--- | :--- | | **schemas** | `string[]` | ✅ | SCIM schema URIs | | **totalResults** | `integer` | ✅ | Total results count | -| **Resources** | `Object \| Object \| Record[]` | ✅ | Resources array (Users, Groups, or custom resources) | +| **Resources** | `{ schemas: string[]; id?: string; externalId?: string; userName: string; … } \| { schemas: string[]; id?: string; externalId?: string; displayName: string; … } \| Record[]` | ✅ | Resources array (Users, Groups, or custom resources) | | **startIndex** | `integer` | optional | Start index (1-based) | | **itemsPerPage** | `integer` | optional | Items per page | @@ -318,7 +318,7 @@ const result = SCIMAddress.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **schemas** | `string[]` | ✅ | SCIM schema URIs | -| **Operations** | `Object[]` | ✅ | Patch operations | +| **Operations** | `{ op: Enum<'add' \| 'remove' \| 'replace'>; path?: string; value?: any }[]` | ✅ | Patch operations | --- @@ -347,7 +347,7 @@ const result = SCIMAddress.parse(data); | **id** | `string` | optional | Unique resource identifier | | **externalId** | `string` | optional | External identifier from client system | | **userName** | `string` | ✅ | Unique username (REQUIRED) | -| **name** | `Object` | optional | Structured name components | +| **name** | `{ formatted?: string; familyName?: string; givenName?: string; middleName?: string; … }` | optional | Structured name components | | **displayName** | `string` | optional | Display name for UI | | **nickName** | `string` | optional | Nickname | | **profileUrl** | `string` | optional | Profile page URL | @@ -358,17 +358,17 @@ const result = SCIMAddress.parse(data); | **timezone** | `string` | optional | Timezone | | **active** | `boolean` | ✅ | Account active status | | **password** | `string` | optional | Password (write-only) | -| **emails** | `Object[]` | optional | Email addresses | -| **phoneNumbers** | `Object[]` | optional | Phone numbers | -| **ims** | `Object[]` | optional | IM addresses | -| **photos** | `Object[]` | optional | Photo URLs | -| **addresses** | `Object[]` | optional | Physical addresses | -| **groups** | `Object[]` | optional | Group memberships | -| **entitlements** | `Object[]` | optional | Entitlements | -| **roles** | `Object[]` | optional | Roles | -| **x509Certificates** | `Object[]` | optional | X509 certificates | -| **meta** | `Object` | optional | Resource metadata | -| **urn:ietf:params:scim:schemas:extension:enterprise:2.0:User** | `Object` | optional | Enterprise user attributes | +| **emails** | `{ value: string; type?: Enum<'work' \| 'home' \| 'other'>; display?: string; primary: boolean }[]` | optional | Email addresses | +| **phoneNumbers** | `{ value: string; type?: Enum<'work' \| 'home' \| 'mobile' \| 'fax' \| 'pager' \| 'other'>; display?: string; primary: boolean }[]` | optional | Phone numbers | +| **ims** | `{ value: string; type?: string; primary?: boolean }[]` | optional | IM addresses | +| **photos** | `{ value: string; type?: Enum<'photo' \| 'thumbnail'>; primary?: boolean }[]` | optional | Photo URLs | +| **addresses** | `{ formatted?: string; streetAddress?: string; locality?: string; region?: string; … }[]` | optional | Physical addresses | +| **groups** | `{ value: string; $ref?: string; display?: string; type?: Enum<'direct' \| 'indirect'> }[]` | optional | Group memberships | +| **entitlements** | `{ value: string; type?: string; primary?: boolean }[]` | optional | Entitlements | +| **roles** | `{ value: string; type?: string; primary?: boolean }[]` | optional | Roles | +| **x509Certificates** | `{ value: string; type?: string; primary?: boolean }[]` | optional | X509 certificates | +| **meta** | `{ resourceType?: string; created?: string; lastModified?: string; location?: string; … }` | optional | Resource metadata | +| **urn:ietf:params:scim:schemas:extension:enterprise:2.0:User** | `{ employeeNumber?: string; costCenter?: string; organization?: string; division?: string; … }` | optional | Enterprise user attributes | --- diff --git a/content/docs/references/integration/connector-auth.mdx b/content/docs/references/integration/connector-auth.mdx index c7d3f2fbb3..ac2912aaae 100644 --- a/content/docs/references/integration/connector-auth.mdx +++ b/content/docs/references/integration/connector-auth.mdx @@ -27,7 +27,7 @@ const result = ConnectorInstanceAPIKeyAuth.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'api-key'` | ✅ | | | **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). | @@ -49,7 +49,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'none'` | ✅ | | --- @@ -61,7 +61,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'bearer'` | ✅ | | | **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. | --- @@ -74,7 +74,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'api-key'` | ✅ | | | **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). | @@ -89,7 +89,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'basic'` | ✅ | | | **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. | @@ -104,7 +104,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'basic'` | ✅ | | | **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. | @@ -117,7 +117,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'bearer'` | ✅ | | | **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. | @@ -129,7 +129,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'none'` | ✅ | | --- diff --git a/content/docs/references/integration/connector.mdx b/content/docs/references/integration/connector.mdx index 5ab6c77508..0603e8c249 100644 --- a/content/docs/references/integration/connector.mdx +++ b/content/docs/references/integration/connector.mdx @@ -67,7 +67,7 @@ a generic executor (connector-openapi / connector-mcp) materializes at boot are tracked in #2977 (ADR-0097). -Authentication is now imported from the canonical auth/config.zod.ts. +Authentication is now imported from the canonical `auth/config.zod.ts`. ## When to Use This Layer @@ -95,17 +95,17 @@ Authentication is now imported from the canonical auth/config.zod.ts. **When to downgrade:** -- Simple field sync → Use [Simple Sync](../automation/sync.zod.ts) +- Simple field sync → Use [Simple Sync](/docs/references/automation/sync) -- Data transformation only → Use [ETL Pipeline](../automation/etl.zod.ts) +- Data transformation only → Use [ETL Pipeline](/docs/references/automation/etl) -@see [../automation/sync.zod.ts](../automation/sync.zod.ts) for Level 1 (simple sync) +See also: [../[automation/sync.zod.ts](/docs/references/automation/sync)](/docs/references/automation/sync) for Level 1 (simple sync) -@see [../automation/etl.zod.ts](../automation/etl.zod.ts) for Level 2 (data engineering) +See also: [../[automation/etl.zod.ts](/docs/references/automation/etl)](/docs/references/automation/etl) for Level 2 (data engineering) ## When to use Integration Connector vs. Trigger Registry? -**Use `integration/connector.zod.ts` when:** +**Use `[integration/connector.zod.ts](/docs/references/integration/connector)` when:** - Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) @@ -119,7 +119,7 @@ Authentication is now imported from the canonical auth/config.zod.ts. - Need comprehensive retry strategies and error handling -**Use `automation/trigger-registry.zod.ts` when:** +**Use `[automation/trigger-registry.zod.ts](/docs/references/automation/trigger-registry)` when:** - Building simple automation triggers (e.g., "when Slack message received, create task") @@ -129,7 +129,7 @@ Authentication is now imported from the canonical auth/config.zod.ts. - Quick setup with minimal configuration -@see ../../automation/trigger-registry.zod.ts for lightweight automation triggers +See also: ../../[automation/trigger-registry.zod.ts](/docs/references/automation/trigger-registry) for lightweight automation triggers **Source:** `packages/spec/src/integration/connector.zod.ts` @@ -176,23 +176,23 @@ Circuit breaker configuration | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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-0097). | | **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: object }` | optional | Health and resilience configuration | | **metadata** | `Record` | optional | Custom connector metadata | @@ -221,8 +221,8 @@ Connector health configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **healthCheck** | `Object` | optional | Health check configuration | -| **circuitBreaker** | `Object` | optional | Circuit breaker configuration | +| **healthCheck** | `{ enabled: boolean; intervalMs: number; timeoutMs: number; endpoint?: string; … }` | optional | Health check configuration | +| **circuitBreaker** | `{ enabled: boolean; failureThreshold: number; resetTimeoutMs: number; halfOpenMaxRequests: number; … }` | optional | Circuit breaker configuration | --- @@ -280,7 +280,7 @@ Connector type | :--- | :--- | :--- | :--- | | **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 * * *` | +| **schedule** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -302,23 +302,23 @@ Connector type | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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-0097). | | **providerConfig** | `Record` | optional | Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: object }` | optional | Health and resilience configuration | | **metadata** | `Record` | optional | Custom connector metadata | @@ -350,7 +350,7 @@ Error mapping configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **rules** | `Object[]` | ✅ | Error mapping rules | +| **rules** | `{ sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]` | ✅ | Error mapping rules | | **defaultCategory** | `Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>` | ✅ | Default category for unmapped errors | | **unmappedBehavior** | `Enum<'passthrough' \| 'generic_error' \| 'throw'>` | ✅ | What to do with unmapped errors | | **logUnmapped** | `boolean` | ✅ | Log unmapped errors | @@ -473,8 +473,8 @@ Synchronization strategy | **body** | `any` | optional | Request body payload (if not using default record data) | | **payloadFields** | `string[]` | optional | Fields to include. Empty = All | | **includeSession** | `boolean` | ✅ | Include user session info | -| **authentication** | `Object` | optional | Authentication configuration | -| **retryPolicy** | `Object` | optional | Retry policy configuration | +| **authentication** | `{ type: Enum<'none' \| 'bearer' \| 'basic' \| 'api-key'>; credentials?: Record }` | optional | Authentication configuration | +| **retryPolicy** | `{ maxRetries: integer; backoffStrategy: Enum<'exponential' \| 'linear' \| 'fixed'>; initialDelayMs: integer; maxDelayMs: integer }` | optional | Retry policy configuration | | **timeoutMs** | `integer` | ✅ | Request timeout in milliseconds | | **secret** | `string` | optional | Signing secret for HMAC signature verification | | **isActive** | `boolean` | ✅ | Whether webhook is active | diff --git a/content/docs/references/integration/http.mdx b/content/docs/references/integration/http.mdx index d9ae601891..17663c9578 100644 --- a/content/docs/references/integration/http.mdx +++ b/content/docs/references/integration/http.mdx @@ -32,7 +32,7 @@ const result = RateLimitConfig.parse(data); | **windowSeconds** | `number` | ✅ | Time window in seconds | | **burstCapacity** | `number` | optional | Burst capacity | | **respectUpstreamLimits** | `boolean` | ✅ | Respect external rate limit headers | -| **rateLimitHeaders** | `Object` | optional | Custom rate limit headers | +| **rateLimitHeaders** | `{ remaining: string; limit: string; reset: string }` | optional | Custom rate limit headers | --- diff --git a/content/docs/references/integration/mapping.mdx b/content/docs/references/integration/mapping.mdx index 1174c93b80..f97bbbd7c1 100644 --- a/content/docs/references/integration/mapping.mdx +++ b/content/docs/references/integration/mapping.mdx @@ -29,7 +29,7 @@ const result = FieldMapping.parse(data); | :--- | :--- | :--- | :--- | | **source** | `string` | ✅ | Source field name | | **target** | `string` | ✅ | Target field name | -| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | +| **transform** | `{ type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }` | 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 | diff --git a/content/docs/references/integration/misc.mdx b/content/docs/references/integration/misc.mdx index 32b1ea3b13..fbd749da18 100644 --- a/content/docs/references/integration/misc.mdx +++ b/content/docs/references/integration/misc.mdx @@ -89,33 +89,33 @@ Message acknowledgment mode | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Unique connector identifier | | **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | +| **type** | `'database'` | ✅ | | | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: 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 | +| **connectionConfig** | `{ host: string; port: number; database: string; username: string; … }` | ✅ | Database connection configuration | +| **poolConfig** | `{ min?: number; max?: number; idleTimeoutMs?: number; connectionTimeoutMs?: number; … }` | optional | Connection pool configuration | +| **sslConfig** | `{ enabled?: boolean; rejectUnauthorized?: boolean; ca?: string; cert?: string; … }` | optional | SSL/TLS configuration | +| **tables** | `{ name: string; label: string; schema?: string; tableName: string; … }[]` | ✅ | Tables to sync | +| **cdcConfig** | `{ enabled?: boolean; method: Enum<'log_based' \| 'trigger_based' \| 'query_based' \| 'custom'>; slotName?: string; publicationName?: string; … }` | optional | CDC configuration | +| **readReplicaConfig** | `{ enabled?: boolean; hosts: { host: string; port: number; weight?: number }[] }` | optional | Read replica configuration | | **queryTimeoutMs** | `number` | optional | Query timeout in ms | | **enableQueryLogging** | `boolean` | optional | Enable SQL query logging | @@ -151,7 +151,7 @@ Message acknowledgment mode | **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 | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Table-specific field mappings | | **whereClause** | `string` | optional | SQL WHERE clause for filtering | @@ -181,7 +181,7 @@ Message delivery guarantee | **enablePreview** | `boolean` | ✅ | Enable preview deployments | | **previewComments** | `boolean` | ✅ | Post preview URLs in PR comments | | **productionProtection** | `boolean` | ✅ | Require approval for production deployments | -| **deployHooks** | `Object[]` | optional | Deploy hooks | +| **deployHooks** | `{ name: string; url: string; branch?: string }[]` | optional | Deploy hooks | --- @@ -208,7 +208,7 @@ Message delivery guarantee | :--- | :--- | :--- | :--- | | **domain** | `string` | ✅ | Domain name (e.g., app.example.com) | | **httpsRedirect** | `boolean` | ✅ | Redirect HTTP to HTTPS | -| **customCertificate** | `Object` | optional | Custom SSL certificate | +| **customCertificate** | `{ cert: string; key: string; ca?: string }` | optional | Custom SSL certificate | | **gitBranch** | `string` | optional | Git branch to deploy to this domain | @@ -296,35 +296,35 @@ File access pattern | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Unique connector identifier | | **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | +| **type** | `'file_storage'` | ✅ | | | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: 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 | +| **storageConfig** | `{ endpoint?: string; region?: string; pathStyle?: boolean }` | optional | Storage configuration | +| **buckets** | `{ name: string; label: string; bucketName: string; region?: string; … }[]` | ✅ | Buckets/containers to sync | +| **metadataConfig** | `{ extractMetadata?: boolean; metadataFields?: Enum<'content_type' \| 'file_size' \| 'last_modified' \| 'etag' \| 'checksum' \| 'creator' \| 'created_at' \| 'custom'>[]; customMetadata?: Record }` | optional | Metadata extraction configuration | +| **multipartConfig** | `{ enabled?: boolean; partSize?: number; maxConcurrentParts?: number; threshold?: number }` | optional | Multipart upload configuration | +| **versioningConfig** | `{ enabled?: boolean; maxVersions?: number; retentionDays?: number }` | optional | File versioning configuration | +| **encryption** | `{ enabled?: boolean; algorithm?: Enum<'AES256' \| 'aws:kms' \| 'custom'>; kmsKeyId?: string }` | optional | Encryption configuration | +| **lifecyclePolicy** | `{ enabled?: boolean; deleteAfterDays?: number; archiveAfterDays?: number }` | optional | Lifecycle policy | +| **contentProcessing** | `{ extractText?: boolean; generateThumbnails?: boolean; thumbnailSizes?: { width: number; height: number }[]; virusScan?: boolean }` | optional | Content processing configuration | | **bufferSize** | `number` | optional | Buffer size in bytes | | **transferAcceleration** | `boolean` | optional | Enable transfer acceleration | @@ -404,34 +404,34 @@ File storage provider type | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Unique connector identifier | | **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | +| **type** | `'saas'` | ✅ | | | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: 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 | +| **repositories** | `{ owner: string; name: string; defaultBranch?: string; autoMerge?: boolean; … }[]` | ✅ | Repositories to manage | +| **commitConfig** | `{ authorName?: string; authorEmail?: string; signCommits?: boolean; messageTemplate?: string; … }` | optional | Commit configuration | +| **pullRequestConfig** | `{ titleTemplate?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; bodyTemplate?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; defaultReviewers?: string[]; defaultAssignees?: string[]; … }` | optional | Pull request configuration | +| **workflows** | `{ name: string; path: string; enabled?: boolean; triggers?: Enum<'push' \| 'pull_request' \| 'release' \| 'schedule' \| 'workflow_dispatch' \| 'repository_dispatch'>[]; … }[]` | optional | GitHub Actions workflows | +| **releaseConfig** | `{ tagPattern?: string; semanticVersioning?: boolean; autoReleaseNotes?: boolean; releaseNameTemplate?: string; … }` | optional | Release configuration | +| **issueTracking** | `{ enabled?: boolean; defaultLabels?: string[]; templatePaths?: string[]; autoAssign?: boolean; … }` | 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 | @@ -448,7 +448,7 @@ File storage provider type | **defaultLabels** | `string[]` | optional | Default issue labels | | **templatePaths** | `string[]` | optional | Issue template paths | | **autoAssign** | `boolean` | ✅ | Auto-assign issues | -| **autoCloseStale** | `Object` | optional | Auto-close stale issues configuration | +| **autoCloseStale** | `{ enabled: boolean; daysBeforeStale: integer; daysBeforeClose: integer; staleLabel: string }` | optional | Auto-close stale issues configuration | --- @@ -471,8 +471,8 @@ GitHub provider type | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **titleTemplate** | `string \| Object` | optional | PR title template — supports `{{var}`} interpolation | -| **bodyTemplate** | `string \| Object` | optional | PR body template — supports `{{var}`} interpolation | +| **titleTemplate** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | PR title template — supports `{{var}`} interpolation | +| **bodyTemplate** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -508,7 +508,7 @@ GitHub provider type | **name** | `string` | ✅ | Repository name | | **defaultBranch** | `string` | ✅ | Default branch name | | **autoMerge** | `boolean` | ✅ | Enable auto-merge for pull requests | -| **branchProtection** | `Object` | optional | Branch protection configuration | +| **branchProtection** | `{ requiredReviewers: integer; requireStatusChecks: boolean; enforceAdmins: boolean; allowForcePushes: boolean; … }` | optional | Branch protection configuration | | **topics** | `string[]` | optional | Repository topics | @@ -537,33 +537,33 @@ GitHub provider type | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Unique connector identifier | | **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | +| **type** | `'message_queue'` | ✅ | | | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: object }` | optional | Health and resilience configuration | | **metadata** | `Record` | optional | Custom connector metadata | -| **brokerConfig** | `Object` | ✅ | Broker connection configuration | -| **topics** | `Object[]` | ✅ | Topics/queues to sync | +| **brokerConfig** | `{ brokers: string[]; clientId?: string; connectionTimeoutMs?: number; requestTimeoutMs?: number }` | ✅ | Broker connection configuration | +| **topics** | `{ name: string; label: string; topicName: string; enabled?: boolean; … }[]` | ✅ | 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 | +| **sslConfig** | `{ enabled?: boolean; rejectUnauthorized?: boolean; ca?: string; cert?: string; … }` | optional | SSL/TLS configuration | +| **saslConfig** | `{ mechanism: Enum<'plain' \| 'scram-sha-256' \| 'scram-sha-512' \| 'aws'>; username?: string; password?: string }` | optional | SASL authentication configuration | +| **schemaRegistry** | `{ url: string; auth?: object }` | optional | Schema registry configuration | | **preserveOrder** | `boolean` | optional | Preserve message ordering | | **enableMetrics** | `boolean` | optional | Enable message queue metrics | | **enableTracing** | `boolean` | optional | Enable distributed tracing | @@ -598,33 +598,33 @@ GitHub provider type | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Unique connector identifier | | **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | +| **type** | `'saas'` | ✅ | | | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: 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 | +| **apiVersion** | `{ version: string; isDefault?: boolean; deprecationDate?: string; sunsetDate?: string }` | optional | API version configuration | +| **objectTypes** | `{ name: string; label: string; apiName: string; enabled?: boolean; … }[]` | ✅ | Syncable object types | +| **oauthSettings** | `{ scopes: string[]; refreshTokenUrl?: string; revokeTokenUrl?: string; autoRefresh?: boolean }` | optional | OAuth-specific configuration | +| **paginationConfig** | `{ type?: Enum<'cursor' \| 'offset' \| 'page'>; defaultPageSize?: number; maxPageSize?: number }` | optional | Pagination configuration | +| **sandboxConfig** | `{ enabled?: boolean; baseUrl?: string }` | optional | Sandbox environment configuration | | **customHeaders** | `Record` | optional | Custom HTTP headers for all requests | @@ -643,7 +643,7 @@ GitHub provider type | **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 | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Object-specific field mappings | --- @@ -698,7 +698,7 @@ SaaS provider type | **enabled** | `boolean` | ✅ | Enable sync for this bucket | | **prefix** | `string` | optional | Prefix/path within bucket | | **accessPattern** | `Enum<'public_read' \| 'private' \| 'authenticated_read' \| 'bucket_owner_read' \| 'bucket_owner_full'>` | optional | Access pattern | -| **fileFilters** | `Object` | optional | File filter configuration | +| **fileFilters** | `{ includePatterns?: string[]; excludePatterns?: string[]; minFileSize?: number; maxFileSize?: number; … }` | optional | File filter configuration | --- @@ -717,11 +717,11 @@ SaaS provider type | **messageFormat** | `Enum<'json' \| 'xml' \| 'protobuf' \| 'avro' \| 'text' \| 'binary'>` | ✅ | Message format/serialization | | **partitions** | `number` | optional | Number of partitions (for Kafka) | | **replicationFactor** | `number` | optional | Replication factor (for Kafka) | -| **consumerConfig** | `Object` | optional | Consumer-specific configuration | -| **producerConfig** | `Object` | optional | Producer-specific configuration | -| **dlqConfig** | `Object` | optional | Dead letter queue configuration | +| **consumerConfig** | `{ enabled: boolean; consumerGroup?: string; concurrency: number; prefetchCount: number; … }` | optional | Consumer-specific configuration | +| **producerConfig** | `{ enabled: boolean; acks: Enum<'0' \| '1' \| 'all'>; compressionType: Enum<'none' \| 'gzip' \| 'snappy' \| 'lz4' \| 'zstd'>; batchSize: number; … }` | optional | Producer-specific configuration | +| **dlqConfig** | `{ enabled: boolean; queueName: string; maxRetries: number; retryDelayMs: number }` | optional | Dead letter queue configuration | | **routingKey** | `string` | optional | Routing key pattern | -| **messageFilter** | `Object` | optional | Message filter criteria | +| **messageFilter** | `{ headers?: Record; attributes?: Record }` | optional | Message filter criteria | --- @@ -734,31 +734,31 @@ SaaS provider type | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Unique connector identifier | | **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | +| **type** | `'saas'` | ✅ | | | **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. | +| **authentication** | `{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }` | 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, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`. | -| **auth** | `Object \| Object \| Object \| Object` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | -| **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 | +| **auth** | `{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }` | optional | Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097). | +| **actions** | `{ key: string; label: string; description?: string; inputSchema?: Record; … }[]` | optional | | +| **triggers** | `{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]` | optional | | +| **syncConfig** | `{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }` | optional | Data sync configuration | +| **fieldMappings** | `{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }; defaultValue?: any; … }[]` | optional | Field mapping rules | +| **webhooks** | `{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]; … }[]` | optional | Webhook configurations | +| **rateLimitConfig** | `{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }` | optional | Rate limiting configuration | +| **retryConfig** | `{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }` | 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 | +| **errorMapping** | `{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }` | optional | Error mapping configuration | +| **health** | `{ healthCheck?: object; circuitBreaker?: 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 | +| **team** | `{ teamId?: string; teamName?: string }` | optional | Vercel team configuration | +| **projects** | `{ name: string; framework?: Enum<'nextjs' \| 'react' \| 'vue' \| 'nuxtjs' \| 'gatsby' \| 'remix' \| 'astro' \| 'sveltekit' \| 'solid' \| 'angular' \| 'static' \| 'other'>; gitRepository?: object; buildConfig?: object; … }[]` | ✅ | Vercel projects | +| **monitoring** | `{ enableWebAnalytics?: boolean; enableSpeedInsights?: boolean; logDrains?: { name: string; url: string; headers?: Record; sources?: Enum<'static' \| 'lambda' \| 'edge'>[] }[] }` | 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 | @@ -795,7 +795,7 @@ Frontend framework | :--- | :--- | :--- | :--- | | **enableWebAnalytics** | `boolean` | ✅ | Enable Vercel Web Analytics | | **enableSpeedInsights** | `boolean` | ✅ | Enable Vercel Speed Insights | -| **logDrains** | `Object[]` | optional | Log drains configuration | +| **logDrains** | `{ name: string; url: string; headers?: Record; sources?: Enum<'static' \| 'lambda' \| 'edge'>[] }[]` | optional | Log drains configuration | --- @@ -808,12 +808,12 @@ Frontend framework | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Vercel project name | | **framework** | `Enum<'nextjs' \| 'react' \| 'vue' \| 'nuxtjs' \| 'gatsby' \| 'remix' \| 'astro' \| 'sveltekit' \| 'solid' \| 'angular' \| 'static' \| 'other'>` | optional | Frontend framework | -| **gitRepository** | `Object` | optional | Git repository configuration | -| **buildConfig** | `Object` | optional | Build configuration | -| **deploymentConfig** | `Object` | optional | Deployment configuration | -| **domains** | `Object[]` | optional | Custom domains | -| **environmentVariables** | `Object[]` | optional | Environment variables | -| **edgeFunctions** | `Object[]` | optional | Edge functions | +| **gitRepository** | `{ type: Enum<'github' \| 'gitlab' \| 'bitbucket'>; repo: string; productionBranch: string; autoDeployProduction: boolean; … }` | optional | Git repository configuration | +| **buildConfig** | `{ buildCommand?: string; outputDirectory?: string; installCommand?: string; devCommand?: string; … }` | optional | Build configuration | +| **deploymentConfig** | `{ autoDeployment: boolean; regions?: Enum<'iad1' \| 'sfo1' \| 'gru1' \| 'lhr1' \| 'fra1' \| 'sin1' \| 'syd1' \| 'hnd1' \| 'icn1'>[]; enablePreview: boolean; previewComments: boolean; … }` | optional | Deployment configuration | +| **domains** | `{ domain: string; httpsRedirect: boolean; customCertificate?: object; gitBranch?: string }[]` | optional | Custom domains | +| **environmentVariables** | `{ key: string; value: string; target: Enum<'production' \| 'preview' \| 'development'>[]; isSecret: boolean; … }[]` | optional | Environment variables | +| **edgeFunctions** | `{ name: string; path: string; regions?: string[]; memoryLimit: integer; … }[]` | optional | Edge functions | | **rootDirectory** | `string` | optional | Root directory (for monorepos) | diff --git a/content/docs/references/kernel/cli-extension.mdx b/content/docs/references/kernel/cli-extension.mdx index 91eb9d47d7..08657398d0 100644 --- a/content/docs/references/kernel/cli-extension.mdx +++ b/content/docs/references/kernel/cli-extension.mdx @@ -136,7 +136,7 @@ oclif plugin configuration section | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **commands** | `Object` | optional | Command discovery configuration | +| **commands** | `{ strategy?: Enum<'pattern' \| 'explicit' \| 'single'>; target?: string; glob?: string }` | optional | Command discovery configuration | | **topicSeparator** | `string` | optional | Character separating topic and command names | diff --git a/content/docs/references/kernel/context.mdx b/content/docs/references/kernel/context.mdx index 1ad09aa2d6..86ec362061 100644 --- a/content/docs/references/kernel/context.mdx +++ b/content/docs/references/kernel/context.mdx @@ -39,7 +39,7 @@ const result = KernelContext.parse(data); | **workspaceRoot** | `string` | optional | Workspace root if different from cwd | | **startTime** | `integer` | ✅ | Boot timestamp (ms) | | **features** | `Record` | ✅ | Global feature toggles | -| **previewMode** | `Object` | optional | Preview/demo mode configuration (used when mode is "preview") | +| **previewMode** | `{ autoLogin: boolean; simulatedRole: Enum<'admin' \| 'user' \| 'viewer'>; simulatedUserName: string; readOnly: boolean; … }` | optional | Preview/demo mode configuration (used when mode is "preview") | --- @@ -91,12 +91,12 @@ Tenant-aware kernel runtime context | **workspaceRoot** | `string` | optional | Workspace root if different from cwd | | **startTime** | `integer` | ✅ | Boot timestamp (ms) | | **features** | `Record` | ✅ | Global feature toggles | -| **previewMode** | `Object` | optional | Preview/demo mode configuration (used when mode is "preview") | +| **previewMode** | `{ autoLogin: boolean; simulatedRole: Enum<'admin' \| 'user' \| 'viewer'>; simulatedUserName: string; readOnly: boolean; … }` | optional | Preview/demo mode configuration (used when mode is "preview") | | **tenantId** | `string` | ✅ | Resolved tenant identifier | | **tenantPlan** | `Enum<'free' \| 'pro' \| 'enterprise'>` | ✅ | Tenant subscription plan | | **tenantRegion** | `string` | optional | Tenant deployment region | | **tenantDbUrl** | `string` | ✅ | Tenant database connection URL | -| **tenantQuotas** | `Object` | optional | Tenant resource quotas | +| **tenantQuotas** | `{ maxUsers?: integer; maxStorage?: integer; apiRateLimit?: integer; maxObjects?: integer; … }` | optional | Tenant resource quotas | --- diff --git a/content/docs/references/kernel/dependency-resolution.mdx b/content/docs/references/kernel/dependency-resolution.mdx index fe99584503..88b902c943 100644 --- a/content/docs/references/kernel/dependency-resolution.mdx +++ b/content/docs/references/kernel/dependency-resolution.mdx @@ -63,9 +63,9 @@ Complete dependency resolution result | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **dependencies** | `Object[]` | ✅ | Resolution result for each dependency | +| **dependencies** | `{ packageId: string; requiredRange: string; resolvedVersion?: string; installedVersion?: string; … }[]` | ✅ | Resolution result for each dependency | | **canProceed** | `boolean` | ✅ | Whether installation can proceed | -| **requiredActions** | `Object[]` | ✅ | Actions required before proceeding | +| **requiredActions** | `{ type: Enum<'install' \| 'upgrade' \| 'confirm_conflict'>; packageId: string; description: string }[]` | ✅ | Actions required before proceeding | | **installOrder** | `string[]` | ✅ | Topologically sorted package IDs for installation | | **circularDependencies** | `string[][]` | optional | Circular dependency chains detected (e.g. [["A", "B", "A"]]) | diff --git a/content/docs/references/kernel/dev-plugin.mdx b/content/docs/references/kernel/dev-plugin.mdx index 7fd5a7c007..5e4955bf9a 100644 --- a/content/docs/references/kernel/dev-plugin.mdx +++ b/content/docs/references/kernel/dev-plugin.mdx @@ -70,9 +70,9 @@ const result = DevFixtureConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **preset** | `Enum<'minimal' \| 'standard' \| 'full'>` | ✅ | Base configuration preset | -| **services** | `Record` | optional | Per-service dev overrides keyed by service name | -| **fixtures** | `Object` | optional | Fixture data loading configuration | -| **tools** | `Object` | optional | Developer tooling settings | +| **services** | `Record; config?: Record }>` | optional | Per-service dev overrides keyed by service name | +| **fixtures** | `{ enabled: boolean; paths?: string[]; resetBeforeLoad: boolean; envFilter?: string[] }` | optional | Fixture data loading configuration | +| **tools** | `{ hotReload: boolean; requestInspector: boolean; dbExplorer: boolean; verboseLogging: boolean; … }` | optional | Developer tooling settings | | **port** | `integer` | ✅ | Port for the dev-tools dashboard | | **open** | `boolean` | ✅ | Auto-open dev dashboard in browser | | **seedAdminUser** | `boolean` | ✅ | Create a default admin user for development | diff --git a/content/docs/references/kernel/execution-context.mdx b/content/docs/references/kernel/execution-context.mdx index 62901fe4d0..23279e1a39 100644 --- a/content/docs/references/kernel/execution-context.mdx +++ b/content/docs/references/kernel/execution-context.mdx @@ -58,7 +58,7 @@ const result = ExecutionContext.parse(data); | **principalKind** | `Enum<'human' \| 'agent' \| 'service' \| 'guest' \| 'system'>` | optional | | | **audience** | `Enum<'internal' \| 'external'>` | optional | | | **posture** | `Enum<'PLATFORM_ADMIN' \| 'TENANT_ADMIN' \| 'MEMBER' \| 'EXTERNAL'>` | optional | ADR-0095 D2 posture rung — PLATFORM_ADMIN crosses the tenant wall where object posture permits; TENANT_ADMIN sees all rows in the org; MEMBER gets business RLS; EXTERNAL sees only explicitly shared rows. | -| **onBehalfOf** | `Object` | optional | | +| **onBehalfOf** | `{ userId: string; principalKind?: Enum<'human' \| 'agent' \| 'service' \| 'guest' \| 'system'> }` | optional | | | **permissions** | `string[]` | ✅ | | | **systemPermissions** | `string[]` | optional | | | **tabPermissions** | `Record>` | optional | | diff --git a/content/docs/references/kernel/feature.mdx b/content/docs/references/kernel/feature.mdx index 885c98a3d9..6ab5de7506 100644 --- a/content/docs/references/kernel/feature.mdx +++ b/content/docs/references/kernel/feature.mdx @@ -34,7 +34,7 @@ const result = FeatureFlag.parse(data); | **description** | `string` | optional | | | **enabled** | `boolean` | optional | Is globally enabled | | **strategy** | `Enum<'boolean' \| 'percentage' \| 'user_list' \| 'group' \| 'custom'>` | optional | | -| **conditions** | `Object` | optional | | +| **conditions** | `{ percentage?: number; users?: string[]; groups?: string[]; expression?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }` | optional | | | **environment** | `Enum<'dev' \| 'staging' \| 'prod' \| 'all'>` | optional | Environment validity | | **expiresAt** | `string` | optional | Feature flag expiration date | diff --git a/content/docs/references/kernel/manifest.mdx b/content/docs/references/kernel/manifest.mdx index 59b056571e..6bbc9257f2 100644 --- a/content/docs/references/kernel/manifest.mdx +++ b/content/docs/references/kernel/manifest.mdx @@ -55,19 +55,19 @@ const result = Manifest.parse(data); | **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) | +| **permissions** | `string[] \| { services?: string[]; hooks?: string[]; network?: string[]; fs?: string[] }` | 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 | +| **configuration** | `{ title?: string; properties: Record; default?: any; description?: string; required?: boolean; … }> }` | optional | Plugin configuration settings | +| **contributes** | `{ kinds?: { id: string; globs: string[]; description?: string }[]; events?: string[]; menus?: Record; themes?: { id: string; label: string; path: string }[]; … }` | optional | Platform contributions | +| **data** | `{ object: string; externalId?: string; mode?: Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>; env?: Enum<'prod' \| 'dev' \| 'test'>[]; … }[]` | optional | Initial seed data (prefer top-level data field) | +| **capabilities** | `{ implements?: { protocol: object; conformance?: Enum<'full' \| 'partial' \| 'experimental' \| 'deprecated'>; implementedFeatures?: string[]; features?: { name: string; enabled?: boolean; description?: string; sinceVersion?: string; … }[]; … }[]; provides?: { id: string; name: string; description?: string; version: object; … }[]; requires?: { pluginId: string; version: string; optional?: boolean; reason?: string; … }[]; extensionPoints?: { id: string; name: string; description?: string; type: Enum<'action' \| 'hook' \| 'widget' \| 'provider' \| 'transformer' \| 'validator' \| 'decorator'>; … }[]; … }` | 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`) | +| **navigationContributions** | `{ app: string; group?: string; priority?: integer; items: { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … }[] }[]` | optional | Navigation items this package contributes into apps owned by other packages | +| **loading** | `{ strategy?: Enum<'eager' \| 'lazy' \| 'parallel' \| 'deferred' \| 'on-demand'>; preload?: object; codeSplitting?: object; dynamicImport?: object; … }` | optional | Plugin loading and runtime behavior configuration | +| **engine** | `{ objectstack: string }` | optional | Platform compatibility requirements (legacy; superseded by `engines`) | +| **engines** | `{ platform?: string; protocol?: string }` | 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) | diff --git a/content/docs/references/kernel/metadata-customization.mdx b/content/docs/references/kernel/metadata-customization.mdx index 939358b4f8..55b6f2b7ee 100644 --- a/content/docs/references/kernel/metadata-customization.mdx +++ b/content/docs/references/kernel/metadata-customization.mdx @@ -136,9 +136,9 @@ const result = CustomizationOrigin.parse(data); | **success** | `boolean` | ✅ | Whether merge completed without unresolved conflicts | | **mergedMetadata** | `Record` | optional | Merged metadata result | | **updatedOverlay** | `Record` | optional | Updated overlay after merge | -| **conflicts** | `Object[]` | optional | Unresolved merge conflicts | -| **autoResolved** | `Object[]` | optional | Summary of auto-resolved changes | -| **stats** | `Object` | optional | | +| **conflicts** | `{ path: string; baseValue: any; incomingValue: any; customValue: any; … }[]` | optional | Unresolved merge conflicts | +| **autoResolved** | `{ path: string; resolution: string; description?: string }[]` | optional | Summary of auto-resolved changes | +| **stats** | `{ totalFields: integer; unchanged: integer; autoResolved: integer; conflicts: integer }` | optional | | --- @@ -172,7 +172,7 @@ const result = CustomizationOrigin.parse(data); | **tenantId** | `string` | optional | Tenant identifier | | **owner** | `string` | optional | Owner user ID for user-scope overlays | | **patch** | `Record` | ✅ | JSON Merge Patch payload (changed fields only) | -| **changes** | `Object[]` | optional | Field-level change tracking for conflict detection | +| **changes** | `{ path: string; originalValue?: any; currentValue: any; changedBy?: string; … }[]` | optional | Field-level change tracking for conflict detection | | **active** | `boolean` | ✅ | Whether this overlay is active | | **createdAt** | `string` | optional | | | **createdBy** | `string` | optional | | diff --git a/content/docs/references/kernel/metadata-loader.mdx b/content/docs/references/kernel/metadata-loader.mdx index 10e82a6ffd..1785ddb868 100644 --- a/content/docs/references/kernel/metadata-loader.mdx +++ b/content/docs/references/kernel/metadata-loader.mdx @@ -51,12 +51,12 @@ const result = MetadataFallbackStrategy.parse(data); | **fallback** | `Enum<'filesystem' \| 'memory' \| 'none'>` | ✅ | Fallback strategy when datasource is unavailable | | **rootDir** | `string` | optional | Root directory path | | **formats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Enabled formats | -| **cache** | `Object` | optional | Cache settings | +| **cache** | `{ enabled: boolean; ttl: integer; maxSize?: integer; databaseLoader?: object }` | optional | Cache settings | | **watch** | `boolean` | ✅ | Enable file watching | -| **watchOptions** | `Object` | optional | File watcher options | -| **validation** | `Object` | optional | Validation settings | +| **watchOptions** | `{ ignored?: string[]; persistent: boolean; ignoreInitial: boolean }` | optional | File watcher options | +| **validation** | `{ strict: boolean; throwOnError: boolean }` | optional | Validation settings | | **loaderOptions** | `Record` | optional | Loader-specific configuration | -| **persistence** | `Object` | optional | Persistence write gates | +| **persistence** | `{ writable: boolean; overlayWritable: boolean }` | optional | Persistence write gates | --- diff --git a/content/docs/references/kernel/metadata-persistence.mdx b/content/docs/references/kernel/metadata-persistence.mdx index 5ca6808c19..3121b9e765 100644 --- a/content/docs/references/kernel/metadata-persistence.mdx +++ b/content/docs/references/kernel/metadata-persistence.mdx @@ -45,7 +45,7 @@ const result = MetadataCollectionInfo.parse(data); | :--- | :--- | :--- | :--- | | **output** | `string` | ✅ | Output file path | | **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | optional | Export format | -| **filter** | `string \| Object` | optional | Filter items to export (CEL) | +| **filter** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -91,7 +91,7 @@ const result = MetadataCollectionInfo.parse(data); | **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) | +| **filter** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Filter predicate (CEL) | | **limit** | `integer` | optional | Maximum items to load | | **recursive** | `boolean` | optional | Search subdirectories | @@ -108,7 +108,7 @@ const result = MetadataCollectionInfo.parse(data); | **fromCache** | `boolean` | ✅ | Loaded from cache | | **notModified** | `boolean` | ✅ | Not modified since last request | | **etag** | `string` | optional | Entity tag | -| **stats** | `Object` | optional | Metadata statistics | +| **stats** | `{ size: integer; modifiedAt: string; etag: string; format: Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>; … }` | optional | Metadata statistics | | **loadTime** | `number` | optional | Load duration in ms | @@ -122,7 +122,7 @@ const result = MetadataCollectionInfo.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Loader identifier | | **protocol** | `Enum<'file:' \| 'http:' \| 's3:' \| 'datasource:' \| 'memory:'>` | ✅ | Protocol identifier | -| **capabilities** | `Object` | ✅ | Loader capabilities | +| **capabilities** | `{ read: boolean; write: boolean; watch: boolean; list: boolean }` | ✅ | Loader capabilities | | **supportedFormats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Supported formats | | **supportsWatch** | `boolean` | ✅ | Supports file watching | | **supportsWrite** | `boolean` | ✅ | Supports write operations | diff --git a/content/docs/references/kernel/metadata-plugin.mdx b/content/docs/references/kernel/metadata-plugin.mdx index ce00b845e1..976eea9b4a 100644 --- a/content/docs/references/kernel/metadata-plugin.mdx +++ b/content/docs/references/kernel/metadata-plugin.mdx @@ -57,11 +57,11 @@ cohesive plugin that "takes over" the entire platform's metadata management: ## References -- kernel/metadata-loader.zod.ts — Storage backend protocol +- [kernel/metadata-loader.zod.ts](/docs/references/kernel/metadata-loader) — Storage backend protocol -- kernel/metadata-customization.zod.ts — Overlay/merge protocol +- [kernel/metadata-customization.zod.ts](/docs/references/kernel/metadata-customization) — Overlay/merge protocol -- system/metadata-persistence.zod.ts — Database record format +- [system/metadata-persistence.zod.ts](/docs/references/system/metadata-persistence) — Database record format - contracts/metadata-service.ts — Service interface @@ -87,7 +87,7 @@ const result = MetadataBulkRegisterRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | Items to register | +| **items** | `{ type: string; name: string; data: Record; namespace?: string }[]` | ✅ | Items to register | | **continueOnError** | `boolean` | ✅ | Continue if individual item fails | | **validate** | `boolean` | ✅ | Validate before register | @@ -103,7 +103,7 @@ const result = MetadataBulkRegisterRequest.parse(data); | **total** | `integer` | ✅ | Total items processed | | **succeeded** | `integer` | ✅ | Successfully processed | | **failed** | `integer` | ✅ | Failed items | -| **errors** | `Object[]` | optional | Per-item errors | +| **errors** | `{ type: string; name: string; error: string }[]` | optional | Per-item errors | --- @@ -147,10 +147,10 @@ const result = MetadataBulkRegisterRequest.parse(data); | 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 | +| **storage** | `{ datasource?: string; tableName?: string; fallback?: Enum<'filesystem' \| 'memory' \| 'none'>; rootDir?: string; … }` | ✅ | Storage backend configuration | +| **customizationPolicies** | `{ metadataType: string; allowCustomization?: boolean; lockedFields?: string[]; customizableFields?: string[]; … }[]` | optional | Default customization policies per type | +| **mergeStrategy** | `{ defaultStrategy?: Enum<'keep-custom' \| 'accept-incoming' \| 'three-way-merge'>; alwaysAcceptIncoming?: string[]; alwaysKeepCustom?: string[]; autoResolveNonConflicting?: boolean }` | optional | Merge strategy for package upgrades | +| **additionalTypes** | `{ label: string; description?: string; filePatterns: string[]; supportsOverlay?: boolean; … }[]` | 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 | @@ -166,13 +166,13 @@ const result = MetadataBulkRegisterRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Metadata plugin ID | -| **name** | `string` | ✅ | Plugin name | +| **id** | `'com.objectstack.metadata'` | ✅ | Metadata plugin ID | +| **name** | `'ObjectStack Metadata Service'` | ✅ | Plugin name | | **version** | `string` | ✅ | Plugin version | -| **type** | `string` | ✅ | Plugin type | +| **type** | `'standard'` | ✅ | Plugin type | | **description** | `string` | optional | Plugin description | -| **capabilities** | `Object` | ✅ | Plugin capabilities | -| **config** | `Object` | optional | Plugin configuration | +| **capabilities** | `{ crud?: boolean; query?: boolean; overlay?: boolean; watch?: boolean; … }` | ✅ | Plugin capabilities | +| **config** | `{ storage: object; customizationPolicies?: { metadataType: string; allowCustomization?: boolean; lockedFields?: string[]; customizableFields?: string[]; … }[]; mergeStrategy?: object; additionalTypes?: { label: string; description?: string; filePatterns: string[]; supportsOverlay?: boolean; … }[]; … }` | optional | Plugin configuration | --- @@ -204,7 +204,7 @@ const result = MetadataBulkRegisterRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | Matched metadata items | +| **items** | `{ type: string; name: string; namespace?: string; label?: string; … }[]` | ✅ | Matched metadata items | | **total** | `integer` | ✅ | Total matching items | | **page** | `integer` | ✅ | Current page | | **pageSize** | `integer` | ✅ | Page size | @@ -263,7 +263,7 @@ const result = MetadataBulkRegisterRequest.parse(data); | **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 | +| **actions** | `{ name: string; label: string; objectName?: string; icon?: string; … }[]` | optional | Declarative type-level actions (e.g. datasource "Test connection"), reusing ActionSchema; merged with plugin-registered actions when emitted | --- @@ -275,8 +275,8 @@ const result = MetadataBulkRegisterRequest.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **valid** | `boolean` | ✅ | Whether the metadata is valid | -| **errors** | `Object[]` | optional | Validation errors | -| **warnings** | `Object[]` | optional | Validation warnings | +| **errors** | `{ path: string; message: string; code?: string }[]` | optional | Validation errors | +| **warnings** | `{ path: string; message: string }[]` | optional | Validation warnings | --- diff --git a/content/docs/references/kernel/misc.mdx b/content/docs/references/kernel/misc.mdx index 0ae6456abf..29792ea516 100644 --- a/content/docs/references/kernel/misc.mdx +++ b/content/docs/references/kernel/misc.mdx @@ -28,8 +28,8 @@ const result = DeadLetterQueueEntry.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique entry identifier | -| **event** | `Object` | ✅ | Original event | -| **error** | `Object` | ✅ | Failure details | +| **event** | `{ id?: string; name: string; payload: any; metadata: object }` | ✅ | Original event | +| **error** | `{ message: string; stack?: string; code?: string }` | ✅ | Failure details | | **retries** | `integer` | ✅ | Number of retry attempts | | **firstFailedAt** | `string` | ✅ | When event first failed | | **lastFailedAt** | `string` | ✅ | When event last failed | @@ -44,15 +44,15 @@ const result = DeadLetterQueueEntry.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **persistence** | `Object` | optional | Event persistence configuration | -| **queue** | `Object` | optional | Event queue configuration | -| **eventSourcing** | `Object` | optional | Event sourcing configuration | -| **replay** | `Object` | optional | Event replay configuration | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **messageQueue** | `Object` | optional | Message queue integration | -| **realtime** | `Object` | optional | Real-time notification configuration | -| **eventTypes** | `Object[]` | optional | Event type definitions | -| **handlers** | `Object[]` | optional | Global event handlers | +| **persistence** | `{ enabled: boolean; retention: integer; filter?: any; storage: Enum<'database' \| 'file' \| 's3' \| 'custom'> }` | optional | Event persistence configuration | +| **queue** | `{ name: string; concurrency: integer; retryPolicy?: object; deadLetterQueue?: string; … }` | optional | Event queue configuration | +| **eventSourcing** | `{ enabled: boolean; snapshotInterval: integer; snapshotRetention: integer; retention: integer; … }` | optional | Event sourcing configuration | +| **replay** | `{ enabled: boolean }` | optional | Event replay configuration | +| **webhooks** | `{ id?: string; eventPattern: string; url: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH'>; … }[]` | optional | Webhook configurations | +| **messageQueue** | `{ provider: Enum<'kafka' \| 'rabbitmq' \| 'aws-sqs' \| 'redis-pubsub' \| 'google-pubsub' \| 'azure-service-bus'>; topic: string; eventPattern: string; partitionKey?: string; … }` | optional | Message queue integration | +| **realtime** | `{ enabled: boolean; protocol: Enum<'websocket' \| 'sse' \| 'long-polling'>; eventPattern: string; userFilter: boolean; … }` | optional | Real-time notification configuration | +| **eventTypes** | `{ name: string; version: string; schema?: any; description?: string; … }[]` | optional | Event type definitions | +| **handlers** | `{ id?: string; eventName: string; handler: any; priority: integer; … }[]` | optional | Global event handlers | --- @@ -68,7 +68,7 @@ const result = DeadLetterQueueEntry.parse(data); | **handler** | `any` | ✅ | Handler function | | **priority** | `integer` | ✅ | Execution priority (lower numbers execute first) | | **async** | `boolean` | ✅ | Execute in background (true) or block (false) | -| **retry** | `Object` | optional | Retry policy for failed handlers | +| **retry** | `{ maxRetries: integer; backoffMs: integer; backoffMultiplier: number }` | optional | Retry policy for failed handlers | | **timeoutMs** | `integer` | optional | Handler timeout in milliseconds | | **filter** | `any` | optional | Optional filter to determine if handler should execute | @@ -82,9 +82,9 @@ const result = DeadLetterQueueEntry.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique log entry identifier | -| **event** | `Object` | ✅ | The event | +| **event** | `{ id?: string; name: string; payload: any; metadata: object }` | ✅ | The event | | **status** | `Enum<'pending' \| 'processing' \| 'completed' \| 'failed'>` | ✅ | Processing status | -| **handlersExecuted** | `Object[]` | optional | Handlers that processed this event | +| **handlersExecuted** | `{ handlerId: string; status: Enum<'success' \| 'failed' \| 'timeout'>; durationMs?: integer; error?: string }[]` | optional | Handlers that processed this event | | **receivedAt** | `string` | ✅ | When event was received | | **processedAt** | `string` | optional | When event was processed | | **totalDurationMs** | `integer` | optional | Total processing time | @@ -124,7 +124,7 @@ const result = DeadLetterQueueEntry.parse(data); | **correlationId** | `string` | optional | Correlation ID for event tracing | | **causationId** | `string` | optional | ID of the event that caused this event | | **priority** | `Enum<'critical' \| 'high' \| 'normal' \| 'low' \| 'background'>` | ✅ | Event priority | -| **cluster** | `Object` | optional | Per-emit cluster routing & delivery options. See cluster-semantics.mdx §4. | +| **cluster** | `{ scope: Enum<'local' \| 'cluster' \| 'tenant'>; deliverySemantics?: Enum<'best-effort' \| 'at-least-once' \| 'exactly-once'>; partitionKey?: string }` | optional | Per-emit cluster routing & delivery options. See cluster-semantics.mdx §4. | --- @@ -164,7 +164,7 @@ const result = DeadLetterQueueEntry.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Event queue name | | **concurrency** | `integer` | ✅ | Max concurrent event handlers | -| **retryPolicy** | `Object` | optional | Default retry policy for events | +| **retryPolicy** | `{ maxRetries: integer; backoffStrategy: Enum<'fixed' \| 'linear' \| 'exponential'>; initialDelayMs: integer; maxDelayMs: integer }` | optional | Default retry policy for events | | **deadLetterQueue** | `string` | optional | Dead letter queue name for failed events | | **priorityEnabled** | `boolean` | ✅ | Process events based on priority | @@ -211,7 +211,7 @@ const result = DeadLetterQueueEntry.parse(data); | **snapshotRetention** | `integer` | ✅ | Number of snapshots to retain | | **retention** | `integer` | ✅ | Days to retain events | | **aggregateTypes** | `string[]` | optional | Aggregate types to enable event sourcing for | -| **storage** | `Object` | optional | Event store configuration | +| **storage** | `{ type: Enum<'database' \| 'file' \| 's3' \| 'eventstore'>; options?: Record }` | optional | Event store configuration | --- @@ -243,8 +243,8 @@ const result = DeadLetterQueueEntry.parse(data); | **url** | `string` | ✅ | Webhook endpoint URL | | **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH'>` | ✅ | HTTP method | | **headers** | `Record` | optional | HTTP headers | -| **authentication** | `Object` | optional | Authentication configuration | -| **retryPolicy** | `Object` | optional | Retry policy | +| **authentication** | `{ type: Enum<'none' \| 'bearer' \| 'basic' \| 'api-key'>; credentials?: Record }` | optional | Authentication configuration | +| **retryPolicy** | `{ maxRetries: integer; backoffStrategy: Enum<'fixed' \| 'linear' \| 'exponential'>; initialDelayMs: integer; maxDelayMs: integer }` | optional | Retry policy | | **timeoutMs** | `integer` | ✅ | Request timeout in milliseconds | | **transform** | `any` | optional | Transform event before sending | | **enabled** | `boolean` | ✅ | Whether webhook is enabled | @@ -263,8 +263,8 @@ const result = DeadLetterQueueEntry.parse(data); | **eventPattern** | `string` | ✅ | Event pattern to broadcast | | **userFilter** | `boolean` | ✅ | Filter events by user | | **tenantFilter** | `boolean` | ✅ | Filter events by tenant | -| **channels** | `Object[]` | optional | Named channels for event broadcasting | -| **rateLimit** | `Object` | optional | Rate limiting configuration | +| **channels** | `{ name: string; eventPattern: string; filter?: any }[]` | optional | Named channels for event broadcasting | +| **rateLimit** | `{ maxEventsPerSecond: integer; windowMs: integer }` | optional | Rate limiting configuration | --- diff --git a/content/docs/references/kernel/package-artifact.mdx b/content/docs/references/kernel/package-artifact.mdx index 95974896bd..268383bf40 100644 --- a/content/docs/references/kernel/package-artifact.mdx +++ b/content/docs/references/kernel/package-artifact.mdx @@ -165,10 +165,10 @@ Package artifact structure and metadata | **size** | `integer` | optional | Total artifact file size in bytes | | **builtAt** | `string` | ✅ | ISO 8601 timestamp of when the artifact was built | | **builtWith** | `string` | optional | Build tool identifier (e.g. "os-cli@3.2.0") | -| **files** | `Object[]` | optional | List of files contained in the artifact | +| **files** | `{ path: string; size: integer; category?: Enum<'objects' \| 'views' \| 'pages' \| 'flows' \| 'dashboards' \| 'permissions' \| 'agents' \| 'reports' \| 'actions' \| 'translations' \| 'themes' \| 'datasets' \| 'apis' \| 'triggers' \| 'workflows'> }[]` | optional | List of files contained in the artifact | | **metadataCategories** | `Enum<'objects' \| 'views' \| 'pages' \| 'flows' \| 'dashboards' \| 'permissions' \| 'agents' \| 'reports' \| 'actions' \| 'translations' \| 'themes' \| 'datasets' \| 'apis' \| 'triggers' \| 'workflows'>[]` | optional | Metadata categories included in this artifact | -| **checksums** | `Object` | optional | SHA256 checksums for artifact integrity verification | -| **signature** | `Object` | optional | Digital signature for artifact authenticity verification | +| **checksums** | `{ algorithm: Enum<'sha256' \| 'sha384' \| 'sha512'>; files: Record }` | optional | SHA256 checksums for artifact integrity verification | +| **signature** | `{ algorithm: Enum<'RSA-SHA256' \| 'RSA-SHA384' \| 'RSA-SHA512' \| 'ECDSA-SHA256'>; publicKeyRef: string; signature: string; signedAt?: string; … }` | optional | Digital signature for artifact authenticity verification | --- diff --git a/content/docs/references/kernel/package-registry.mdx b/content/docs/references/kernel/package-registry.mdx index a086580c45..0f43d1170b 100644 --- a/content/docs/references/kernel/package-registry.mdx +++ b/content/docs/references/kernel/package-registry.mdx @@ -78,7 +78,7 @@ Disable package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Disabled package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Disabled package details | | **message** | `string` | optional | Disable status message | @@ -105,7 +105,7 @@ Enable package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Enabled package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Enabled package details | | **message** | `string` | optional | Enable status message | @@ -132,7 +132,7 @@ Get package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Package details | --- @@ -145,7 +145,7 @@ Install package request | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | Package manifest to install | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | 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 | @@ -161,9 +161,9 @@ Install package response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | Installed package details | +| **package** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }` | ✅ | Installed package details | | **message** | `string` | optional | Installation status message | -| **dependencyResolution** | `Object` | optional | Dependency resolution result from install analysis | +| **dependencyResolution** | `{ dependencies: { packageId: string; requiredRange: string; resolvedVersion?: string; installedVersion?: string; … }[]; canProceed: boolean; requiredActions: { type: Enum<'install' \| 'upgrade' \| 'confirm_conflict'>; packageId: string; description: string }[]; installOrder: string[]; … }` | optional | Dependency resolution result from install analysis | --- @@ -176,7 +176,7 @@ Installed package with runtime lifecycle state | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | Full package manifest | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | 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 | @@ -186,7 +186,7 @@ Installed package with runtime lifecycle state | **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 | +| **upgradeHistory** | `{ fromVersion: string; toVersion: string; upgradedAt: string; status: Enum<'success' \| 'failed' \| 'rolled_back'>; … }[]` | optional | Version upgrade history | | **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package | @@ -215,7 +215,7 @@ List packages response | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **packages** | `Object[]` | ✅ | List of installed packages | +| **packages** | `{ manifest: object; status?: Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>; enabled?: boolean; installedAt?: string; … }[]` | ✅ | List of installed packages | | **total** | `number` | ✅ | Total package count | @@ -229,7 +229,7 @@ Namespace collision error during installation | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Error type | +| **type** | `'namespace_conflict'` | ✅ | Error type | | **requestedNamespace** | `string` | ✅ | Requested namespace | | **conflictingPackageId** | `string` | ✅ | Conflicting package ID | | **conflictingPackageName** | `string` | ✅ | Conflicting package display name | diff --git a/content/docs/references/kernel/package-upgrade.mdx b/content/docs/references/kernel/package-upgrade.mdx index 39aa0fc77e..a157b5e9d6 100644 --- a/content/docs/references/kernel/package-upgrade.mdx +++ b/content/docs/references/kernel/package-upgrade.mdx @@ -144,7 +144,7 @@ Upgrade package request | :--- | :--- | :--- | :--- | | **packageId** | `string` | ✅ | Package ID to upgrade | | **targetVersion** | `string` | optional | Target version (defaults to latest) | -| **manifest** | `Object` | optional | New manifest (if installing from local) | +| **manifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | 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 | @@ -163,9 +163,9 @@ Upgrade package response | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | Whether the upgrade succeeded | | **phase** | `Enum<'pending' \| 'analyzing' \| 'snapshot' \| 'executing' \| 'migrating' \| 'validating' \| 'completed' \| 'failed' \| 'rolling-back' \| 'rolled-back'>` | ✅ | Current upgrade phase | -| **plan** | `Object` | optional | Upgrade plan | +| **plan** | `{ packageId: string; fromVersion: string; toVersion: string; impactLevel: Enum<'none' \| 'low' \| 'medium' \| 'high' \| 'critical'>; … }` | optional | Upgrade plan | | **snapshotId** | `string` | optional | Snapshot ID for rollback | -| **conflicts** | `Object[]` | optional | Unresolved merge conflicts | +| **conflicts** | `{ path: string; baseValue: any; incomingValue: any; customValue: any }[]` | optional | Unresolved merge conflicts | | **errorMessage** | `string` | optional | Error message if upgrade failed | | **message** | `string` | optional | Human-readable status message | @@ -204,11 +204,11 @@ Upgrade analysis plan generated before execution | **fromVersion** | `string` | ✅ | Currently installed version | | **toVersion** | `string` | ✅ | Target upgrade version | | **impactLevel** | `Enum<'none' \| 'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | Severity assessment from none (seamless) to critical (breaking changes) | -| **changes** | `Object[]` | ✅ | All metadata changes | +| **changes** | `{ type: string; name: string; changeType: Enum<'added' \| 'modified' \| 'removed' \| 'renamed'>; hasConflict: boolean; … }[]` | ✅ | All metadata changes | | **affectedCustomizations** | `integer` | ✅ | Count of customizations that may be affected | | **requiresMigration** | `boolean` | ✅ | Whether data migration scripts are needed | | **migrationScripts** | `string[]` | optional | Paths to migration scripts | -| **dependencyUpgrades** | `Object[]` | optional | Dependent packages that also need upgrading | +| **dependencyUpgrades** | `{ packageId: string; fromVersion: string; toVersion: string }[]` | optional | Dependent packages that also need upgrading | | **estimatedDuration** | `integer` | optional | Estimated upgrade duration in seconds | | **summary** | `string` | optional | Human-readable upgrade summary | @@ -228,8 +228,8 @@ Pre-upgrade state snapshot for rollback capability | **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 | +| **previousManifest** | `{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }` | ✅ | Complete manifest of the previous package version | +| **metadataSnapshot** | `{ type: string; name: string; metadata: Record }[]` | ✅ | 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-capability.mdx b/content/docs/references/kernel/plugin-capability.mdx index 58cfc7b4bd..8de04d3db9 100644 --- a/content/docs/references/kernel/plugin-capability.mdx +++ b/content/docs/references/kernel/plugin-capability.mdx @@ -59,7 +59,7 @@ Level of protocol conformance | **name** | `string` | ✅ | | | **description** | `string` | optional | | | **type** | `Enum<'action' \| 'hook' \| 'widget' \| 'provider' \| 'transformer' \| 'validator' \| 'decorator'>` | ✅ | | -| **contract** | `Object` | optional | | +| **contract** | `{ input?: string; output?: string; signature?: string }` | optional | | | **cardinality** | `Enum<'single' \| 'multiple'>` | ✅ | Whether multiple extensions can register to this point | @@ -71,10 +71,10 @@ Level of protocol conformance | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **protocol** | `Object` | ✅ | | +| **protocol** | `{ id: string; label: string; version: object; specification?: string; … }` | ✅ | | | **conformance** | `Enum<'full' \| 'partial' \| 'experimental' \| 'deprecated'>` | ✅ | Level of protocol conformance | | **implementedFeatures** | `string[]` | optional | List of implemented feature names | -| **features** | `Object[]` | optional | | +| **features** | `{ name: string; enabled: boolean; description?: string; sinceVersion?: string; … }[]` | optional | | | **metadata** | `Record` | optional | | | **certified** | `boolean` | ✅ | Has passed official conformance tests | | **certificationDate** | `string` | optional | | @@ -88,11 +88,11 @@ Level of protocol conformance | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **implements** | `Object[]` | optional | List of protocols this plugin conforms to | -| **provides** | `Object[]` | optional | Services/APIs this plugin offers to others | -| **requires** | `Object[]` | optional | Required plugins and their capabilities | -| **extensionPoints** | `Object[]` | optional | Points where other plugins can extend this plugin | -| **extensions** | `Object[]` | optional | Extensions contributed to other plugins | +| **implements** | `{ protocol: object; conformance: Enum<'full' \| 'partial' \| 'experimental' \| 'deprecated'>; implementedFeatures?: string[]; features?: { name: string; enabled: boolean; description?: string; sinceVersion?: string; … }[]; … }[]` | optional | List of protocols this plugin conforms to | +| **provides** | `{ id: string; name: string; description?: string; version: object; … }[]` | optional | Services/APIs this plugin offers to others | +| **requires** | `{ pluginId: string; version: string; optional: boolean; reason?: string; … }[]` | optional | Required plugins and their capabilities | +| **extensionPoints** | `{ id: string; name: string; description?: string; type: Enum<'action' \| 'hook' \| 'widget' \| 'provider' \| 'transformer' \| 'validator' \| 'decorator'>; … }[]` | optional | Points where other plugins can extend this plugin | +| **extensions** | `{ targetPluginId: string; extensionPointId: string; implementation: string; priority: integer }[]` | optional | Extensions contributed to other plugins | --- @@ -121,9 +121,9 @@ Level of protocol conformance | **id** | `string` | ✅ | Unique interface identifier | | **name** | `string` | ✅ | | | **description** | `string` | optional | | -| **version** | `Object` | ✅ | Semantic version of the protocol | -| **methods** | `Object[]` | ✅ | | -| **events** | `Object[]` | optional | | +| **version** | `{ major: integer; minor: integer; patch: integer }` | ✅ | Semantic version of the protocol | +| **methods** | `{ name: string; description?: string; parameters?: { name: string; type: string; required: boolean; description?: string }[]; returnType?: string; … }[]` | ✅ | | +| **events** | `{ name: string; description?: string; payload?: string }[]` | optional | | | **stability** | `Enum<'stable' \| 'beta' \| 'alpha' \| 'experimental'>` | ✅ | | @@ -152,7 +152,7 @@ Level of protocol conformance | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique protocol identifier (e.g., com.objectstack.protocol.storage.v1) | | **label** | `string` | ✅ | | -| **version** | `Object` | ✅ | Semantic version of the protocol | +| **version** | `{ major: integer; minor: integer; patch: integer }` | ✅ | Semantic version of the protocol | | **specification** | `string` | optional | URL or path to protocol specification | | **description** | `string` | optional | | diff --git a/content/docs/references/kernel/plugin-lifecycle-advanced.mdx b/content/docs/references/kernel/plugin-lifecycle-advanced.mdx index 43216f1bc6..141c83d089 100644 --- a/content/docs/references/kernel/plugin-lifecycle-advanced.mdx +++ b/content/docs/references/kernel/plugin-lifecycle-advanced.mdx @@ -43,12 +43,12 @@ const result = AdvancedPluginLifecycleConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **health** | `Object` | optional | | -| **hotReload** | `Object` | optional | | -| **degradation** | `Object` | optional | | -| **updates** | `Object` | optional | | -| **resources** | `Object` | optional | | -| **observability** | `Object` | optional | | +| **health** | `{ interval: integer; timeout: integer; failureThreshold: integer; successThreshold: integer; … }` | optional | | +| **hotReload** | `{ enabled: boolean; watchPatterns?: string[]; debounceDelay: integer; preserveState: boolean; … }` | optional | | +| **degradation** | `{ enabled: boolean; fallbackMode: Enum<'minimal' \| 'cached' \| 'readonly' \| 'offline' \| 'disabled'>; criticalDependencies?: string[]; optionalDependencies?: string[]; … }` | optional | | +| **updates** | `{ mode: Enum<'manual' \| 'automatic' \| 'scheduled' \| 'rolling'>; autoUpdateConstraints?: object; schedule?: object; rollback?: object; … }` | optional | | +| **resources** | `{ maxMemory?: integer; maxCpu?: number; maxConnections?: integer; timeout?: integer }` | optional | | +| **observability** | `{ enableMetrics: boolean; enableTracing: boolean; enableProfiling: boolean; metricsInterval: integer }` | optional | | --- @@ -63,8 +63,8 @@ const result = AdvancedPluginLifecycleConfig.parse(data); | **endpoints** | `string[]` | optional | Backend connection endpoints | | **keyPrefix** | `string` | optional | Prefix for all keys (e.g., "plugin:my-plugin:") | | **ttl** | `integer` | optional | State expiration time in seconds | -| **auth** | `Object` | optional | | -| **replication** | `Object` | optional | | +| **auth** | `{ username?: string; password?: string; token?: string; certificate?: string }` | optional | | +| **replication** | `{ enabled: boolean; minReplicas: integer }` | optional | | | **customConfig** | `Record` | optional | Provider-specific configuration | @@ -80,8 +80,8 @@ const result = AdvancedPluginLifecycleConfig.parse(data); | **fallbackMode** | `Enum<'minimal' \| 'cached' \| 'readonly' \| 'offline' \| 'disabled'>` | ✅ | | | **criticalDependencies** | `string[]` | optional | Plugin IDs that are required for operation | | **optionalDependencies** | `string[]` | optional | Plugin IDs that are nice to have but not required | -| **degradedFeatures** | `Object[]` | optional | | -| **autoRecovery** | `Object` | optional | | +| **degradedFeatures** | `{ feature: string; enabled: boolean; reason?: string }[]` | optional | | +| **autoRecovery** | `{ enabled: boolean; retryInterval: integer; maxAttempts: integer }` | optional | | --- @@ -97,7 +97,7 @@ const result = AdvancedPluginLifecycleConfig.parse(data); | **debounceDelay** | `integer` | ✅ | Wait time after change detection before reload | | **preserveState** | `boolean` | ✅ | Keep plugin state across reloads | | **stateStrategy** | `Enum<'memory' \| 'disk' \| 'distributed' \| 'none'>` | ✅ | How to preserve state during reload | -| **distributedConfig** | `Object` | optional | Configuration for distributed state management | +| **distributedConfig** | `{ provider: Enum<'redis' \| 'etcd' \| 'custom'>; endpoints?: string[]; keyPrefix?: string; ttl?: integer; … }` | optional | Configuration for distributed state management | | **shutdownTimeout** | `integer` | ✅ | Maximum time to wait for graceful shutdown | | **beforeReload** | `string[]` | optional | Hook names to call before reload | | **afterReload** | `string[]` | optional | Hook names to call after reload | @@ -132,9 +132,9 @@ const result = AdvancedPluginLifecycleConfig.parse(data); | **status** | `Enum<'healthy' \| 'degraded' \| 'unhealthy' \| 'failed' \| 'recovering' \| 'unknown'>` | ✅ | Current health status of the plugin | | **timestamp** | `string` | ✅ | | | **message** | `string` | optional | | -| **metrics** | `Object` | optional | | -| **checks** | `Object[]` | optional | | -| **dependencies** | `Object[]` | optional | | +| **metrics** | `{ uptime?: number; memoryUsage?: number; cpuUsage?: number; activeConnections?: number; … }` | optional | | +| **checks** | `{ name: string; status: Enum<'passed' \| 'failed' \| 'warning'>; message?: string; data?: Record }[]` | optional | | +| **dependencies** | `{ pluginId: string; status: Enum<'healthy' \| 'degraded' \| 'unhealthy' \| 'failed' \| 'recovering' \| 'unknown'>; message?: string }[]` | optional | | --- @@ -165,7 +165,7 @@ Current health status of the plugin | **version** | `string` | ✅ | | | **timestamp** | `string` | ✅ | | | **state** | `Record` | ✅ | | -| **metadata** | `Object` | optional | | +| **metadata** | `{ checksum?: string; compressed: boolean; encryption?: string }` | optional | | --- @@ -177,10 +177,10 @@ Current health status of the plugin | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **mode** | `Enum<'manual' \| 'automatic' \| 'scheduled' \| 'rolling'>` | ✅ | | -| **autoUpdateConstraints** | `Object` | optional | | -| **schedule** | `Object` | optional | | -| **rollback** | `Object` | optional | | -| **validation** | `Object` | optional | | +| **autoUpdateConstraints** | `{ major: boolean; minor: boolean; patch: boolean }` | optional | | +| **schedule** | `{ cron?: string; timezone: string; maintenanceWindow: integer }` | optional | | +| **rollback** | `{ enabled: boolean; automatic: boolean; keepVersions: integer; timeout: integer }` | optional | | +| **validation** | `{ checkCompatibility: boolean; runTests: boolean; testSuite?: string }` | optional | | --- diff --git a/content/docs/references/kernel/plugin-lifecycle-events.mdx b/content/docs/references/kernel/plugin-lifecycle-events.mdx index 1815d27880..4b9f47fd05 100644 --- a/content/docs/references/kernel/plugin-lifecycle-events.mdx +++ b/content/docs/references/kernel/plugin-lifecycle-events.mdx @@ -115,7 +115,7 @@ Plugin lifecycle phase | :--- | :--- | :--- | :--- | | **pluginName** | `string` | ✅ | Name of the plugin | | **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred | -| **error** | `Object` | ✅ | Serializable error representation | +| **error** | `{ name: string; message: string; stack?: string; code?: string }` | ✅ | Serializable error representation | | **phase** | `Enum<'init' \| 'start' \| 'destroy'>` | ✅ | Lifecycle phase where error occurred | | **errorMessage** | `string` | optional | Error message | | **errorStack** | `string` | optional | Error stack trace | diff --git a/content/docs/references/kernel/plugin-loading.mdx b/content/docs/references/kernel/plugin-loading.mdx index f4c35538a6..647659faa7 100644 --- a/content/docs/references/kernel/plugin-loading.mdx +++ b/content/docs/references/kernel/plugin-loading.mdx @@ -61,7 +61,7 @@ Plugin caching configuration | **ttl** | `integer` | optional | Time to live in seconds (0 = infinite) | | **maxSize** | `integer` | optional | Max cache size in MB | | **invalidateOn** | `Enum<'version-change' \| 'dependency-change' \| 'manual' \| 'error'>[]` | optional | | -| **compression** | `Object` | optional | | +| **compression** | `{ enabled: boolean; algorithm: Enum<'gzip' \| 'brotli' \| 'deflate'> }` | optional | | --- @@ -78,7 +78,7 @@ Plugin code splitting configuration | **strategy** | `Enum<'route' \| 'feature' \| 'size' \| 'custom'>` | ✅ | | | **chunkNaming** | `Enum<'hashed' \| 'named' \| 'sequential'>` | ✅ | | | **maxChunkSize** | `integer` | optional | Max chunk size in KB | -| **sharedDependencies** | `Object` | optional | | +| **sharedDependencies** | `{ enabled: boolean; minChunks: integer }` | optional | | --- @@ -92,8 +92,8 @@ Plugin dependency resolution configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **strategy** | `Enum<'strict' \| 'compatible' \| 'latest' \| 'pinned'>` | ✅ | | -| **peerDependencies** | `Object` | optional | | -| **optionalDependencies** | `Object` | optional | | +| **peerDependencies** | `{ resolve: boolean; onMissing: Enum<'error' \| 'warn' \| 'ignore'>; onMismatch: Enum<'error' \| 'warn' \| 'ignore'> }` | optional | | +| **optionalDependencies** | `{ load: boolean; onFailure: Enum<'warn' \| 'ignore'> }` | optional | | | **conflictResolution** | `Enum<'fail' \| 'latest' \| 'oldest' \| 'manual'>` | ✅ | | | **circularDependencies** | `Enum<'error' \| 'warn' \| 'allow'>` | ✅ | | @@ -114,7 +114,7 @@ Plugin dynamic import configuration | **preload** | `boolean` | ✅ | Preload module in parallel with parent | | **webpackChunkName** | `string` | optional | Custom chunk name for webpack | | **timeout** | `integer` | ✅ | Dynamic import timeout (ms) | -| **retry** | `Object` | optional | | +| **retry** | `{ enabled: boolean; maxAttempts: integer; backoffMs: integer }` | optional | | --- @@ -134,9 +134,9 @@ Plugin hot reload configuration | **ignorePatterns** | `string[]` | optional | Glob patterns for files to ignore | | **debounceMs** | `integer` | ✅ | | | **preserveState** | `boolean` | ✅ | | -| **stateSerialization** | `Object` | optional | | -| **hooks** | `Object` | optional | | -| **productionSafety** | `Object` | optional | | +| **stateSerialization** | `{ enabled: boolean; handler?: string }` | optional | | +| **hooks** | `{ beforeReload?: string; afterReload?: string; onError?: string }` | optional | | +| **productionSafety** | `{ healthValidation: boolean; rollbackOnFailure: boolean; healthTimeout: integer; drainConnections: boolean; … }` | optional | | --- @@ -153,7 +153,7 @@ Plugin initialization configuration | **timeout** | `integer` | ✅ | | | **priority** | `integer` | ✅ | | | **critical** | `boolean` | ✅ | If true, kernel bootstrap fails if plugin fails | -| **retry** | `Object` | optional | | +| **retry** | `{ enabled: boolean; maxAttempts: integer; backoffMs: integer }` | optional | | | **healthCheckInterval** | `integer` | optional | Health check interval in ms (0 = disabled) | @@ -168,15 +168,15 @@ Complete plugin loading configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **strategy** | `Enum<'eager' \| 'lazy' \| 'parallel' \| 'deferred' \| 'on-demand'>` | ✅ | Plugin loading strategy | -| **preload** | `Object` | optional | Plugin preloading configuration | -| **codeSplitting** | `Object` | optional | Plugin code splitting configuration | -| **dynamicImport** | `Object` | optional | Plugin dynamic import configuration | -| **initialization** | `Object` | optional | Plugin initialization configuration | -| **dependencyResolution** | `Object` | optional | Plugin dependency resolution configuration | -| **hotReload** | `Object` | optional | Plugin hot reload configuration | -| **caching** | `Object` | optional | Plugin caching configuration | -| **sandboxing** | `Object` | optional | Plugin sandboxing configuration | -| **monitoring** | `Object` | optional | Plugin performance monitoring configuration | +| **preload** | `{ enabled: boolean; priority: integer; resources?: Enum<'metadata' \| 'dependencies' \| 'assets' \| 'code' \| 'services'>[]; conditions?: object }` | optional | Plugin preloading configuration | +| **codeSplitting** | `{ enabled: boolean; strategy: Enum<'route' \| 'feature' \| 'size' \| 'custom'>; chunkNaming: Enum<'hashed' \| 'named' \| 'sequential'>; maxChunkSize?: integer; … }` | optional | Plugin code splitting configuration | +| **dynamicImport** | `{ enabled: boolean; mode: Enum<'async' \| 'sync' \| 'eager' \| 'lazy'>; prefetch: boolean; preload: boolean; … }` | optional | Plugin dynamic import configuration | +| **initialization** | `{ mode: Enum<'sync' \| 'async' \| 'parallel' \| 'sequential'>; timeout: integer; priority: integer; critical: boolean; … }` | optional | Plugin initialization configuration | +| **dependencyResolution** | `{ strategy: Enum<'strict' \| 'compatible' \| 'latest' \| 'pinned'>; peerDependencies?: object; optionalDependencies?: object; conflictResolution: Enum<'fail' \| 'latest' \| 'oldest' \| 'manual'>; … }` | optional | Plugin dependency resolution configuration | +| **hotReload** | `{ enabled: boolean; environment: Enum<'development' \| 'staging' \| 'production'>; strategy: Enum<'full' \| 'partial' \| 'state-preserve'>; watchPatterns?: string[]; … }` | optional | Plugin hot reload configuration | +| **caching** | `{ enabled: boolean; storage: Enum<'memory' \| 'disk' \| 'indexeddb' \| 'hybrid'>; keyStrategy: Enum<'version' \| 'hash' \| 'timestamp'>; ttl?: integer; … }` | optional | Plugin caching configuration | +| **sandboxing** | `{ enabled: boolean; scope: Enum<'automation-only' \| 'untrusted-only' \| 'all-plugins'>; isolationLevel: Enum<'none' \| 'process' \| 'vm' \| 'iframe' \| 'web-worker'>; allowedCapabilities?: string[]; … }` | optional | Plugin sandboxing configuration | +| **monitoring** | `{ enabled: boolean; metrics?: Enum<'load-time' \| 'init-time' \| 'memory-usage' \| 'cpu-usage' \| 'api-calls' \| 'error-rate' \| 'cache-hit-rate'>[]; samplingRate: number; reportingInterval: integer; … }` | optional | Plugin performance monitoring configuration | --- @@ -194,7 +194,7 @@ Plugin loading lifecycle event | **timestamp** | `integer` | ✅ | | | **durationMs** | `integer` | optional | | | **metadata** | `Record` | optional | | -| **error** | `Object` | optional | | +| **error** | `{ message: string; code?: string; stack?: string }` | optional | | --- @@ -245,7 +245,7 @@ Plugin performance monitoring configuration | **metrics** | `Enum<'load-time' \| 'init-time' \| 'memory-usage' \| 'cpu-usage' \| 'api-calls' \| 'error-rate' \| 'cache-hit-rate'>[]` | optional | | | **samplingRate** | `number` | ✅ | | | **reportingInterval** | `integer` | ✅ | | -| **budgets** | `Object` | optional | | +| **budgets** | `{ maxLoadTimeMs?: integer; maxInitTimeMs?: integer; maxMemoryMB?: integer }` | optional | | | **onBudgetViolation** | `Enum<'warn' \| 'error' \| 'ignore'>` | ✅ | | @@ -262,7 +262,7 @@ Plugin preloading configuration | **enabled** | `boolean` | ✅ | | | **priority** | `integer` | ✅ | | | **resources** | `Enum<'metadata' \| 'dependencies' \| 'assets' \| 'code' \| 'services'>[]` | optional | | -| **conditions** | `Object` | optional | | +| **conditions** | `{ routes?: string[]; roles?: string[]; deviceType?: Enum<'desktop' \| 'mobile' \| 'tablet'>[]; minNetworkSpeed?: Enum<'slow-2g' \| '2g' \| '3g' \| '4g'> }` | optional | | --- @@ -279,9 +279,9 @@ Plugin sandboxing configuration | **scope** | `Enum<'automation-only' \| 'untrusted-only' \| 'all-plugins'>` | ✅ | Which plugins are subject to isolation | | **isolationLevel** | `Enum<'none' \| 'process' \| 'vm' \| 'iframe' \| 'web-worker'>` | ✅ | | | **allowedCapabilities** | `string[]` | optional | List of allowed capability IDs | -| **resourceQuotas** | `Object` | optional | | -| **permissions** | `Object` | optional | | -| **ipc** | `Object` | optional | | +| **resourceQuotas** | `{ maxMemoryMB?: integer; maxCpuTimeMs?: integer; maxFileDescriptors?: integer; maxNetworkKBps?: integer }` | optional | | +| **permissions** | `{ allowedAPIs?: string[]; allowedPaths?: string[]; allowedEndpoints?: string[]; allowedEnvVars?: string[] }` | optional | | +| **ipc** | `{ enabled: boolean; transport: Enum<'message-port' \| 'unix-socket' \| 'tcp' \| 'memory'>; maxMessageSize: integer; timeout: integer; … }` | optional | | --- diff --git a/content/docs/references/kernel/plugin-registry.mdx b/content/docs/references/kernel/plugin-registry.mdx index d94d39714b..55cca8adcc 100644 --- a/content/docs/references/kernel/plugin-registry.mdx +++ b/content/docs/references/kernel/plugin-registry.mdx @@ -39,7 +39,7 @@ const result = PluginInstallConfig.parse(data); | **version** | `string` | optional | Defaults to latest | | **config** | `Record` | optional | | | **autoUpdate** | `boolean` | optional | | -| **options** | `Object` | optional | | +| **options** | `{ skipDependencies?: boolean; force?: boolean; target?: Enum<'system' \| 'space' \| 'user'> }` | optional | | --- @@ -53,8 +53,8 @@ const result = PluginInstallConfig.parse(data); | **testCoverage** | `number` | optional | | | **documentationScore** | `number` | optional | | | **codeQuality** | `number` | optional | | -| **securityScan** | `Object` | optional | | -| **conformanceTests** | `Object[]` | optional | | +| **securityScan** | `{ lastScanDate?: string; vulnerabilities?: object; passed: boolean }` | optional | | +| **conformanceTests** | `{ protocolId: string; passed: boolean; totalTests: integer; passedTests: integer; … }[]` | optional | | --- @@ -72,21 +72,21 @@ const result = PluginInstallConfig.parse(data); | **readme** | `string` | optional | | | **category** | `Enum<'data' \| 'integration' \| 'ui' \| 'analytics' \| 'security' \| 'automation' \| 'ai' \| 'utility' \| 'driver' \| 'gateway' \| 'adapter'>` | optional | | | **tags** | `string[]` | optional | | -| **vendor** | `Object` | ✅ | | -| **capabilities** | `Object` | optional | | -| **compatibility** | `Object` | optional | | -| **links** | `Object` | optional | | -| **media** | `Object` | optional | | -| **quality** | `Object` | optional | | -| **statistics** | `Object` | optional | | +| **vendor** | `{ id: string; name: string; website?: string; email?: string; … }` | ✅ | | +| **capabilities** | `{ implements?: { protocol: object; conformance: Enum<'full' \| 'partial' \| 'experimental' \| 'deprecated'>; implementedFeatures?: string[]; features?: { name: string; enabled: boolean; description?: string; sinceVersion?: string; … }[]; … }[]; provides?: { id: string; name: string; description?: string; version: object; … }[]; requires?: { pluginId: string; version: string; optional: boolean; reason?: string; … }[]; extensionPoints?: { id: string; name: string; description?: string; type: Enum<'action' \| 'hook' \| 'widget' \| 'provider' \| 'transformer' \| 'validator' \| 'decorator'>; … }[]; … }` | optional | | +| **compatibility** | `{ minObjectStackVersion?: string; maxObjectStackVersion?: string; nodeVersion?: string; platforms?: Enum<'linux' \| 'darwin' \| 'win32' \| 'browser'>[] }` | optional | | +| **links** | `{ homepage?: string; repository?: string; documentation?: string; bugs?: string; … }` | optional | | +| **media** | `{ icon?: string; logo?: string; screenshots?: string[]; video?: string }` | optional | | +| **quality** | `{ testCoverage?: number; documentationScore?: number; codeQuality?: number; securityScan?: object; … }` | optional | | +| **statistics** | `{ downloads: integer; downloadsLastMonth: integer; activeInstallations: integer; ratings?: object; … }` | optional | | | **license** | `string` | optional | SPDX license identifier | -| **pricing** | `Object` | optional | | +| **pricing** | `{ model: Enum<'free' \| 'freemium' \| 'paid' \| 'enterprise'>; price?: number; currency?: string; billingPeriod?: Enum<'one-time' \| 'monthly' \| 'yearly'> }` | optional | | | **publishedAt** | `string` | optional | | | **updatedAt** | `string` | optional | | | **deprecated** | `boolean` | ✅ | | | **deprecationMessage** | `string` | optional | | | **replacedBy** | `string` | optional | Plugin ID that replaces this one | -| **flags** | `Object` | optional | | +| **flags** | `{ experimental: boolean; beta: boolean; featured: boolean; verified: boolean }` | optional | | --- @@ -121,7 +121,7 @@ const result = PluginInstallConfig.parse(data); | **downloads** | `integer` | ✅ | | | **downloadsLastMonth** | `integer` | ✅ | | | **activeInstallations** | `integer` | ✅ | | -| **ratings** | `Object` | optional | | +| **ratings** | `{ average: number; count: integer; distribution?: object }` | optional | | | **stars** | `integer` | optional | | | **dependents** | `integer` | ✅ | | diff --git a/content/docs/references/kernel/plugin-runtime.mdx b/content/docs/references/kernel/plugin-runtime.mdx index ee0ec896fb..b2b9046f10 100644 --- a/content/docs/references/kernel/plugin-runtime.mdx +++ b/content/docs/references/kernel/plugin-runtime.mdx @@ -56,8 +56,8 @@ Request to dynamically load a plugin at runtime | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **pluginId** | `string` | ✅ | Unique plugin identifier | -| **source** | `Object` | ✅ | Plugin source location for dynamic resolution | -| **activationEvents** | `Object[]` | optional | Lazy activation triggers; if omitted plugin starts immediately | +| **source** | `{ type: Enum<'npm' \| 'local' \| 'url' \| 'registry' \| 'git'>; location: string; version?: string; integrity?: string }` | ✅ | Plugin source location for dynamic resolution | +| **activationEvents** | `{ type: Enum<'onCommand' \| 'onRoute' \| 'onObject' \| 'onEvent' \| 'onService' \| 'onSchedule' \| 'onStartup'>; pattern: string }[]` | optional | Lazy activation triggers; if omitted plugin starts immediately | | **config** | `Record` | optional | Runtime configuration overrides | | **priority** | `integer` | ✅ | Loading priority (lower is higher) | | **sandbox** | `boolean` | ✅ | Run in an isolated sandbox | @@ -76,7 +76,7 @@ Dynamic plugin loading subsystem configuration | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable runtime load/unload of plugins | | **maxDynamicPlugins** | `integer` | ✅ | Upper limit on runtime-loaded plugins | -| **discovery** | `Object` | optional | Runtime plugin discovery configuration | +| **discovery** | `{ enabled: boolean; sources: { type: Enum<'registry' \| 'npm' \| 'directory' \| 'url'>; endpoint: string; pollInterval: integer; filter?: object }[]; autoLoad: boolean; requireApproval: boolean }` | optional | Runtime plugin discovery configuration | | **defaultSandbox** | `boolean` | ✅ | Sandbox dynamically loaded plugins by default | | **allowedSources** | `Enum<'npm' \| 'local' \| 'url' \| 'registry' \| 'git'>[]` | optional | Restrict which source types are permitted | | **requireIntegrity** | `boolean` | ✅ | Require integrity hash verification for remote sources | @@ -113,7 +113,7 @@ Result of a dynamic plugin operation | **pluginId** | `string` | ✅ | | | **durationMs** | `integer` | optional | | | **version** | `string` | optional | | -| **error** | `Object` | optional | | +| **error** | `{ code: string; message: string; details?: Record }` | optional | | | **warnings** | `string[]` | optional | | @@ -145,7 +145,7 @@ Runtime plugin discovery configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | | -| **sources** | `Object[]` | ✅ | | +| **sources** | `{ type: Enum<'registry' \| 'npm' \| 'directory' \| 'url'>; endpoint: string; pollInterval: integer; filter?: object }[]` | ✅ | | | **autoLoad** | `boolean` | ✅ | Automatically load newly discovered plugins | | **requireApproval** | `boolean` | ✅ | Require admin approval before loading discovered plugins | @@ -163,7 +163,7 @@ Source for runtime plugin discovery | **type** | `Enum<'registry' \| 'npm' \| 'directory' \| 'url'>` | ✅ | Discovery source type | | **endpoint** | `string` | ✅ | Registry URL, directory path, or manifest URL | | **pollInterval** | `integer` | ✅ | How often to re-scan for new plugins (0 = manual) | -| **filter** | `Object` | optional | | +| **filter** | `{ tags?: string[]; vendors?: string[]; minTrustLevel?: Enum<'verified' \| 'trusted' \| 'community' \| 'untrusted'> }` | optional | | --- diff --git a/content/docs/references/kernel/plugin-security-advanced.mdx b/content/docs/references/kernel/plugin-security-advanced.mdx index c1fd93727e..f240b91041 100644 --- a/content/docs/references/kernel/plugin-security-advanced.mdx +++ b/content/docs/references/kernel/plugin-security-advanced.mdx @@ -45,12 +45,12 @@ const result = KernelSecurityPolicy.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **csp** | `Object` | optional | | -| **cors** | `Object` | optional | | -| **rateLimit** | `Object` | optional | | -| **authentication** | `Object` | optional | | -| **encryption** | `Object` | optional | | -| **auditLog** | `Object` | optional | | +| **csp** | `{ directives?: Record; reportOnly: boolean }` | optional | | +| **cors** | `{ allowedOrigins: string[]; allowedMethods: string[]; allowedHeaders: string[]; allowCredentials: boolean; … }` | optional | | +| **rateLimit** | `{ enabled: boolean; maxRequests: integer; windowMs: integer; strategy: Enum<'fixed' \| 'sliding' \| 'token-bucket'> }` | optional | | +| **authentication** | `{ required: boolean; methods: Enum<'jwt' \| 'oauth2' \| 'api-key' \| 'session' \| 'certificate'>[]; tokenExpiration?: integer }` | optional | | +| **encryption** | `{ dataAtRest: boolean; dataInTransit: boolean; algorithm?: string; minKeyLength?: integer }` | optional | | +| **auditLog** | `{ enabled: boolean; events?: string[]; retention?: integer }` | optional | | --- @@ -62,13 +62,13 @@ const result = KernelSecurityPolicy.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **timestamp** | `string` | ✅ | | -| **scanner** | `Object` | ✅ | | +| **scanner** | `{ name: string; version: string }` | ✅ | | | **status** | `Enum<'passed' \| 'failed' \| 'warning'>` | ✅ | | -| **vulnerabilities** | `Object[]` | optional | | -| **codeIssues** | `Object[]` | optional | | -| **dependencyVulnerabilities** | `Object[]` | optional | | -| **licenseCompliance** | `Object` | optional | | -| **summary** | `Object` | ✅ | | +| **vulnerabilities** | `{ cve?: string; id: string; severity: Enum<'critical' \| 'high' \| 'medium' \| 'low' \| 'info'>; category?: string; … }[]` | optional | | +| **codeIssues** | `{ severity: Enum<'error' \| 'warning' \| 'info'>; type: string; file: string; line?: integer; … }[]` | optional | | +| **dependencyVulnerabilities** | `{ package: string; version: string; vulnerability: object }[]` | optional | | +| **licenseCompliance** | `{ status: Enum<'compliant' \| 'non-compliant' \| 'unknown'>; issues?: { package: string; license: string; reason: string }[] }` | optional | | +| **summary** | `{ totalVulnerabilities: integer; criticalCount: integer; highCount: integer; mediumCount: integer; … }` | ✅ | | --- @@ -146,7 +146,7 @@ Scope of permission application | **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 | | +| **filter** | `{ resourceIds?: string[]; condition?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; fields?: string[] }` | optional | | | **description** | `string` | ✅ | | | **required** | `boolean` | optional | | | **justification** | `string` | optional | Why this permission is needed | @@ -160,8 +160,8 @@ Scope of permission application | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **permissions** | `Object[]` | ✅ | | -| **groups** | `Object[]` | optional | | +| **permissions** | `{ id: string; 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'>; actions: Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'execute' \| 'manage' \| 'configure' \| 'share' \| 'export' \| 'import' \| 'admin'>[]; scope?: Enum<'global' \| 'tenant' \| 'user' \| 'resource' \| 'plugin'>; … }[]` | ✅ | | +| **groups** | `{ name: string; description: string; permissions: string[] }[]` | optional | | | **defaultGrant** | `Enum<'prompt' \| 'allow' \| 'deny' \| 'inherit'>` | optional | | @@ -175,15 +175,15 @@ Scope of permission application | :--- | :--- | :--- | :--- | | **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 | | +| **permissions** | `{ permissions: { id: string; 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'>; actions: Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'execute' \| 'manage' \| 'configure' \| 'share' \| 'export' \| 'import' \| 'admin'>[]; scope?: Enum<'global' \| 'tenant' \| 'user' \| 'resource' \| 'plugin'>; … }[]; groups?: { name: string; description: string; permissions: string[] }[]; defaultGrant?: Enum<'prompt' \| 'allow' \| 'deny' \| 'inherit'> }` | ✅ | | +| **sandbox** | `{ enabled?: boolean; level?: Enum<'none' \| 'minimal' \| 'standard' \| 'strict' \| 'paranoid'>; runtime?: object; filesystem?: object; … }` | ✅ | | +| **policy** | `{ csp?: object; cors?: object; rateLimit?: object; authentication?: object; … }` | optional | | +| **scanResults** | `{ timestamp: string; scanner: object; status: Enum<'passed' \| 'failed' \| 'warning'>; vulnerabilities?: { cve?: string; id: string; severity: Enum<'critical' \| 'high' \| 'medium' \| 'low' \| 'info'>; category?: string; … }[]; … }[]` | optional | | +| **vulnerabilities** | `{ cve?: string; id: string; severity: Enum<'critical' \| 'high' \| 'medium' \| 'low' \| 'info'>; category?: string; … }[]` | optional | | +| **codeSigning** | `{ signed: boolean; signature?: string; certificate?: string; algorithm?: string; … }` | optional | | +| **certifications** | `{ name: string; issuer: string; issuedDate: string; expiryDate?: string; … }[]` | optional | | +| **securityContact** | `{ email?: string; url?: string; pgpKey?: string }` | optional | | +| **vulnerabilityDisclosure** | `{ policyUrl?: string; responseTime?: integer; bugBounty?: boolean }` | optional | | --- @@ -236,8 +236,8 @@ Type of resource being accessed | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **engine** | `Enum<'v8-isolate' \| 'wasm' \| 'container' \| 'process'>` | ✅ | Execution environment engine | -| **engineConfig** | `Object` | optional | | -| **resourceLimits** | `Object` | optional | | +| **engineConfig** | `{ wasm?: object; container?: object; v8Isolate?: object }` | optional | | +| **resourceLimits** | `{ maxMemory?: integer; maxCpu?: number; timeout?: integer }` | optional | | --- @@ -250,13 +250,13 @@ Type of resource being accessed | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | | | **level** | `Enum<'none' \| 'minimal' \| 'standard' \| 'strict' \| 'paranoid'>` | ✅ | | -| **runtime** | `Object` | optional | Execution environment and isolation settings | -| **filesystem** | `Object` | optional | | -| **network** | `Object` | optional | | -| **process** | `Object` | optional | | -| **memory** | `Object` | optional | | -| **cpu** | `Object` | optional | | -| **environment** | `Object` | optional | | +| **runtime** | `{ engine: Enum<'v8-isolate' \| 'wasm' \| 'container' \| 'process'>; engineConfig?: object; resourceLimits?: object }` | optional | Execution environment and isolation settings | +| **filesystem** | `{ mode: Enum<'none' \| 'readonly' \| 'restricted' \| 'full'>; allowedPaths?: string[]; deniedPaths?: string[]; maxFileSize?: integer }` | optional | | +| **network** | `{ mode: Enum<'none' \| 'local' \| 'restricted' \| 'full'>; allowedHosts?: string[]; deniedHosts?: string[]; allowedPorts?: number[]; … }` | optional | | +| **process** | `{ allowSpawn: boolean; allowedCommands?: string[]; timeout?: integer }` | optional | | +| **memory** | `{ maxHeap?: integer; maxStack?: integer }` | optional | | +| **cpu** | `{ maxCpuPercent?: number; maxThreads?: integer }` | optional | | +| **environment** | `{ mode: Enum<'none' \| 'readonly' \| 'restricted' \| 'full'>; allowedVars?: string[]; deniedVars?: string[] }` | optional | | --- diff --git a/content/docs/references/kernel/plugin-security.mdx b/content/docs/references/kernel/plugin-security.mdx index 02d24a8e1d..9f376d5792 100644 --- a/content/docs/references/kernel/plugin-security.mdx +++ b/content/docs/references/kernel/plugin-security.mdx @@ -49,10 +49,10 @@ Complete dependency graph for a package and its transitive dependencies | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **root** | `Object` | ✅ | Root package of the dependency graph | -| **nodes** | `Object[]` | ✅ | All resolved package nodes in the dependency graph | -| **edges** | `Object[]` | ✅ | Directed edges representing dependency relationships | -| **stats** | `Object` | ✅ | Summary statistics for the dependency graph | +| **root** | `{ id: string; version: string }` | ✅ | Root package of the dependency graph | +| **nodes** | `{ id: string; version: string; dependencies: { name: string; versionConstraint: string; type: Enum<'required' \| 'optional' \| 'peer' \| 'dev'>; resolvedVersion?: string }[]; depth: integer; … }[]` | ✅ | All resolved package nodes in the dependency graph | +| **edges** | `{ from: string; to: string; constraint: string }[]` | ✅ | Directed edges representing dependency relationships | +| **stats** | `{ totalDependencies: integer; directDependencies: integer; maxDepth: integer }` | ✅ | Summary statistics for the dependency graph | --- @@ -67,10 +67,10 @@ A node in the dependency graph representing a resolved package | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique identifier of the package | | **version** | `string` | ✅ | Resolved version of the package | -| **dependencies** | `Object[]` | ✅ | Dependencies required by this package | +| **dependencies** | `{ name: string; versionConstraint: string; type: Enum<'required' \| 'optional' \| 'peer' \| 'dev'>; resolvedVersion?: string }[]` | ✅ | Dependencies required by this package | | **depth** | `integer` | ✅ | Depth level in the dependency tree (0 = root) | | **isDirect** | `boolean` | ✅ | Whether this is a direct (top-level) dependency | -| **metadata** | `Object` | optional | Additional metadata about the package | +| **metadata** | `{ name: string; description?: string; license?: string; homepage?: string }` | optional | Additional metadata about the package | --- @@ -100,8 +100,8 @@ A detected conflict between dependency version requirements | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **package** | `string` | ✅ | Name of the package with conflicting version requirements | -| **conflicts** | `Object[]` | ✅ | List of conflicting version requirements | -| **resolution** | `Object` | optional | Suggested resolution for the conflict | +| **conflicts** | `{ version: string; requestedBy: string[]; constraint: string }[]` | ✅ | List of conflicting version requirements | +| **resolution** | `{ strategy: Enum<'pick-highest' \| 'pick-lowest' \| 'manual'>; version?: string; reason?: string }` | optional | Suggested resolution for the conflict | | **severity** | `Enum<'error' \| 'warning' \| 'info'>` | ✅ | Severity level of the dependency conflict | @@ -116,9 +116,9 @@ Result of a dependency resolution process | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **status** | `Enum<'success' \| 'conflict' \| 'error'>` | ✅ | Overall status of the dependency resolution | -| **graph** | `Object` | optional | Resolved dependency graph if resolution succeeded | -| **conflicts** | `Object[]` | ✅ | List of dependency conflicts detected during resolution | -| **errors** | `Object[]` | ✅ | Errors encountered during dependency resolution | +| **graph** | `{ root: object; nodes: { id: string; version: string; dependencies: { name: string; versionConstraint: string; type: Enum<'required' \| 'optional' \| 'peer' \| 'dev'>; resolvedVersion?: string }[]; depth: integer; … }[]; edges: { from: string; to: string; constraint: string }[]; stats: object }` | optional | Resolved dependency graph if resolution succeeded | +| **conflicts** | `{ package: string; conflicts: { version: string; requestedBy: string[]; constraint: string }[]; resolution?: object; severity: Enum<'error' \| 'warning' \| 'info'> }[]` | ✅ | List of dependency conflicts detected during resolution | +| **errors** | `{ package: string; error: string }[]` | ✅ | Errors encountered during dependency resolution | | **installOrder** | `string[]` | ✅ | Topologically sorted list of package IDs for installation | | **resolvedIn** | `integer` | optional | Time taken to resolve dependencies in milliseconds | @@ -135,10 +135,10 @@ Verifiable provenance and chain of custody for a plugin artifact | :--- | :--- | :--- | :--- | | **pluginId** | `string` | ✅ | Unique identifier of the plugin | | **version** | `string` | ✅ | Version of the plugin artifact | -| **build** | `Object` | ✅ | Build provenance information | -| **artifacts** | `Object[]` | ✅ | List of build artifacts with integrity hashes | -| **signatures** | `Object[]` | ✅ | Cryptographic signatures for the plugin artifact | -| **attestations** | `Object[]` | ✅ | Verification attestations for the plugin | +| **build** | `{ timestamp: string; environment?: object; source?: object; builder?: object }` | ✅ | Build provenance information | +| **artifacts** | `{ filename: string; sha256: string; size: integer }[]` | ✅ | List of build artifacts with integrity hashes | +| **signatures** | `{ algorithm: Enum<'rsa' \| 'ecdsa' \| 'ed25519'>; publicKey: string; signature: string; signedBy: string; … }[]` | ✅ | Cryptographic signatures for the plugin artifact | +| **attestations** | `{ type: Enum<'code-review' \| 'security-scan' \| 'test-results' \| 'ci-build'>; status: Enum<'passed' \| 'failed'>; url?: string; timestamp: string }[]` | ✅ | Verification attestations for the plugin | --- @@ -153,7 +153,7 @@ Trust score and verification status for a plugin | :--- | :--- | :--- | :--- | | **pluginId** | `string` | ✅ | Unique identifier of the plugin | | **score** | `number` | ✅ | Overall trust score from 0 to 100 | -| **components** | `Object` | ✅ | Individual score components contributing to the overall trust score | +| **components** | `{ vendorReputation: number; securityScore: number; codeQuality: number; communityScore: number; … }` | ✅ | Individual score components contributing to the overall trust score | | **level** | `Enum<'verified' \| 'trusted' \| 'neutral' \| 'untrusted' \| 'blocked'>` | ✅ | Computed trust level based on the overall score | | **badges** | `Enum<'official' \| 'verified-vendor' \| 'security-scanned' \| 'code-signed' \| 'open-source' \| 'popular'>[]` | ✅ | Verification badges earned by the plugin | | **updatedAt** | `string` | ✅ | ISO 8601 timestamp when the trust score was last updated | @@ -171,10 +171,10 @@ Software Bill of Materials for a plugin | :--- | :--- | :--- | :--- | | **format** | `Enum<'spdx' \| 'cyclonedx'>` | ✅ | SBOM standard format used | | **version** | `string` | ✅ | Version of the SBOM specification | -| **plugin** | `Object` | ✅ | Metadata about the plugin this SBOM describes | -| **components** | `Object[]` | ✅ | List of software components included in the plugin | +| **plugin** | `{ id: string; version: string; name: string }` | ✅ | Metadata about the plugin this SBOM describes | +| **components** | `{ name: string; version: string; purl?: string; license?: string; … }[]` | ✅ | List of software components included in the plugin | | **generatedAt** | `string` | ✅ | ISO 8601 timestamp when the SBOM was generated | -| **generator** | `Object` | optional | Tool used to generate this SBOM | +| **generator** | `{ name: string; version: string }` | optional | Tool used to generate this SBOM | --- @@ -191,9 +191,9 @@ A single entry in a Software Bill of Materials | **version** | `string` | ✅ | Version of the software component | | **purl** | `string` | optional | Package URL identifier | | **license** | `string` | optional | SPDX license identifier of the component | -| **hashes** | `Object` | optional | Cryptographic hashes for integrity verification | -| **supplier** | `Object` | optional | Supplier information for the component | -| **externalRefs** | `Object[]` | ✅ | External references related to the component | +| **hashes** | `{ sha256?: string; sha512?: string }` | optional | Cryptographic hashes for integrity verification | +| **supplier** | `{ name: string; url?: string }` | optional | Supplier information for the component | +| **externalRefs** | `{ type: Enum<'website' \| 'repository' \| 'documentation' \| 'issue-tracker'>; url: string }[]` | ✅ | External references related to the component | --- @@ -208,12 +208,12 @@ Security policy governing plugin scanning and enforcement | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Unique identifier for the security policy | | **name** | `string` | ✅ | Human-readable name of the security policy | -| **autoScan** | `Object` | ✅ | Automatic security scanning configuration | -| **thresholds** | `Object` | ✅ | Vulnerability count thresholds for policy enforcement | +| **autoScan** | `{ enabled: boolean; frequency: Enum<'on-publish' \| 'daily' \| 'weekly' \| 'monthly'> }` | ✅ | Automatic security scanning configuration | +| **thresholds** | `{ maxCritical: integer; maxHigh: integer; maxMedium: integer }` | ✅ | Vulnerability count thresholds for policy enforcement | | **allowedLicenses** | `string[]` | ✅ | List of SPDX license identifiers that are permitted | | **prohibitedLicenses** | `string[]` | ✅ | List of SPDX license identifiers that are prohibited | -| **codeSigning** | `Object` | optional | Code signing requirements for plugin artifacts | -| **sandbox** | `Object` | optional | Sandbox restrictions for plugin execution | +| **codeSigning** | `{ required: boolean; allowedSigners: string[] }` | optional | Code signing requirements for plugin artifacts | +| **sandbox** | `{ networkAccess: Enum<'none' \| 'localhost' \| 'allowlist' \| 'all'>; allowedDestinations: string[]; filesystemAccess: Enum<'none' \| 'read-only' \| 'temp-only' \| 'full'>; maxMemoryMB?: integer; … }` | optional | Sandbox restrictions for plugin execution | --- @@ -227,14 +227,14 @@ Result of a security scan performed on a plugin | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **scanId** | `string` | ✅ | Unique identifier for this security scan | -| **plugin** | `Object` | ✅ | Plugin that was scanned | +| **plugin** | `{ id: string; version: string }` | ✅ | Plugin that was scanned | | **scannedAt** | `string` | ✅ | ISO 8601 timestamp when the scan was performed | -| **scanner** | `Object` | ✅ | Information about the scanner tool used | +| **scanner** | `{ name: string; version: string }` | ✅ | Information about the scanner tool used | | **status** | `Enum<'passed' \| 'failed' \| 'warning'>` | ✅ | Overall result status of the security scan | -| **vulnerabilities** | `Object[]` | ✅ | List of vulnerabilities discovered during the scan | -| **summary** | `Object` | ✅ | Summary counts of vulnerabilities by severity | -| **licenseIssues** | `Object[]` | ✅ | License compliance issues found during the scan | -| **codeQuality** | `Object` | optional | Code quality analysis results | +| **vulnerabilities** | `{ cve?: string; id: string; title: string; description: string; … }[]` | ✅ | List of vulnerabilities discovered during the scan | +| **summary** | `{ critical: integer; high: integer; medium: integer; low: integer; … }` | ✅ | Summary counts of vulnerabilities by severity | +| **licenseIssues** | `{ package: string; license: string; reason: string; severity: Enum<'error' \| 'warning' \| 'info'> }[]` | ✅ | License compliance issues found during the scan | +| **codeQuality** | `{ score?: number; issues: { type: Enum<'security' \| 'quality' \| 'style'>; severity: Enum<'error' \| 'warning' \| 'info'>; message: string; file?: string; … }[] }` | optional | Code quality analysis results | | **nextScanAt** | `string` | optional | ISO 8601 timestamp for the next scheduled scan | @@ -254,10 +254,10 @@ A known security vulnerability in a package dependency | **description** | `string` | ✅ | Detailed description of the vulnerability | | **severity** | `Enum<'critical' \| 'high' \| 'medium' \| 'low' \| 'info'>` | ✅ | Severity level of this vulnerability | | **cvss** | `number` | optional | CVSS score ranging from 0 to 10 | -| **package** | `Object` | ✅ | Affected package information | +| **package** | `{ name: string; version: string; ecosystem?: string }` | ✅ | Affected package information | | **vulnerableVersions** | `string` | ✅ | Semver range of vulnerable versions | | **patchedVersions** | `string` | optional | Semver range of patched versions | -| **references** | `Object[]` | ✅ | External references related to the vulnerability | +| **references** | `{ type: Enum<'advisory' \| 'article' \| 'report' \| 'web'>; url: string }[]` | ✅ | External references related to the vulnerability | | **cwe** | `string[]` | ✅ | CWE identifiers associated with this vulnerability | | **publishedAt** | `string` | optional | ISO 8601 date when the vulnerability was published | | **mitigation** | `string` | optional | Recommended steps to mitigate the vulnerability | diff --git a/content/docs/references/kernel/plugin-structure.mdx b/content/docs/references/kernel/plugin-structure.mdx index 6f1c7e4b71..259ee69634 100644 --- a/content/docs/references/kernel/plugin-structure.mdx +++ b/content/docs/references/kernel/plugin-structure.mdx @@ -11,7 +11,7 @@ Formal Zod definitions for the Plugin Directory Structure and File Naming conven This can be used by the CLI or IDE extensions to lint project structure. -@see PLUGIN_STANDARDS.md +See also: PLUGIN_STANDARDS.md **Source:** `packages/spec/src/kernel/plugin-structure.zod.ts` diff --git a/content/docs/references/kernel/plugin-validator.mdx b/content/docs/references/kernel/plugin-validator.mdx index 331b726596..269ef2804c 100644 --- a/content/docs/references/kernel/plugin-validator.mdx +++ b/content/docs/references/kernel/plugin-validator.mdx @@ -67,8 +67,8 @@ Plugin metadata for validation | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **valid** | `boolean` | ✅ | Whether the plugin passed validation | -| **errors** | `Object[]` | optional | Validation errors | -| **warnings** | `Object[]` | optional | Validation warnings | +| **errors** | `{ field: string; message: string; code?: string }[]` | optional | Validation errors | +| **warnings** | `{ field: string; message: string; code?: string }[]` | optional | Validation warnings | --- diff --git a/content/docs/references/kernel/plugin-versioning.mdx b/content/docs/references/kernel/plugin-versioning.mdx index 82f06932dd..fc53867169 100644 --- a/content/docs/references/kernel/plugin-versioning.mdx +++ b/content/docs/references/kernel/plugin-versioning.mdx @@ -79,7 +79,7 @@ Compatibility level between versions | **from** | `string` | ✅ | Version being upgraded from | | **to** | `string` | ✅ | Version being upgraded to | | **compatibility** | `Enum<'fully-compatible' \| 'backward-compatible' \| 'deprecated-compatible' \| 'breaking-changes' \| 'incompatible'>` | ✅ | Compatibility level between versions | -| **breakingChanges** | `Object[]` | optional | | +| **breakingChanges** | `{ introducedIn: string; type: Enum<'api-removed' \| 'api-renamed' \| 'api-signature-changed' \| 'behavior-changed' \| 'dependency-changed' \| 'configuration-changed' \| 'protocol-changed'>; description: string; migrationGuide?: string; … }[]` | optional | | | **migrationRequired** | `boolean` | ✅ | | | **migrationComplexity** | `Enum<'trivial' \| 'simple' \| 'moderate' \| 'complex' \| 'major'>` | optional | | | **estimatedMigrationTime** | `number` | optional | | @@ -96,9 +96,9 @@ Compatibility level between versions | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **type** | `Enum<'version-mismatch' \| 'missing-dependency' \| 'circular-dependency' \| 'incompatible-versions' \| 'conflicting-interfaces'>` | ✅ | | -| **plugins** | `Object[]` | ✅ | | +| **plugins** | `{ pluginId: string; version: string; requirement?: string }[]` | ✅ | | | **description** | `string` | ✅ | | -| **resolutions** | `Object[]` | optional | | +| **resolutions** | `{ strategy: Enum<'upgrade' \| 'downgrade' \| 'replace' \| 'disable' \| 'manual'>; description: string; automaticResolution: boolean; riskLevel: Enum<'low' \| 'medium' \| 'high'> }[]` | optional | | | **severity** | `Enum<'critical' \| 'error' \| 'warning' \| 'info'>` | ✅ | | @@ -129,8 +129,8 @@ Compatibility level between versions | **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 | | +| **routing** | `{ condition: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; version: string; priority?: integer }[]` | optional | | +| **rollout** | `{ enabled?: boolean; strategy: Enum<'percentage' \| 'blue-green' \| 'canary'>; percentage?: number; duration?: integer }` | optional | | --- @@ -143,8 +143,8 @@ Compatibility level between versions | :--- | :--- | :--- | :--- | | **pluginId** | `string` | ✅ | | | **currentVersion** | `string` | ✅ | | -| **compatibilityMatrix** | `Object[]` | ✅ | | -| **supportedVersions** | `Object[]` | ✅ | | +| **compatibilityMatrix** | `{ from: string; to: string; compatibility: Enum<'fully-compatible' \| 'backward-compatible' \| 'deprecated-compatible' \| 'breaking-changes' \| 'incompatible'>; breakingChanges?: { introducedIn: string; type: Enum<'api-removed' \| 'api-renamed' \| 'api-signature-changed' \| 'behavior-changed' \| 'dependency-changed' \| 'configuration-changed' \| 'protocol-changed'>; description: string; migrationGuide?: string; … }[]; … }[]` | ✅ | | +| **supportedVersions** | `{ version: string; supported: boolean; endOfLife?: string; securitySupport: boolean }[]` | ✅ | | | **minimumCompatibleVersion** | `string` | optional | Oldest version that can be directly upgraded | @@ -157,8 +157,8 @@ Compatibility level between versions | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | | -| **resolved** | `Object[]` | optional | | -| **conflicts** | `Object[]` | optional | | +| **resolved** | `{ pluginId: string; version: string; resolvedVersion: string }[]` | optional | | +| **conflicts** | `{ type: Enum<'version-mismatch' \| 'missing-dependency' \| 'circular-dependency' \| 'incompatible-versions' \| 'conflicting-interfaces'>; plugins: { pluginId: string; version: string; requirement?: string }[]; description: string; resolutions?: { strategy: Enum<'upgrade' \| 'downgrade' \| 'replace' \| 'disable' \| 'manual'>; description: string; automaticResolution: boolean; riskLevel: Enum<'low' \| 'medium' \| 'high'> }[]; … }[]` | optional | | | **warnings** | `string[]` | optional | | | **installationOrder** | `string[]` | optional | Plugin IDs in order they should be installed | | **dependencyGraph** | `Record` | optional | Map of plugin ID to its dependencies | @@ -173,16 +173,16 @@ Compatibility level between versions | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **pluginId** | `string` | ✅ | | -| **version** | `Object` | ✅ | Semantic version number | +| **version** | `{ major: integer; minor: integer; patch: integer; preRelease?: string; … }` | ✅ | Semantic version number | | **versionString** | `string` | ✅ | Full version string (e.g., 1.2.3-beta.1+build.123) | | **releaseDate** | `string` | ✅ | | | **releaseNotes** | `string` | optional | | -| **breakingChanges** | `Object[]` | optional | | -| **deprecations** | `Object[]` | optional | | -| **compatibilityMatrix** | `Object[]` | optional | | -| **securityFixes** | `Object[]` | optional | | -| **statistics** | `Object` | optional | | -| **support** | `Object` | ✅ | | +| **breakingChanges** | `{ introducedIn: string; type: Enum<'api-removed' \| 'api-renamed' \| 'api-signature-changed' \| 'behavior-changed' \| 'dependency-changed' \| 'configuration-changed' \| 'protocol-changed'>; description: string; migrationGuide?: string; … }[]` | optional | | +| **deprecations** | `{ feature: string; deprecatedIn: string; removeIn?: string; reason: string; … }[]` | optional | | +| **compatibilityMatrix** | `{ from: string; to: string; compatibility: Enum<'fully-compatible' \| 'backward-compatible' \| 'deprecated-compatible' \| 'breaking-changes' \| 'incompatible'>; breakingChanges?: { introducedIn: string; type: Enum<'api-removed' \| 'api-renamed' \| 'api-signature-changed' \| 'behavior-changed' \| 'dependency-changed' \| 'configuration-changed' \| 'protocol-changed'>; description: string; migrationGuide?: string; … }[]; … }[]` | optional | | +| **securityFixes** | `{ cve?: string; severity: Enum<'critical' \| 'high' \| 'medium' \| 'low'>; description: string; fixedIn: string }[]` | optional | | +| **statistics** | `{ downloads?: integer; installations?: integer; ratings?: number }` | optional | | +| **support** | `{ status: Enum<'active' \| 'maintenance' \| 'deprecated' \| 'eol'>; endOfLife?: string; securitySupport: boolean }` | ✅ | | --- @@ -278,7 +278,7 @@ Type: `string` Any version -Type: `string` +Type: `'*'` --- @@ -286,7 +286,7 @@ Type: `string` Latest stable version -Type: `string` +Type: `'latest'` --- diff --git a/content/docs/references/kernel/service-registry.mdx b/content/docs/references/kernel/service-registry.mdx index 19aa53513a..74dcd0bf89 100644 --- a/content/docs/references/kernel/service-registry.mdx +++ b/content/docs/references/kernel/service-registry.mdx @@ -75,7 +75,7 @@ const result = ScopeConfig.parse(data); | **scope** | `Enum<'singleton' \| 'transient' \| 'scoped'>` | ✅ | Service scope type | | **factoryType** | `Enum<'sync' \| 'async'>` | ✅ | Whether factory is synchronous or asynchronous | | **singleton** | `boolean` | ✅ | Whether to cache the factory result (singleton pattern) | -| **cluster** | `Object` | optional | Cluster scope & leader strategy for this service. | +| **cluster** | `{ clusterScope: Enum<'node' \| 'cluster'>; leaderStrategy?: Enum<'leader-elected' \| 'partitioned' \| 'idempotent-broadcast'>; clusterId?: string }` | optional | Cluster scope & leader strategy for this service. | --- @@ -91,7 +91,7 @@ const result = ScopeConfig.parse(data); | **type** | `string` | optional | Service type or interface name | | **registeredAt** | `integer` | optional | Unix timestamp in milliseconds when service was registered | | **metadata** | `Record` | optional | Additional service-specific metadata | -| **cluster** | `Object` | optional | Cluster scope & leader strategy. See cluster-semantics.mdx §5. | +| **cluster** | `{ clusterScope: Enum<'node' \| 'cluster'>; leaderStrategy?: Enum<'leader-elected' \| 'partitioned' \| 'idempotent-broadcast'>; clusterId?: string }` | optional | Cluster scope & leader strategy. See cluster-semantics.mdx §5. | --- diff --git a/content/docs/references/kernel/startup-orchestrator.mdx b/content/docs/references/kernel/startup-orchestrator.mdx index b1d558007a..eeeeb08946 100644 --- a/content/docs/references/kernel/startup-orchestrator.mdx +++ b/content/docs/references/kernel/startup-orchestrator.mdx @@ -54,8 +54,8 @@ const result = HealthStatus.parse(data); | **plugin** | `Record` | ✅ | Plugin metadata | | **success** | `boolean` | ✅ | Whether the plugin started successfully | | **duration** | `number` | ✅ | Time taken to start the plugin in milliseconds | -| **error** | `Object` | optional | Serializable error representation if startup failed | -| **health** | `Object` | optional | Health status after startup if health check was enabled | +| **error** | `{ name: string; message: string; stack?: string; code?: string }` | optional | Serializable error representation if startup failed | +| **health** | `{ healthy: boolean; timestamp: integer; details?: Record; message?: string }` | optional | Health status after startup if health check was enabled | --- @@ -81,7 +81,7 @@ const result = HealthStatus.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **results** | `Object[]` | ✅ | Startup results for each plugin | +| **results** | `{ plugin: object; success: boolean; duration: number; error?: object; … }[]` | ✅ | Startup results for each plugin | | **totalDuration** | `number` | ✅ | Total time taken for all plugins in milliseconds | | **allSuccessful** | `boolean` | ✅ | Whether all plugins started successfully | | **rolledBack** | `string[]` | optional | Names of plugins that were rolled back | diff --git a/content/docs/references/kernel/state-machine.mdx b/content/docs/references/kernel/state-machine.mdx index e47f220ac5..a0d9a5e15c 100644 --- a/content/docs/references/kernel/state-machine.mdx +++ b/content/docs/references/kernel/state-machine.mdx @@ -30,7 +30,7 @@ const result = Event.parse(data); | **id** | `string` | optional | Unique event identifier | | **name** | `string` | ✅ | Event name (lowercase with dots, e.g., user.created, order.paid) | | **payload** | `any` | ✅ | Event payload schema | -| **metadata** | `Object` | ✅ | Event metadata | +| **metadata** | `{ source: string; timestamp: string; userId?: string; tenantId?: string; … }` | ✅ | Event metadata | --- diff --git a/content/docs/references/qa/testing.mdx b/content/docs/references/qa/testing.mdx index 9a3fac99c4..55c49dd6ff 100644 --- a/content/docs/references/qa/testing.mdx +++ b/content/docs/references/qa/testing.mdx @@ -106,10 +106,10 @@ A complete test scenario with setup, execution steps, and teardown | **name** | `string` | ✅ | Scenario name for test reports | | **description** | `string` | optional | Detailed description of the test scenario | | **tags** | `string[]` | optional | Tags for filtering and categorization (e.g. "critical", "regression", "crm") | -| **setup** | `Object[]` | optional | Steps to run before main test (preconditions) | -| **steps** | `Object[]` | ✅ | Main test sequence to execute | -| **teardown** | `Object[]` | optional | Steps to cleanup after test execution | -| **requires** | `Object` | optional | Environment requirements for this scenario | +| **setup** | `{ name: string; description?: string; action: object; assertions?: { field: string; operator: Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'is_null' \| 'not_null' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'error'>; expectedValue: any }[]; … }[]` | optional | Steps to run before main test (preconditions) | +| **steps** | `{ name: string; description?: string; action: object; assertions?: { field: string; operator: Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'is_null' \| 'not_null' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'error'>; expectedValue: any }[]; … }[]` | ✅ | Main test sequence to execute | +| **teardown** | `{ name: string; description?: string; action: object; assertions?: { field: string; operator: Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'is_null' \| 'not_null' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'error'>; expectedValue: any }[]; … }[]` | optional | Steps to cleanup after test execution | +| **requires** | `{ params?: string[]; plugins?: string[] }` | optional | Environment requirements for this scenario | --- @@ -124,8 +124,8 @@ A single step in a test scenario, consisting of an action and optional assertion | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Step name for identification in test reports | | **description** | `string` | optional | Human-readable description of what this step tests | -| **action** | `Object` | ✅ | The action to execute in this step | -| **assertions** | `Object[]` | optional | Assertions to validate after the action completes | +| **action** | `{ type: Enum<'create_record' \| 'update_record' \| 'delete_record' \| 'read_record' \| 'query_records' \| 'api_call' \| 'run_script' \| 'wait'>; target: string; payload?: Record; user?: string }` | ✅ | The action to execute in this step | +| **assertions** | `{ field: string; operator: Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'is_null' \| 'not_null' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'error'>; expectedValue: any }[]` | optional | Assertions to validate after the action completes | | **capture** | `Record` | optional | Map result fields to context variables: `{ "newId": "body.id" }` | @@ -140,7 +140,7 @@ A collection of test scenarios grouped into a test suite | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Test suite name | -| **scenarios** | `Object[]` | ✅ | List of test scenarios in this suite | +| **scenarios** | `{ id: string; name: string; description?: string; tags?: string[]; … }[]` | ✅ | List of test scenarios in this suite | --- diff --git a/content/docs/references/security/explain.mdx b/content/docs/references/security/explain.mdx index c9a15c196f..98fb45f473 100644 --- a/content/docs/references/security/explain.mdx +++ b/content/docs/references/security/explain.mdx @@ -71,8 +71,8 @@ const result = AccessMatrix.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **version** | `number` | ✅ | | -| **entries** | `Object[]` | ✅ | | +| **version** | `'1'` | ✅ | | +| **entries** | `{ permissionSet: string; object: string; create: boolean; read: boolean; … }[]` | ✅ | | --- @@ -121,10 +121,10 @@ ADR-0095 D2 posture rung — PLATFORM_ADMIN crosses the tenant wall where object | **allowed** | `boolean` | ✅ | | | **object** | `string` | ✅ | | | **operation** | `Enum<'read' \| 'create' \| 'update' \| 'delete' \| 'transfer' \| 'restore' \| 'purge'>` | ✅ | | -| **principal** | `Object` | ✅ | | -| **layers** | `Object[]` | ✅ | | +| **principal** | `{ userId: string \| null; positions: string[]; permissionSets: string[]; principalKind?: Enum<'human' \| 'agent' \| 'service' \| 'guest' \| 'system'>; … }` | ✅ | | +| **layers** | `{ layer: Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| 'fls' \| 'owd_baseline' \| 'depth' \| 'sharing' \| 'vama_bypass' \| 'rls'>; kernelTier?: Enum<'layer_0_tenant' \| 'layer_1_business'>; verdict: Enum<'grants' \| 'denies' \| 'narrows' \| 'widens' \| 'neutral' \| 'not_applicable'>; detail: string; … }[]` | ✅ | | | **readFilter** | `any` | optional | | -| **record** | `Object` | optional | Row-level verdict for the specific record; set only for record-grained requests. | +| **record** | `{ recordId: string; visible: boolean; decidedBy?: Enum<'tenant_isolation' \| 'principal' \| 'required_permissions' \| 'object_crud' \| 'fls' \| 'owd_baseline' \| 'depth' \| 'sharing' \| 'vama_bypass' \| 'rls'> }` | optional | Row-level verdict for the specific record; set only for record-grained requests. | --- @@ -139,8 +139,8 @@ ADR-0095 D2 posture rung — PLATFORM_ADMIN crosses the tenant wall where object | **kernelTier** | `Enum<'layer_0_tenant' \| 'layer_1_business'>` | optional | ADR-0095 kernel layer: layer_0_tenant = the always-first org wall; layer_1_business = business RLS/sharing/ownership. | | **verdict** | `Enum<'grants' \| 'denies' \| 'narrows' \| 'widens' \| 'neutral' \| 'not_applicable'>` | ✅ | | | **detail** | `string` | ✅ | | -| **contributors** | `Object[]` | ✅ | | -| **record** | `Object` | optional | Row-level determination for the specific record under explanation; set only for record-grained requests. | +| **contributors** | `{ kind: Enum<'permission_set' \| 'position' \| 'system'>; name: string; via?: string; state?: Enum<'active' \| 'expired'> }[]` | ✅ | | +| **record** | `{ outcome: Enum<'admitted' \| 'excluded' \| 'not_evaluated'>; rowFilter?: any; matchesRecord?: boolean; rules: { kind: Enum<'tenant_filter' \| 'owd_baseline' \| 'ownership' \| 'record_share' \| 'sharing_rule' \| 'team' \| 'territory' \| 'rls_policy'>; name: string; grants?: Enum<'read' \| 'edit' \| 'full'>; via?: string; … }[]; … }` | optional | Row-level determination for the specific record under explanation; set only for record-grained requests. | --- @@ -185,7 +185,7 @@ ADR-0095 D2 posture rung — PLATFORM_ADMIN crosses the tenant wall where object | **outcome** | `Enum<'admitted' \| 'excluded' \| 'not_evaluated'>` | ✅ | This layer's row-level outcome for the record: admitted, excluded, or not_evaluated (skipped/not row-scoped). | | **rowFilter** | `any` | optional | The effective row predicate this layer contributed for the record set (null = unrestricted, __deny_all__ = zero rows). | | **matchesRecord** | `boolean` | optional | Whether the specific record satisfies rowFilter — the judgement behind outcome. | -| **rules** | `Object[]` | ✅ | Concrete rules, shares, or policies this layer evaluated against the record, in evaluation order. | +| **rules** | `{ kind: Enum<'tenant_filter' \| 'owd_baseline' \| 'ownership' \| 'record_share' \| 'sharing_rule' \| 'team' \| 'territory' \| 'rls_policy'>; name: string; grants?: Enum<'read' \| 'edit' \| 'full'>; via?: string; … }[]` | ✅ | Concrete rules, shares, or policies this layer evaluated against the record, in evaluation order. | | **detail** | `string` | optional | Human-readable, record-specific explanation of this layer's outcome. | diff --git a/content/docs/references/security/permission.mdx b/content/docs/references/security/permission.mdx index ddb6baea0b..e57bffcd93 100644 --- a/content/docs/references/security/permission.mdx +++ b/content/docs/references/security/permission.mdx @@ -106,13 +106,13 @@ const result = AdminScope.parse(data); | **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] 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 | +| **objects** | `Record` | ✅ | Entity permissions | +| **fields** | `Record` | optional | Field level security | | **systemPermissions** | `string[]` | optional | System level capabilities | | **tabPermissions** | `Record>` | optional | App/tab visibility: visible, hidden, default_on (shown by default), default_off (available but hidden initially) | -| **rowLevelSecurity** | `Object[]` | optional | Row-level security policies (see rls.zod.ts for full spec) | +| **rowLevelSecurity** | `{ name: string; label?: string; description?: string; object: string; … }[]` | optional | Row-level security policies (see rls.zod.ts for full spec) | | **contextVariables** | `Record` | optional | Context variables for RLS evaluation | -| **adminScope** | `Object` | optional | [ADR-0090 D12] Scoped delegated-administration grant (BU subtree + assignable-set allowlist) | +| **adminScope** | `{ businessUnit: string; includeSubtree: boolean; manageAssignments: boolean; manageBindings: boolean; … }` | optional | [ADR-0090 D12] Scoped delegated-administration grant (BU subtree + assignable-set allowlist) | --- diff --git a/content/docs/references/security/rls.mdx b/content/docs/references/security/rls.mdx index fef61d7884..426381ab5d 100644 --- a/content/docs/references/security/rls.mdx +++ b/content/docs/references/security/rls.mdx @@ -141,9 +141,9 @@ ObjectStack RLS: 4. **Context Variables**: Ensure current_user context is always set -@see https://www.postgresql.org/docs/current/ddl-rowsecurity.html +See also: https://www.postgresql.org/docs/current/ddl-rowsecurity.html -@see https://help.salesforce.com/s/articleView?id=sf.security_sharing_rules.htm +See also: https://help.salesforce.com/s/articleView?id=sf.security_sharing_rules.htm **Source:** `packages/spec/src/security/rls.zod.ts` diff --git a/content/docs/references/security/sharing.mdx b/content/docs/references/security/sharing.mdx index 461d2187c6..cee6cd567c 100644 --- a/content/docs/references/security/sharing.mdx +++ b/content/docs/references/security/sharing.mdx @@ -37,9 +37,9 @@ const result = CriteriaSharingRule.parse(data); | **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"` | +| **sharedWith** | `{ type: Enum<'user' \| 'group' \| 'position' \| 'unit_and_subordinates' \| 'guest'>; value: string }` | ✅ | The recipient of the shared access | +| **type** | `'criteria'` | ✅ | | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). e.g. P`record.department == "Sales"` | --- @@ -68,9 +68,9 @@ const result = CriteriaSharingRule.parse(data); | **object** | `string` | ✅ | Target Object Name | | **active** | `boolean` | ✅ | | | **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | ✅ | | -| **sharedWith** | `Object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **ownedBy** | `Object` | ✅ | Source group/position whose records are being shared | +| **sharedWith** | `{ type: Enum<'user' \| 'group' \| 'position' \| 'unit_and_subordinates' \| 'guest'>; value: string }` | ✅ | The recipient of the shared access | +| **type** | `'owner'` | ✅ | | +| **ownedBy** | `{ type: Enum<'user' \| 'group' \| 'position' \| 'unit_and_subordinates' \| 'guest'>; value: string }` | ✅ | Source group/position whose records are being shared | --- @@ -119,9 +119,9 @@ This schema accepts one of the following structures: | **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"` | +| **sharedWith** | `{ type: Enum<'user' \| 'group' \| 'position' \| 'unit_and_subordinates' \| 'guest'>; value: string }` | ✅ | The recipient of the shared access | +| **type** | `'criteria'` | ✅ | | +| **condition** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). e.g. P`record.department == "Sales"` | --- @@ -139,9 +139,9 @@ This schema accepts one of the following structures: | **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 | +| **sharedWith** | `{ type: Enum<'user' \| 'group' \| 'position' \| 'unit_and_subordinates' \| 'guest'>; value: string }` | ✅ | The recipient of the shared access | +| **type** | `'owner'` | ✅ | | +| **ownedBy** | `{ type: Enum<'user' \| 'group' \| 'position' \| 'unit_and_subordinates' \| 'guest'>; value: string }` | ✅ | Source group/position whose records are being shared | --- diff --git a/content/docs/references/shared/expression.mdx b/content/docs/references/shared/expression.mdx index 63624e5152..649023b3cf 100644 --- a/content/docs/references/shared/expression.mdx +++ b/content/docs/references/shared/expression.mdx @@ -39,7 +39,7 @@ routed through this schema — they stay driver-native because their security posture and portability story differ. -@see content/docs/concepts/north-star.mdx §8 "No private expression DSL" +See also: content/docs/concepts/north-star.mdx §8 "No private expression DSL" **Source:** `packages/spec/src/shared/expression.zod.ts` @@ -78,7 +78,7 @@ Type: `string` | **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | | **source** | `string` | optional | | | **ast** | `any` | optional | | -| **meta** | `Object` | optional | | +| **meta** | `{ rationale?: string; generatedBy?: string }` | optional | | --- @@ -94,7 +94,7 @@ Type: `string` | **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | | **source** | `string` | optional | | | **ast** | `any` | optional | | -| **meta** | `Object` | optional | | +| **meta** | `{ rationale?: string; generatedBy?: string }` | optional | | --- @@ -132,7 +132,7 @@ Type: `string` | **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | | **source** | `string` | optional | | | **ast** | `any` | optional | | -| **meta** | `Object` | optional | | +| **meta** | `{ rationale?: string; generatedBy?: string }` | optional | | --- @@ -160,7 +160,7 @@ Type: `string` | **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | | **source** | `string` | optional | | | **ast** | `any` | optional | | -| **meta** | `Object` | optional | | +| **meta** | `{ rationale?: string; generatedBy?: string }` | optional | | --- @@ -186,7 +186,7 @@ Type: `string` | **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | | **source** | `string` | optional | | | **ast** | `any` | optional | | -| **meta** | `Object` | optional | | +| **meta** | `{ rationale?: string; generatedBy?: string }` | optional | | --- @@ -214,7 +214,7 @@ Type: `string` | **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ | | | **source** | `string` | optional | | | **ast** | `any` | optional | | -| **meta** | `Object` | optional | | +| **meta** | `{ rationale?: string; generatedBy?: string }` | optional | | --- diff --git a/content/docs/references/shared/mapping.mdx b/content/docs/references/shared/mapping.mdx index 1fd66457c9..33dd6043f2 100644 --- a/content/docs/references/shared/mapping.mdx +++ b/content/docs/references/shared/mapping.mdx @@ -79,7 +79,7 @@ const result = FieldMapping.parse(data); | :--- | :--- | :--- | :--- | | **source** | `string` | ✅ | Source field name | | **target** | `string` | ✅ | Target field name | -| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | +| **transform** | `{ type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record }` | optional | Transformation to apply | | **defaultValue** | `any` | optional | Default if source is null/undefined | @@ -101,7 +101,7 @@ Set a constant value | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'constant'` | ✅ | | | **value** | `any` | ✅ | Constant value to use | --- @@ -116,7 +116,7 @@ Cast to a specific data type | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'cast'` | ✅ | | | **targetType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date'>` | ✅ | Target data type | --- @@ -131,7 +131,7 @@ Lookup value from another table | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'lookup'` | ✅ | | | **table** | `string` | ✅ | Lookup table name | | **keyField** | `string` | ✅ | Field to match on | | **valueField** | `string` | ✅ | Field to retrieve | @@ -148,8 +148,8 @@ Custom JavaScript transformation | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string \| Object` | ✅ | JS expression (dialect="js" recommended). e.g. value.toUpperCase() | +| **type** | `'javascript'` | ✅ | | +| **expression** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | JS expression (dialect="js" recommended). e.g. value.toUpperCase() | --- @@ -163,7 +163,7 @@ Map values using a dictionary | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'map'` | ✅ | | | **mappings** | `Record` | ✅ | Value mappings (e.g., `{"Active": "active"}`) | --- diff --git a/content/docs/references/shared/protection.mdx b/content/docs/references/shared/protection.mdx index 924c3e41f9..7e90ee4efe 100644 --- a/content/docs/references/shared/protection.mdx +++ b/content/docs/references/shared/protection.mdx @@ -15,7 +15,7 @@ tenant's Studio) is allowed to mutate. Internally this is what gets translated into the `_lock` / `_lockReason` / `_lockDocsUrl` -private envelope (`kernel/metadata-protection.zod.ts`) that the +private envelope (`[kernel/metadata-protection.zod.ts](/docs/references/kernel/metadata-protection)`) that the protocol layer enforces. @@ -63,7 +63,7 @@ docsUrl: 'https://docs.objectstack.ai/adr/0010-metadata-protection', The loader (`metadata/plugin.ts` + `objectql/registry.ts`) calls -[applyProtection](applyProtection) to translate this block into the private +`applyProtection` to translate this block into the private `_lock` envelope at registration time. Authors should NEVER set @@ -75,7 +75,7 @@ See also: - ADR-0010 §3.7 — Future work → now implemented. -- `kernel/metadata-protection.zod.ts` — the runtime envelope. +- `[kernel/metadata-protection.zod.ts](/docs/references/kernel/metadata-protection)` — the runtime envelope. **Source:** `packages/spec/src/shared/protection.zod.ts` diff --git a/content/docs/references/studio/flow-builder.mdx b/content/docs/references/studio/flow-builder.mdx index 0f7c71f5b9..c2c4253c05 100644 --- a/content/docs/references/studio/flow-builder.mdx +++ b/content/docs/references/studio/flow-builder.mdx @@ -77,11 +77,11 @@ Studio Flow Builder configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **snap** | `Object` | ✅ | Canvas snap-to-grid settings | -| **zoom** | `Object` | ✅ | Canvas zoom settings | +| **snap** | `{ enabled: boolean; gridSize: integer; showGrid: boolean }` | ✅ | Canvas snap-to-grid settings | +| **zoom** | `{ min: number; max: number; default: number; step: number }` | ✅ | Canvas zoom settings | | **layoutAlgorithm** | `Enum<'dagre' \| 'elk' \| 'force' \| 'manual'>` | ✅ | Default auto-layout algorithm | | **layoutDirection** | `Enum<'TB' \| 'BT' \| 'LR' \| 'RL'>` | ✅ | Default auto-layout direction | -| **nodeDescriptors** | `Object[]` | optional | Custom node render descriptors (merged with built-in defaults) | +| **nodeDescriptors** | `{ action: string; shape: Enum<'rounded_rect' \| 'circle' \| 'diamond' \| 'parallelogram' \| 'hexagon' \| 'diamond_thick' \| 'attached_circle' \| 'screen_rect'>; icon: string; defaultLabel: string; … }[]` | optional | Custom node render descriptors (merged with built-in defaults) | | **showMinimap** | `boolean` | ✅ | Show minimap panel | | **showPropertyPanel** | `boolean` | ✅ | Show property panel | | **showPalette** | `boolean` | ✅ | Show node palette sidebar | @@ -104,7 +104,7 @@ Canvas layout and visual data for a flow edge | **style** | `Enum<'solid' \| 'dashed' \| 'dotted' \| 'bold' \| 'back'>` | ✅ | Line style | | **color** | `string` | ✅ | Edge line color | | **labelPosition** | `number` | ✅ | Position of the condition label along the edge | -| **waypoints** | `Object[]` | optional | Manual waypoints for edge routing | +| **waypoints** | `{ x: number; y: number }[]` | optional | Manual waypoints for edge routing | | **animated** | `boolean` | ✅ | Show animated flow indicator | diff --git a/content/docs/references/studio/object-designer.mdx b/content/docs/references/studio/object-designer.mdx index f79eacab2c..9b3109a7e6 100644 --- a/content/docs/references/studio/object-designer.mdx +++ b/content/docs/references/studio/object-designer.mdx @@ -127,7 +127,7 @@ const result = ERDiagramConfig.parse(data); | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable ER diagram panel | | **layout** | `Enum<'force' \| 'hierarchy' \| 'grid' \| 'circular'>` | ✅ | Default layout algorithm | -| **nodeDisplay** | `Object` | ✅ | Node display configuration | +| **nodeDisplay** | `{ showFields: boolean; maxFieldsVisible: number; showFieldTypes: boolean; showRequiredIndicator: boolean; … }` | ✅ | Node display configuration | | **showMinimap** | `boolean` | ✅ | Show minimap for large diagrams | | **zoomControls** | `boolean` | ✅ | Show zoom in/out/fit controls | | **minZoom** | `number` | ✅ | Minimum zoom level | @@ -184,8 +184,8 @@ ER diagram layout algorithm | **dragReorder** | `boolean` | ✅ | Enable drag-and-drop field reordering | | **showFieldGroups** | `boolean` | ✅ | Show field group headers | | **showPropertyPanel** | `boolean` | ✅ | Show the right-side property panel | -| **propertySections** | `Object[]` | ✅ | Property panel section definitions | -| **fieldGroups** | `Object[]` | ✅ | Field group definitions | +| **propertySections** | `{ key: string; label: string; icon?: string; defaultExpanded: boolean; … }[]` | ✅ | Property panel section definitions | +| **fieldGroups** | `{ key: string; label: string; icon?: string; defaultExpanded: boolean; … }[]` | ✅ | Field group definitions | | **paginationThreshold** | `number` | ✅ | Number of fields before pagination is enabled | | **batchOperations** | `boolean` | ✅ | Enable batch add/remove field operations | | **showUsageStats** | `boolean` | ✅ | Show field usage statistics | @@ -230,11 +230,11 @@ ER diagram layout algorithm | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **defaultView** | `Enum<'field-editor' \| 'relationship-mapper' \| 'er-diagram' \| 'object-manager'>` | ✅ | Default view | -| **fieldEditor** | `Object` | ✅ | Field editor configuration | -| **relationshipMapper** | `Object` | ✅ | Relationship mapper configuration | -| **erDiagram** | `Object` | ✅ | ER diagram configuration | -| **objectManager** | `Object` | ✅ | Object manager configuration | -| **objectPreview** | `Object` | ✅ | Object preview configuration | +| **fieldEditor** | `{ inlineEditing: boolean; dragReorder: boolean; showFieldGroups: boolean; showPropertyPanel: boolean; … }` | ✅ | Field editor configuration | +| **relationshipMapper** | `{ visualCreation: boolean; showReverseRelationships: boolean; showCascadeWarnings: boolean; displayConfig: { type: Enum<'lookup' \| 'master_detail' \| 'tree'>; lineStyle: Enum<'solid' \| 'dashed' \| 'dotted'>; color: string; highlightColor: string; … }[] }` | ✅ | Relationship mapper configuration | +| **erDiagram** | `{ enabled: boolean; layout: Enum<'force' \| 'hierarchy' \| 'grid' \| 'circular'>; nodeDisplay: object; showMinimap: boolean; … }` | ✅ | ER diagram configuration | +| **objectManager** | `{ defaultDisplayMode: Enum<'table' \| 'cards' \| 'tree'>; defaultSortField: Enum<'name' \| 'label' \| 'fieldCount' \| 'updatedAt'>; defaultSortDirection: Enum<'asc' \| 'desc'>; defaultFilter: object; … }` | ✅ | Object manager configuration | +| **objectPreview** | `{ tabs: { key: string; label: string; icon?: string; enabled: boolean; … }[]; defaultTab: string; showHeader: boolean; showBreadcrumbs: boolean }` | ✅ | Object preview configuration | --- @@ -292,7 +292,7 @@ Object list display mode | **defaultDisplayMode** | `Enum<'table' \| 'cards' \| 'tree'>` | ✅ | Default list display mode | | **defaultSortField** | `Enum<'name' \| 'label' \| 'fieldCount' \| 'updatedAt'>` | ✅ | Default sort field | | **defaultSortDirection** | `Enum<'asc' \| 'desc'>` | ✅ | Default sort direction | -| **defaultFilter** | `Object` | ✅ | Default filter configuration | +| **defaultFilter** | `{ package?: string; tags?: string[]; includeSystem: boolean; includeAbstract: boolean; … }` | ✅ | Default filter configuration | | **showFieldCount** | `boolean` | ✅ | Show field count badge | | **showRelationshipCount** | `boolean` | ✅ | Show relationship count badge | | **showQuickPreview** | `boolean` | ✅ | Show quick field preview tooltip on hover | @@ -310,7 +310,7 @@ Object list display mode | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **tabs** | `Object[]` | ✅ | Object detail preview tabs | +| **tabs** | `{ key: string; label: string; icon?: string; enabled: boolean; … }[]` | ✅ | Object detail preview tabs | | **defaultTab** | `string` | ✅ | Default active tab key | | **showHeader** | `boolean` | ✅ | Show object summary header | | **showBreadcrumbs** | `boolean` | ✅ | Show navigation breadcrumbs | @@ -371,7 +371,7 @@ Object list sort field | **visualCreation** | `boolean` | ✅ | Enable drag-to-create relationships | | **showReverseRelationships** | `boolean` | ✅ | Show reverse/child-to-parent relationships | | **showCascadeWarnings** | `boolean` | ✅ | Show cascade delete behavior warnings | -| **displayConfig** | `Object[]` | ✅ | Visual config per relationship type | +| **displayConfig** | `{ type: Enum<'lookup' \| 'master_detail' \| 'tree'>; lineStyle: Enum<'solid' \| 'dashed' \| 'dotted'>; color: string; highlightColor: string; … }[]` | ✅ | Visual config per relationship type | --- diff --git a/content/docs/references/studio/plugin.mdx b/content/docs/references/studio/plugin.mdx index 7b17afff77..1b58a79581 100644 --- a/content/docs/references/studio/plugin.mdx +++ b/content/docs/references/studio/plugin.mdx @@ -215,12 +215,12 @@ const result = ActionContribution.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **metadataViewers** | `Object[]` | ✅ | | -| **sidebarGroups** | `Object[]` | ✅ | | -| **actions** | `Object[]` | ✅ | | -| **metadataIcons** | `Object[]` | ✅ | | -| **panels** | `Object[]` | ✅ | | -| **commands** | `Object[]` | ✅ | | +| **metadataViewers** | `{ id: string; metadataTypes: string[]; label: string; priority: number; … }[]` | ✅ | | +| **sidebarGroups** | `{ key: string; label: string; icon?: string; metadataTypes: string[]; … }[]` | ✅ | | +| **actions** | `{ id: string; label: string; icon?: string; location: Enum<'toolbar' \| 'contextMenu' \| 'commandPalette'>; … }[]` | ✅ | | +| **metadataIcons** | `{ metadataType: string; label: string; icon: string }[]` | ✅ | | +| **panels** | `{ id: string; label: string; icon?: string; location: Enum<'bottom' \| 'right' \| 'modal'> }[]` | ✅ | | +| **commands** | `{ id: string; label: string; shortcut?: string; icon?: string }[]` | ✅ | | --- @@ -236,7 +236,7 @@ const result = ActionContribution.parse(data); | **version** | `string` | ✅ | Plugin version | | **description** | `string` | optional | Plugin description | | **author** | `string` | optional | Author | -| **contributes** | `Object` | ✅ | | +| **contributes** | `{ metadataViewers: { id: string; metadataTypes: string[]; label: string; priority: number; … }[]; sidebarGroups: { key: string; label: string; icon?: string; metadataTypes: string[]; … }[]; actions: { id: string; label: string; icon?: string; location: Enum<'toolbar' \| 'contextMenu' \| 'commandPalette'>; … }[]; metadataIcons: { metadataType: string; label: string; icon: string }[]; … }` | ✅ | | | **activationEvents** | `string[]` | ✅ | | diff --git a/content/docs/references/system/app-install.mdx b/content/docs/references/system/app-install.mdx index a1acedbe86..00ff169bc9 100644 --- a/content/docs/references/system/app-install.mdx +++ b/content/docs/references/system/app-install.mdx @@ -50,7 +50,7 @@ App compatibility check result | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **compatible** | `boolean` | ✅ | Whether the app is compatible | -| **issues** | `Object[]` | ✅ | Compatibility issues | +| **issues** | `{ severity: Enum<'error' \| 'warning'>; message: string; category: Enum<'kernel_version' \| 'object_conflict' \| 'dependency_missing' \| 'quota_exceeded'> }[]` | ✅ | Compatibility issues | --- diff --git a/content/docs/references/system/audit.mdx b/content/docs/references/system/audit.mdx index 5af34269b9..85512dd9f5 100644 --- a/content/docs/references/system/audit.mdx +++ b/content/docs/references/system/audit.mdx @@ -51,16 +51,16 @@ const result = AuditConfig.parse(data); | **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 | +| **storage** | `{ type: Enum<'database' \| 'elasticsearch' \| 'mongodb' \| 'clickhouse' \| 's3' \| 'gcs' \| 'azure_blob' \| 'custom'>; connectionString?: string; config?: Record; bufferEnabled?: boolean; … }` | ✅ | Storage configuration | +| **retentionPolicy** | `{ retentionDays?: integer; archiveAfterRetention?: boolean; archiveStorage?: object; customRetention?: Record; … }` | optional | Retention policy | +| **suspiciousActivityRules** | `{ id: string; name: string; description?: string; enabled?: boolean; … }[]` | 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 | +| **customHandlers** | `{ eventType: 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'>; handlerId: string }[]` | optional | Custom event handler references | +| **compliance** | `{ standards?: Enum<'sox' \| 'hipaa' \| 'gdpr' \| 'pci_dss' \| 'iso_27001' \| 'fedramp'>[]; immutableLogs?: boolean; requireSigning?: boolean; signingKey?: string }` | optional | Compliance configuration | --- @@ -75,16 +75,16 @@ const result = AuditConfig.parse(data); | **eventType** | `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 type | | **severity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | ✅ | Event severity | | **timestamp** | `string` | ✅ | Event timestamp | -| **actor** | `Object` | ✅ | Event actor | -| **target** | `Object` | optional | Event target | +| **actor** | `{ type: Enum<'user' \| 'system' \| 'service' \| 'api_client' \| 'integration'>; id: string; name?: string; email?: string; … }` | ✅ | Event actor | +| **target** | `{ type: string; id: string; name?: string; metadata?: Record }` | optional | Event target | | **description** | `string` | ✅ | Event description | -| **changes** | `Object[]` | optional | List of changes | +| **changes** | `{ field: string; oldValue?: any; newValue?: any }[]` | optional | List of changes | | **result** | `Enum<'success' \| 'failure' \| 'partial'>` | ✅ | Action result | | **errorMessage** | `string` | optional | Error message | | **tenantId** | `string` | optional | Tenant identifier | | **requestId** | `string` | optional | Request ID for tracing | | **metadata** | `Record` | optional | Additional metadata | -| **location** | `Object` | optional | Geographic location | +| **location** | `{ country?: string; region?: string; city?: string }` | optional | Geographic location | --- @@ -128,7 +128,7 @@ const result = AuditConfig.parse(data); | **severities** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>[]` | optional | Severity levels to include | | **actorId** | `string` | optional | Actor identifier | | **tenantId** | `string` | optional | Tenant identifier | -| **timeRange** | `Object` | optional | Time range filter | +| **timeRange** | `{ from: string; to: string }` | optional | Time range filter | | **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Result status | | **searchQuery** | `string` | optional | Search query | | **customFilters** | `Record` | optional | Custom filters | @@ -224,7 +224,7 @@ const result = AuditConfig.parse(data); | :--- | :--- | :--- | :--- | | **retentionDays** | `integer` | ✅ | Retention period in days | | **archiveAfterRetention** | `boolean` | ✅ | Archive logs after retention period | -| **archiveStorage** | `Object` | optional | Archive storage configuration | +| **archiveStorage** | `{ type: Enum<'s3' \| 'gcs' \| 'azure_blob' \| 'filesystem'>; endpoint?: string; bucket?: string; path?: string; … }` | optional | Archive storage configuration | | **customRetention** | `Record` | optional | Custom retention by event type | | **minimumRetentionDays** | `integer` | optional | Minimum retention for compliance | @@ -259,10 +259,10 @@ const result = AuditConfig.parse(data); | **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 | +| **condition** | `{ threshold: integer; windowSeconds: integer; groupBy?: string[]; filters?: Record } \| string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **notifications** | `{ email?: string[]; slack?: string; webhook?: string }` | optional | Notification configuration | --- diff --git a/content/docs/references/system/auth-config.mdx b/content/docs/references/system/auth-config.mdx index 86e69b466c..14c579ffa2 100644 --- a/content/docs/references/system/auth-config.mdx +++ b/content/docs/references/system/auth-config.mdx @@ -35,7 +35,7 @@ Advanced / low-level Better-Auth options | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **crossSubDomainCookies** | `Object` | optional | Share auth cookies across subdomains (critical for *.example.com multi-tenant) | +| **crossSubDomainCookies** | `{ enabled: boolean; additionalCookies?: string[]; domain?: string }` | optional | Share auth cookies across subdomains (critical for *.example.com multi-tenant) | | **useSecureCookies** | `boolean` | optional | Force Secure flag on cookies | | **disableCSRFCheck** | `boolean` | optional | ⚠ Disable CSRF check — security risk, use with caution | | **cookiePrefix** | `string` | optional | Prefix for auth cookie names | @@ -53,17 +53,17 @@ Advanced / low-level Better-Auth options | **baseUrl** | `string` | optional | Base URL for auth routes | | **uiBasePath** | `string` | ✅ | Basename where the auth UI (Console) is mounted (default `/_console`) | | **databaseUrl** | `string` | optional | Database connection string | -| **providers** | `Object[]` | optional | | -| **plugins** | `Object` | optional | | -| **session** | `Object` | optional | | +| **providers** | `{ id: string; clientId: string; clientSecret: string; scope?: string[] }[]` | optional | | +| **plugins** | `{ organization: boolean; twoFactor: boolean; passkeys: boolean; passwordRejectBreached: boolean; … }` | optional | | +| **session** | `{ expiresIn: number; updateAge: number }` | optional | | | **trustedOrigins** | `string[]` | optional | Trusted origins for CSRF protection. Supports wildcards (e.g. "https://*.example.com"). The baseUrl origin is always trusted implicitly. | | **socialProviders** | `Record>` | optional | Social/OAuth provider map forwarded to better-auth socialProviders. Keys are provider ids (google, github, apple, …). | -| **oidcProviders** | `Object[]` | optional | List of OIDC/OAuth2 providers for enterprise SSO. Product or enterprise packages can pass this directly or contribute it through auth:configure. | -| **emailAndPassword** | `Object` | optional | Email and password authentication options forwarded to better-auth | -| **emailVerification** | `Object` | optional | Email verification options forwarded to better-auth | -| **advanced** | `Object` | optional | Advanced / low-level Better-Auth options | +| **oidcProviders** | `{ providerId: string; name?: string; discoveryUrl?: string; issuer?: string; … }[]` | optional | List of OIDC/OAuth2 providers for enterprise SSO. Product or enterprise packages can pass this directly or contribute it through auth:configure. | +| **emailAndPassword** | `{ enabled: boolean; disableSignUp?: boolean; requireEmailVerification?: boolean; minPasswordLength?: number; … }` | optional | Email and password authentication options forwarded to better-auth | +| **emailVerification** | `{ sendOnSignUp?: boolean; sendOnSignIn?: boolean; autoSignInAfterVerification?: boolean; expiresIn?: number }` | optional | Email verification options forwarded to better-auth | +| **advanced** | `{ crossSubDomainCookies?: object; useSecureCookies?: boolean; disableCSRFCheck?: boolean; cookiePrefix?: string }` | optional | Advanced / low-level Better-Auth options | | **ssoOnlyMode** | `boolean` | optional | SSO-only login: hide the local password form + self-registration (the break-glass password endpoint stays enabled) | -| **mutualTls** | `Object` | optional | Mutual TLS (mTLS) configuration | +| **mutualTls** | `{ enabled: boolean; clientCertRequired: boolean; trustedCAs: string[]; crlUrl?: string; … }` | optional | Mutual TLS (mTLS) configuration | --- @@ -152,7 +152,7 @@ Email verification options forwarded to better-auth | **certificateValidation** | `Enum<'strict' \| 'relaxed' \| 'none'>` | ✅ | Certificate validation strictness level | | **allowedCNs** | `string[]` | optional | Allowed Common Names (CN) on client certificates | | **allowedOUs** | `string[]` | optional | Allowed Organizational Units (OU) on client certificates | -| **pinning** | `Object` | optional | Certificate pinning configuration | +| **pinning** | `{ enabled: boolean; pins: string[] }` | optional | Certificate pinning configuration | --- diff --git a/content/docs/references/system/book.mdx b/content/docs/references/system/book.mdx index 0c766631fc..6c46a6c42b 100644 --- a/content/docs/references/system/book.mdx +++ b/content/docs/references/system/book.mdx @@ -60,12 +60,12 @@ const result = Book.parse(data); | **name** | `string` | ✅ | Book name (namespace prefix recommended, like every metadata name) | | **label** | `string` | optional | Display title | | **description** | `string` | optional | | -| **translations** | `Record` | optional | | +| **translations** | `Record` | optional | | | **slug** | `string` | optional | Portal URL segment; defaults to name sans prefix | | **icon** | `string` | optional | | | **order** | `number` | optional | Orders books within the portal | -| **audience** | `string \| string \| Object` | optional | Access audience; defaults to 'org' (inherits package grant) | -| **groups** | `Object[]` | ✅ | The spine: ordered sections. Two levels total. | +| **audience** | `'org' \| 'public' \| { permissionSet: string }` | optional | Access audience; defaults to 'org' (inherits package grant) | +| **groups** | `{ key: string; label: string; translations?: Record; order?: number; … }[]` | ✅ | The spine: ordered sections. Two levels total. | --- @@ -78,13 +78,13 @@ This schema accepts one of the following structures: #### Option 1 -Type: `string` +Type: `'org'` --- #### Option 2 -Type: `string` +Type: `'public'` --- @@ -109,11 +109,11 @@ Type: `string` | :--- | :--- | :--- | :--- | | **key** | `string` | ✅ | Stable group key (used by overrides, deep links, explicit `doc.group`) | | **label** | `string` | ✅ | Section title — first-class, i18n-homed | -| **translations** | `Record` | optional | Per-locale label variants | +| **translations** | `Record` | optional | Per-locale label variants | | **order** | `number` | optional | Order of THIS group within the book | -| **include** | `string \| Object` | optional | Rule that derives membership (glob or tag) | +| **include** | `string \| { tag: string }` | optional | Rule that derives membership (glob or tag) | | **package** | `string` | optional | Scope the rule to a package id (default: the book package; cross-package via ADR-0048) | -| **pages** | `string \| Object[]` | optional | OPTIONAL explicit override — hand-pin a curated order; wins over `include` | +| **pages** | `string \| { doc?: string; href?: string; label?: string; badge?: string; … }[]` | optional | OPTIONAL explicit override — hand-pin a curated order; wins over `include` | --- diff --git a/content/docs/references/system/cache.mdx b/content/docs/references/system/cache.mdx index a12a2813f8..23c19a24f3 100644 --- a/content/docs/references/system/cache.mdx +++ b/content/docs/references/system/cache.mdx @@ -13,7 +13,7 @@ Supports Memory, Redis, Memcached, and CDN. ## Caching in ObjectStack -**Application Cache (`system/cache.zod.ts`) - This File** +**Application Cache (`[system/cache.zod.ts](/docs/references/system/cache)`) - This File** - **Purpose**: Cache computed data, query results, aggregations @@ -25,7 +25,7 @@ Supports Memory, Redis, Memcached, and CDN. - **Scope**: Application layer, server-side data storage -**HTTP Cache (`api/http-cache.zod.ts`)** +**HTTP Cache (`[api/http-cache.zod.ts](/docs/references/api/http-cache)`)** - **Purpose**: Cache API responses at HTTP protocol level @@ -37,7 +37,7 @@ Supports Memory, Redis, Memcached, and CDN. - **Scope**: HTTP layer, client-server communication -@see ../../api/http-cache.zod.ts for HTTP-level caching +See also: ../../[api/http-cache.zod.ts](/docs/references/api/http-cache) for HTTP-level caching **Source:** `packages/spec/src/system/cache.zod.ts` @@ -63,9 +63,9 @@ Cache avalanche/stampede prevention configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **jitterTtl** | `Object` | optional | TTL jitter to prevent simultaneous expiration | -| **circuitBreaker** | `Object` | optional | Circuit breaker for backend protection | -| **lockout** | `Object` | optional | Lock-based stampede prevention | +| **jitterTtl** | `{ enabled: boolean; maxJitterSeconds: number }` | optional | TTL jitter to prevent simultaneous expiration | +| **circuitBreaker** | `{ enabled: boolean; failureThreshold: number; resetTimeout: number }` | optional | Circuit breaker for backend protection | +| **lockout** | `{ enabled: boolean; lockTimeoutMs: number }` | optional | Lock-based stampede prevention | --- @@ -79,8 +79,8 @@ Top-level application cache configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable application-level caching | -| **tiers** | `Object[]` | ✅ | Ordered cache tier hierarchy | -| **invalidation** | `Object[]` | ✅ | Cache invalidation rules | +| **tiers** | `{ name: string; type: Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>; maxSize?: number; ttl: number; … }[]` | ✅ | Ordered cache tier hierarchy | +| **invalidation** | `{ trigger: Enum<'create' \| 'update' \| 'delete' \| 'manual'>; scope: Enum<'key' \| 'pattern' \| 'tag' \| 'all'>; pattern?: string; tags?: string[] }[]` | ✅ | Cache invalidation rules | | **prefetch** | `boolean` | ✅ | Enable cache prefetching | | **compression** | `boolean` | ✅ | Enable data compression in cache | | **encryption** | `boolean` | ✅ | Enable encryption for cached data | @@ -161,7 +161,7 @@ Cache warmup strategy | :--- | :--- | :--- | :--- | | **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 | +| **schedule** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -177,14 +177,14 @@ Distributed cache configuration with consistency and avalanche prevention | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | optional | Enable application-level caching | -| **tiers** | `Object[]` | ✅ | Ordered cache tier hierarchy | -| **invalidation** | `Object[]` | ✅ | Cache invalidation rules | +| **tiers** | `{ name: string; type: Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>; maxSize?: number; ttl?: number; … }[]` | ✅ | Ordered cache tier hierarchy | +| **invalidation** | `{ trigger: Enum<'create' \| 'update' \| 'delete' \| 'manual'>; scope: Enum<'key' \| 'pattern' \| 'tag' \| 'all'>; pattern?: string; tags?: string[] }[]` | ✅ | 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 | +| **avalanchePrevention** | `{ jitterTtl?: object; circuitBreaker?: object; lockout?: object }` | optional | Cache avalanche and stampede prevention | +| **warmup** | `{ enabled?: boolean; strategy?: Enum<'eager' \| 'lazy' \| 'scheduled'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; patterns?: string[]; … }` | optional | Cache warmup strategy | --- diff --git a/content/docs/references/system/change-management.mdx b/content/docs/references/system/change-management.mdx index 34b7e9e0ad..09888f4819 100644 --- a/content/docs/references/system/change-management.mdx +++ b/content/docs/references/system/change-management.mdx @@ -36,7 +36,7 @@ const result = ChangeImpact.parse(data); | **level** | `Enum<'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | Impact level | | **affectedSystems** | `string[]` | ✅ | Affected systems | | **affectedUsers** | `number` | optional | Affected user count | -| **downtime** | `Object` | optional | Downtime information | +| **downtime** | `{ required: boolean; durationMinutes?: number }` | optional | Downtime information | --- @@ -67,13 +67,13 @@ const result = ChangeImpact.parse(data); | **status** | `Enum<'draft' \| 'submitted' \| 'in-review' \| 'approved' \| 'scheduled' \| 'in-progress' \| 'completed' \| 'failed' \| 'rolled-back' \| 'cancelled'>` | ✅ | Change status | | **requestedBy** | `string` | ✅ | Requester user ID | | **requestedAt** | `number` | ✅ | Request timestamp | -| **impact** | `Object` | ✅ | Impact assessment | -| **implementation** | `Object` | ✅ | Implementation plan | -| **rollbackPlan** | `Object` | ✅ | Rollback plan | -| **schedule** | `Object` | optional | Schedule | -| **securityImpact** | `Object` | optional | Security impact assessment per ISO 27001:2022 A.8.32 | -| **approval** | `Object` | optional | Approval workflow | -| **attachments** | `Object[]` | optional | Attachments | +| **impact** | `{ level: Enum<'low' \| 'medium' \| 'high' \| 'critical'>; affectedSystems: string[]; affectedUsers?: number; downtime?: object }` | ✅ | Impact assessment | +| **implementation** | `{ description: string; steps: { order: number; description: string; estimatedMinutes: number }[]; testing?: string }` | ✅ | Implementation plan | +| **rollbackPlan** | `{ description: string; steps: { order: number; description: string; estimatedMinutes: number }[]; testProcedure?: string }` | ✅ | Rollback plan | +| **schedule** | `{ plannedStart: number; plannedEnd: number; actualStart?: number; actualEnd?: number }` | optional | Schedule | +| **securityImpact** | `{ assessed: boolean; riskLevel?: Enum<'none' \| 'low' \| 'medium' \| 'high' \| 'critical'>; affectedDataClassifications?: Enum<'pii' \| 'phi' \| 'pci' \| 'financial' \| 'confidential' \| 'internal' \| 'public'>[]; requiresSecurityApproval: boolean; … }` | optional | Security impact assessment per ISO 27001:2022 A.8.32 | +| **approval** | `{ required: boolean; approvers: { userId: string; approvedAt?: number; comments?: string }[] }` | optional | Approval workflow | +| **attachments** | `{ name: string; url: string }[]` | optional | Attachments | | **metadata** | `Record` | optional | Custom metadata key-value pairs for extensibility | @@ -116,7 +116,7 @@ const result = ChangeImpact.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **description** | `string` | ✅ | Rollback description | -| **steps** | `Object[]` | ✅ | Rollback steps | +| **steps** | `{ order: number; description: string; estimatedMinutes: number }[]` | ✅ | Rollback steps | | **testProcedure** | `string` | optional | Test procedure | diff --git a/content/docs/references/system/collaboration.mdx b/content/docs/references/system/collaboration.mdx index 2b0c946b21..0029d8b17a 100644 --- a/content/docs/references/system/collaboration.mdx +++ b/content/docs/references/system/collaboration.mdx @@ -55,7 +55,7 @@ const result = AwarenessEvent.parse(data); | :--- | :--- | :--- | :--- | | **sessionId** | `string` | ✅ | Session identifier | | **documentId** | `string` | optional | Document ID this session is for | -| **users** | `Object[]` | ✅ | Active users in session | +| **users** | `{ userId: string; sessionId: string; userName: string; userAvatar?: string; … }[]` | ✅ | Active users in session | | **startedAt** | `string` | ✅ | ISO 8601 datetime when session started | | **lastUpdate** | `string` | ✅ | ISO 8601 datetime of last update | | **metadata** | `Record` | optional | Session metadata | @@ -104,8 +104,8 @@ const result = AwarenessEvent.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **state** | `Object \| Object \| Object \| Object \| Object` | ✅ | Merged CRDT state | -| **conflicts** | `Object[]` | optional | Conflicts encountered during merge | +| **state** | `{ type: 'lww-register'; value: any; timestamp: string; replicaId: string; … } \| { type: 'g-counter'; counts: Record } \| { type: 'pn-counter'; positive: Record; negative: Record } \| { type: 'or-set'; elements: { value: any; timestamp: string; replicaId: string; uid: string; … }[] } \| { type: 'text'; documentId: string; content: string; operations: { operationId: string; replicaId: string; position: integer; insert?: string; … }[]; … }` | ✅ | Merged CRDT state | +| **conflicts** | `{ type: string; description: string; resolved: boolean }[]` | optional | Conflicts encountered during merge | --- @@ -124,11 +124,11 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'lww-register'` | ✅ | | | **value** | `any` | ✅ | Current register value | | **timestamp** | `string` | ✅ | ISO 8601 datetime of last write | | **replicaId** | `string` | ✅ | ID of replica that performed last write | -| **vectorClock** | `Object` | optional | Optional vector clock for causality tracking | +| **vectorClock** | `{ clock: Record }` | optional | Optional vector clock for causality tracking | --- @@ -140,7 +140,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'g-counter'` | ✅ | | | **counts** | `Record` | ✅ | Map of replica ID to count | --- @@ -153,7 +153,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'pn-counter'` | ✅ | | | **positive** | `Record` | ✅ | Positive increments per replica | | **negative** | `Record` | ✅ | Negative increments per replica | @@ -167,8 +167,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **elements** | `Object[]` | ✅ | Set elements with metadata | +| **type** | `'or-set'` | ✅ | | +| **elements** | `{ value: any; timestamp: string; replicaId: string; uid: string; … }[]` | ✅ | Set elements with metadata | --- @@ -180,12 +180,12 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'text'` | ✅ | | | **documentId** | `string` | ✅ | Document identifier | | **content** | `string` | ✅ | Current text content | -| **operations** | `Object[]` | ✅ | History of operations | +| **operations** | `{ operationId: string; replicaId: string; position: integer; insert?: string; … }[]` | ✅ | History of operations | | **lamportClock** | `integer` | ✅ | Current Lamport clock value | -| **vectorClock** | `Object` | ✅ | Vector clock for causality | +| **vectorClock** | `{ clock: Record }` | ✅ | Vector clock for causality | --- @@ -229,11 +229,11 @@ This schema accepts one of the following structures: | :--- | :--- | :--- | :--- | | **sessionId** | `string` | ✅ | Session identifier | | **documentId** | `string` | ✅ | Document identifier | -| **config** | `Object` | ✅ | Session configuration | -| **users** | `Object[]` | ✅ | Active users | -| **cursors** | `Object[]` | ✅ | Active cursors | +| **config** | `{ mode: Enum<'ot' \| 'crdt' \| 'lock' \| 'hybrid'>; enableCursorSharing: boolean; enablePresence: boolean; enableAwareness: boolean; … }` | ✅ | Session configuration | +| **users** | `{ userId: string; sessionId: string; userName: string; userAvatar?: string; … }[]` | ✅ | Active users | +| **cursors** | `{ userId: string; sessionId: string; documentId: string; userName: string; … }[]` | ✅ | Active cursors | | **version** | `integer` | ✅ | Current document version | -| **operations** | `Object \| Object[]` | optional | Recent operations | +| **operations** | `{ operationId: string; documentId: string; userId: string; sessionId: string; … } \| { operationId: string; replicaId: string; position: integer; insert?: string; … }[]` | optional | Recent operations | | **createdAt** | `string` | ✅ | ISO 8601 datetime when session was created | | **lastActivity** | `string` | ✅ | ISO 8601 datetime of last activity | | **status** | `Enum<'active' \| 'idle' \| 'ended'>` | ✅ | Session status | @@ -255,7 +255,7 @@ This schema accepts one of the following structures: | **idleTimeout** | `integer` | ✅ | Idle timeout in milliseconds | | **conflictResolution** | `Enum<'ot' \| 'crdt' \| 'manual'>` | ✅ | Conflict resolution strategy | | **persistence** | `boolean` | ✅ | Enable operation persistence | -| **snapshot** | `Object` | optional | Snapshot configuration | +| **snapshot** | `{ enabled: boolean; interval: integer }` | optional | Snapshot configuration | --- @@ -270,9 +270,9 @@ This schema accepts one of the following structures: | **sessionId** | `string` | ✅ | Session identifier | | **documentId** | `string` | ✅ | Document identifier | | **userName** | `string` | ✅ | Display name of user | -| **position** | `Object` | ✅ | Current cursor position | -| **selection** | `Object` | optional | Current text selection | -| **style** | `Object` | ✅ | Visual style for this cursor | +| **position** | `{ line: integer; column: integer }` | ✅ | Current cursor position | +| **selection** | `{ anchor: object; focus: object; direction?: Enum<'forward' \| 'backward'> }` | optional | Current text selection | +| **style** | `{ color: Enum<'blue' \| 'green' \| 'red' \| 'yellow' \| 'purple' \| 'orange' \| 'pink' \| 'teal' \| 'indigo' \| 'cyan'> \| string; opacity: number; label?: string; showLabel: boolean; … }` | ✅ | Visual style for this cursor | | **isTyping** | `boolean` | ✅ | Whether user is currently typing | | **lastUpdate** | `string` | ✅ | ISO 8601 datetime of last cursor update | | **metadata** | `Record` | optional | Additional cursor metadata | @@ -317,8 +317,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **anchor** | `Object` | ✅ | Selection anchor (start point) | -| **focus** | `Object` | ✅ | Selection focus (end point) | +| **anchor** | `{ line: integer; column: integer }` | ✅ | Selection anchor (start point) | +| **focus** | `{ line: integer; column: integer }` | ✅ | Selection focus (end point) | | **direction** | `Enum<'forward' \| 'backward'>` | optional | Selection direction | @@ -345,8 +345,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **position** | `Object` | optional | Updated cursor position | -| **selection** | `Object` | optional | Updated selection | +| **position** | `{ line: integer; column: integer }` | optional | Updated cursor position | +| **selection** | `{ anchor: object; focus: object; direction?: Enum<'forward' \| 'backward'> }` | optional | Updated selection | | **isTyping** | `boolean` | optional | Updated typing state | | **metadata** | `Record` | optional | Updated metadata | @@ -359,7 +359,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'g-counter'` | ✅ | | | **counts** | `Record` | ✅ | Map of replica ID to count | @@ -371,11 +371,11 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'lww-register'` | ✅ | | | **value** | `any` | ✅ | Current register value | | **timestamp** | `string` | ✅ | ISO 8601 datetime of last write | | **replicaId** | `string` | ✅ | ID of replica that performed last write | -| **vectorClock** | `Object` | optional | Optional vector clock for causality tracking | +| **vectorClock** | `{ clock: Record }` | optional | Optional vector clock for causality tracking | --- @@ -386,8 +386,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **elements** | `Object[]` | ✅ | Set elements with metadata | +| **type** | `'or-set'` | ✅ | | +| **elements** | `{ value: any; timestamp: string; replicaId: string; uid: string; … }[]` | ✅ | Set elements with metadata | --- @@ -421,7 +421,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'insert'` | ✅ | | | **text** | `string` | ✅ | Text to insert | | **attributes** | `Record` | optional | Text formatting attributes (e.g., bold, italic) | @@ -435,7 +435,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'delete'` | ✅ | | | **count** | `integer` | ✅ | Number of characters to delete | --- @@ -448,7 +448,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'retain'` | ✅ | | | **count** | `integer` | ✅ | Number of characters to retain | | **attributes** | `Record` | optional | Attribute changes to apply | @@ -467,7 +467,7 @@ This schema accepts one of the following structures: | **documentId** | `string` | ✅ | Document identifier | | **userId** | `string` | ✅ | User who created the operation | | **sessionId** | `string` | ✅ | Session identifier | -| **components** | `Object \| Object \| Object[]` | ✅ | Operation components | +| **components** | `{ type: 'insert'; text: string; attributes?: Record } \| { type: 'delete'; count: integer } \| { type: 'retain'; count: integer; attributes?: Record }[]` | ✅ | Operation components | | **baseVersion** | `integer` | ✅ | Document version this operation is based on | | **timestamp** | `string` | ✅ | ISO 8601 datetime when operation was created | | **metadata** | `Record` | optional | Additional operation metadata | @@ -492,7 +492,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **operation** | `Object` | ✅ | Transformed operation | +| **operation** | `{ operationId: string; documentId: string; userId: string; sessionId: string; … }` | ✅ | Transformed operation | | **transformed** | `boolean` | ✅ | Whether transformation was applied | | **conflicts** | `string[]` | optional | Conflict descriptions if any | @@ -505,7 +505,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'pn-counter'` | ✅ | | | **positive** | `Record` | ✅ | Positive increments per replica | | **negative** | `Record` | ✅ | Negative increments per replica | @@ -535,12 +535,12 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'text'` | ✅ | | | **documentId** | `string` | ✅ | Document identifier | | **content** | `string` | ✅ | Current text content | -| **operations** | `Object[]` | ✅ | History of operations | +| **operations** | `{ operationId: string; replicaId: string; position: integer; insert?: string; … }[]` | ✅ | History of operations | | **lamportClock** | `integer` | ✅ | Current Lamport clock value | -| **vectorClock** | `Object` | ✅ | Vector clock for causality | +| **vectorClock** | `{ clock: Record }` | ✅ | Vector clock for causality | --- diff --git a/content/docs/references/system/deploy-bundle.mdx b/content/docs/references/system/deploy-bundle.mdx index 9b3e142221..6dd3c6ec5c 100644 --- a/content/docs/references/system/deploy-bundle.mdx +++ b/content/docs/references/system/deploy-bundle.mdx @@ -63,7 +63,7 @@ Deploy bundle containing all metadata for deployment | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | Deployment manifest | +| **manifest** | `{ version: string; checksum?: string; objects: string[]; views: string[]; … }` | ✅ | Deployment manifest | | **objects** | `Record[]` | ✅ | Object definitions | | **views** | `Record[]` | ✅ | View definitions | | **flows** | `Record[]` | ✅ | Flow definitions | @@ -81,8 +81,8 @@ Schema diff between current and desired state | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **changes** | `Object[]` | ✅ | List of schema changes | -| **summary** | `Object` | ✅ | Change summary counts | +| **changes** | `{ entityType: Enum<'object' \| 'field' \| 'index' \| 'view' \| 'flow' \| 'permission'>; entityName: string; parentEntity?: string; changeType: Enum<'added' \| 'modified' \| 'removed'>; … }[]` | ✅ | List of schema changes | +| **summary** | `{ added: integer; modified: integer; removed: integer }` | ✅ | Change summary counts | | **hasBreakingChanges** | `boolean` | ✅ | Whether diff contains breaking changes | @@ -149,7 +149,7 @@ Bundle validation result | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **valid** | `boolean` | ✅ | Whether the bundle is valid | -| **issues** | `Object[]` | ✅ | Validation issues | +| **issues** | `{ severity: Enum<'error' \| 'warning' \| 'info'>; path: string; message: string; code?: string }[]` | ✅ | Validation issues | | **errorCount** | `integer` | ✅ | Number of errors | | **warningCount** | `integer` | ✅ | Number of warnings | @@ -164,7 +164,7 @@ Ordered migration plan | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **statements** | `Object[]` | ✅ | Ordered DDL statements | +| **statements** | `{ sql: string; reversible: boolean; rollbackSql?: string; order: integer }[]` | ✅ | Ordered DDL statements | | **dialect** | `string` | ✅ | Target SQL dialect | | **reversible** | `boolean` | ✅ | Whether the plan can be fully rolled back | | **estimatedDurationMs** | `integer` | optional | Estimated execution time | diff --git a/content/docs/references/system/disaster-recovery.mdx b/content/docs/references/system/disaster-recovery.mdx index e95012df9d..3aed2c2981 100644 --- a/content/docs/references/system/disaster-recovery.mdx +++ b/content/docs/references/system/disaster-recovery.mdx @@ -58,11 +58,11 @@ Backup configuration | 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 | +| **schedule** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Cron expression for backup schedule — cron`0 2 * * *` | +| **retention** | `{ days: number; minCopies?: number; maxCopies?: number }` | ✅ | Backup retention policy | +| **destination** | `{ type: Enum<'s3' \| 'gcs' \| 'azure_blob' \| 'local'>; bucket?: string; path?: string; region?: string }` | ✅ | Backup storage destination | +| **encryption** | `{ enabled?: boolean; algorithm?: Enum<'AES-256-GCM' \| 'AES-256-CBC' \| 'ChaCha20-Poly1305'>; keyId?: string }` | optional | Backup encryption settings | +| **compression** | `{ enabled?: boolean; algorithm?: Enum<'gzip' \| 'zstd' \| 'lz4' \| 'snappy'> }` | optional | Backup compression settings | | **verifyAfterBackup** | `boolean` | optional | Verify backup integrity after creation | @@ -105,14 +105,14 @@ Complete disaster recovery plan configuration | 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 | +| **rpo** | `{ value: number; unit?: Enum<'seconds' \| 'minutes' \| 'hours'> }` | ✅ | Recovery Point Objective | +| **rto** | `{ value: number; unit?: Enum<'seconds' \| 'minutes' \| 'hours'> }` | ✅ | Recovery Time Objective | +| **backup** | `{ strategy?: Enum<'full' \| 'incremental' \| 'differential'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; retention: object; destination: object; … }` | ✅ | Backup configuration | +| **failover** | `{ mode?: Enum<'active_passive' \| 'active_active' \| 'pilot_light' \| 'warm_standby'>; autoFailover?: boolean; healthCheckInterval?: number; failureThreshold?: number; … }` | optional | Multi-region failover configuration | +| **replication** | `{ mode?: Enum<'synchronous' \| 'asynchronous' \| 'semi_synchronous'>; maxLagSeconds?: number; includeObjects?: string[]; excludeObjects?: string[] }` | optional | Data replication settings | +| **testing** | `{ enabled?: boolean; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; notificationChannel?: string }` | optional | Automated disaster recovery testing | | **runbookUrl** | `string` | optional | URL to disaster recovery runbook/playbook | -| **contacts** | `Object[]` | optional | Emergency contact list for DR incidents | +| **contacts** | `{ name: string; role: string; email?: string; phone?: string }[]` | optional | Emergency contact list for DR incidents | --- @@ -129,8 +129,8 @@ Failover configuration | **autoFailover** | `boolean` | ✅ | Enable automatic failover | | **healthCheckInterval** | `number` | ✅ | Health check interval in seconds | | **failureThreshold** | `number` | ✅ | Consecutive failures before failover | -| **regions** | `Object[]` | ✅ | Multi-region configuration (minimum 2 regions) | -| **dns** | `Object` | optional | DNS failover settings | +| **regions** | `{ name: string; role: Enum<'primary' \| 'secondary' \| 'witness'>; endpoint?: string; priority?: number }[]` | ✅ | Multi-region configuration (minimum 2 regions) | +| **dns** | `{ ttl: number; provider?: Enum<'route53' \| 'cloudflare' \| 'azure_dns' \| 'custom'> }` | optional | DNS failover settings | --- diff --git a/content/docs/references/system/doc.mdx b/content/docs/references/system/doc.mdx index 4cb22838e2..d7800d34dc 100644 --- a/content/docs/references/system/doc.mdx +++ b/content/docs/references/system/doc.mdx @@ -67,7 +67,7 @@ const result = Doc.parse(data); | **content** | `string` | ✅ | Raw Markdown content (CommonMark + GFM) | | **order** | `number` | optional | Sort key within a book group (ADR-0046 §6) | | **group** | `string` | optional | Explicit book-group key (ADR-0046 §6); rules usually suffice | -| **translations** | `Record` | optional | Per-locale `{label?,description?,content}` variants; the base doc is the fallback | +| **translations** | `Record` | optional | Per-locale `{label?,description?,content}` variants; the base doc is the fallback | --- diff --git a/content/docs/references/system/email-config.mdx b/content/docs/references/system/email-config.mdx index d7954735f5..4753c28db9 100644 --- a/content/docs/references/system/email-config.mdx +++ b/content/docs/references/system/email-config.mdx @@ -70,7 +70,7 @@ const result = EmailAddressConfig.parse(data); | :--- | :--- | :--- | :--- | | **provider** | `Enum<'log' \| 'resend' \| 'postmark'>` | ✅ | | | **apiKey** | `string` | optional | Provider API key (or OS_EMAIL_API_KEY env) | -| **defaultFrom** | `Object` | optional | | +| **defaultFrom** | `{ name?: string; address: string }` | optional | | | **retries** | `integer` | optional | Retry attempts on transport throw | | **persist** | `boolean` | optional | Persist to sys_email (default true) | | **options** | `Record` | optional | | diff --git a/content/docs/references/system/email-template.mdx b/content/docs/references/system/email-template.mdx index 8dbb5241c9..f8e73b7eb3 100644 --- a/content/docs/references/system/email-template.mdx +++ b/content/docs/references/system/email-template.mdx @@ -56,13 +56,13 @@ const result = EmailTemplateDefinition.parse(data); | **subject** | `string` | ✅ | Subject template | | **bodyHtml** | `string` | ✅ | HTML body template | | **bodyText** | `string` | optional | Plain-text body template (auto-derived from HTML when omitted) | -| **variables** | `Object[]` | ✅ | | -| **fromOverride** | `Object` | optional | | +| **variables** | `{ name: string; type: Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'url' \| 'user' \| 'record'>; required: boolean; description?: string }[]` | ✅ | | +| **fromOverride** | `{ name?: string; address: string }` | optional | | | **replyTo** | `string` | optional | | | **active** | `boolean` | ✅ | | | **isSystem** | `boolean` | ✅ | | | **description** | `string` | optional | | -| **protection** | `Object` | optional | Package author protection block — lock policy for this email template. | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | diff --git a/content/docs/references/system/encryption.mdx b/content/docs/references/system/encryption.mdx index 093ce24325..8a690ad213 100644 --- a/content/docs/references/system/encryption.mdx +++ b/content/docs/references/system/encryption.mdx @@ -48,7 +48,7 @@ Field-level encryption configuration | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable field-level encryption | | **algorithm** | `Enum<'aes-256-gcm' \| 'aes-256-cbc' \| 'chacha20-poly1305'>` | ✅ | Encryption algorithm | -| **keyManagement** | `Object` | ✅ | Key management configuration | +| **keyManagement** | `{ provider: Enum<'local' \| 'aws-kms' \| 'azure-key-vault' \| 'gcp-kms' \| 'hashicorp-vault'>; keyId?: string; rotationPolicy?: object }` | ✅ | Key management configuration | | **scope** | `Enum<'field' \| 'record' \| 'table' \| 'database'>` | ✅ | Encryption scope level | | **deterministicEncryption** | `boolean` | ✅ | Allows equality queries on encrypted data | | **searchableEncryption** | `boolean` | ✅ | Allows search on encrypted data | @@ -65,7 +65,7 @@ Per-field encryption assignment | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **fieldName** | `string` | ✅ | Name of the field to encrypt | -| **encryptionConfig** | `Object` | ✅ | Encryption settings for this field | +| **encryptionConfig** | `{ enabled: boolean; algorithm: Enum<'aes-256-gcm' \| 'aes-256-cbc' \| 'chacha20-poly1305'>; keyManagement: object; scope: Enum<'field' \| 'record' \| 'table' \| 'database'>; … }` | ✅ | Encryption settings for this field | | **indexable** | `boolean` | ✅ | Allow indexing on encrypted field | diff --git a/content/docs/references/system/environment-artifact.mdx b/content/docs/references/system/environment-artifact.mdx index c36430ad8c..b9a6227920 100644 --- a/content/docs/references/system/environment-artifact.mdx +++ b/content/docs/references/system/environment-artifact.mdx @@ -27,9 +27,9 @@ and `checksum`. credentials, environment identity, secrets. Injected at runtime. -See [content/docs/concepts/north-star.mdx](content/docs/concepts/north-star.mdx) §6.3 for the runtime-inputs +See `content/docs/concepts/north-star.mdx` §6.3 for the runtime-inputs -boundary, and [ROADMAP.md](ROADMAP.md) M1 for the milestone definition. +boundary, and `ROADMAP.md` M1 for the milestone definition. ## Storage / Distribution @@ -65,16 +65,16 @@ ObjectStack Environment Artifact envelope (v0) | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **schemaVersion** | `string` | ✅ | Environment artifact envelope schema version | +| **schemaVersion** | `'0.1'` | ✅ | Environment artifact envelope schema version | | **environmentId** | `string` | ✅ | Environment identifier (control-plane scoped) | | **commitId** | `string` | ✅ | Content-addressable revision id | -| **checksum** | `Object` | ✅ | Artifact integrity checksum | +| **checksum** | `{ algorithm: Enum<'sha256' \| 'sha384' \| 'sha512'>; value: string }` | ✅ | Artifact integrity checksum | | **builtAt** | `string` | optional | ISO-8601 timestamp of when the artifact was built | | **builtWith** | `string` | optional | Build tool identifier | | **metadata** | `Record` | ✅ | Compiled environment metadata grouped by category | -| **functions** | `Object[]` | ✅ | Inlined function code packaged with the artifact | -| **manifest** | `Object` | ✅ | Plugin/driver requirements baked into the artifact | -| **payloadRef** | `Object` | optional | Out-of-band payload reference (reserved for future use) | +| **functions** | `{ name: string; language: Enum<'javascript' \| 'typescript'>; code: string; source?: object; … }[]` | ✅ | Inlined function code packaged with the artifact | +| **manifest** | `{ plugins?: { id: string; version?: string }[]; drivers?: { id: string; version?: string }[]; engine?: object }` | ✅ | Plugin/driver requirements baked into the artifact | +| **payloadRef** | `{ url: string; expiresAt?: string; checksum: object }` | optional | Out-of-band payload reference (reserved for future use) | --- @@ -104,7 +104,7 @@ A single inlined function | **name** | `string` | ✅ | Function machine name (snake_case) | | **language** | `Enum<'javascript' \| 'typescript'>` | ✅ | Source language of the function code | | **code** | `string` | ✅ | Inlined function source | -| **source** | `Object` | optional | Source-map metadata for the function | +| **source** | `{ path?: string; exportName?: string }` | optional | Source-map metadata for the function | | **hash** | `string` | optional | Hex SHA-256 of the inlined code | @@ -143,9 +143,9 @@ Plugin/driver requirements baked into the artifact | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **plugins** | `Object[]` | optional | | -| **drivers** | `Object[]` | optional | | -| **engine** | `Object` | optional | | +| **plugins** | `{ id: string; version?: string }[]` | optional | | +| **drivers** | `{ id: string; version?: string }[]` | optional | | +| **engine** | `{ objectstack: string }` | optional | | --- @@ -193,7 +193,7 @@ Out-of-band payload reference (reserved for future use) | :--- | :--- | :--- | :--- | | **url** | `string` | ✅ | Signed URL pointing at the artifact payload | | **expiresAt** | `string` | optional | ISO-8601 expiry timestamp | -| **checksum** | `Object` | ✅ | Checksum of the referenced payload | +| **checksum** | `{ algorithm: Enum<'sha256' \| 'sha384' \| 'sha512'>; value: string }` | ✅ | Checksum of the referenced payload | --- diff --git a/content/docs/references/system/http-server.mdx b/content/docs/references/system/http-server.mdx index 60e98c9fd9..85bbcf67ba 100644 --- a/content/docs/references/system/http-server.mdx +++ b/content/docs/references/system/http-server.mdx @@ -43,12 +43,12 @@ const result = HttpServerConfig.parse(data); | :--- | :--- | :--- | :--- | | **port** | `integer` | ✅ | Port number to listen on | | **host** | `string` | ✅ | Host address to bind to | -| **cors** | `Object` | optional | CORS configuration | +| **cors** | `{ enabled: boolean; origins: string \| string[]; methods?: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>[]; credentials: boolean; … }` | optional | CORS configuration | | **requestTimeout** | `integer` | ✅ | Request timeout in milliseconds | | **bodyLimit** | `string` | ✅ | Maximum request body size | | **compression** | `boolean` | ✅ | Enable response compression | -| **security** | `Object` | optional | Security configuration | -| **static** | `Object[]` | optional | Static file serving configuration | +| **security** | `{ helmet: boolean; rateLimit?: object }` | optional | Security configuration | +| **static** | `{ path: string; directory: string; cacheControl?: string }[]` | optional | Static file serving configuration | | **trustProxy** | `boolean` | ✅ | Trust X-Forwarded-* headers | @@ -65,7 +65,7 @@ const result = HttpServerConfig.parse(data); | **enabled** | `boolean` | ✅ | Whether middleware is enabled | | **order** | `integer` | ✅ | Execution order priority | | **config** | `Record` | optional | Middleware configuration object | -| **paths** | `Object` | optional | Path filtering | +| **paths** | `{ include?: string[]; exclude?: string[] }` | optional | Path filtering | --- @@ -94,8 +94,8 @@ const result = HttpServerConfig.parse(data); | **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method | | **path** | `string` | ✅ | URL path pattern | | **handler** | `string` | ✅ | Handler identifier or name | -| **metadata** | `Object` | optional | | -| **security** | `Object` | optional | | +| **metadata** | `{ summary?: string; description?: string; tags?: string[]; operationId?: string }` | optional | | +| **security** | `{ authRequired: boolean; permissions?: string[]; rateLimit?: string }` | optional | | --- @@ -154,9 +154,9 @@ const result = HttpServerConfig.parse(data); | :--- | :--- | :--- | :--- | | **state** | `Enum<'stopped' \| 'starting' \| 'running' \| 'stopping' \| 'error'>` | ✅ | Current server state | | **uptime** | `integer` | optional | Server uptime in milliseconds | -| **server** | `Object` | optional | | -| **connections** | `Object` | optional | | -| **requests** | `Object` | optional | | +| **server** | `{ port: integer; host: string; url?: string }` | optional | | +| **connections** | `{ active: integer; total: integer }` | optional | | +| **requests** | `{ total: integer; success: integer; errors: integer }` | optional | | --- diff --git a/content/docs/references/system/incident-response.mdx b/content/docs/references/system/incident-response.mdx index 2fb53ac205..9fdd2a973b 100644 --- a/content/docs/references/system/incident-response.mdx +++ b/content/docs/references/system/incident-response.mdx @@ -13,7 +13,7 @@ incident classification, severity grading, response procedures, and notification matrices. -@see https://www.iso.org/standard/27001 +See also: https://www.iso.org/standard/27001 @category Security @@ -53,7 +53,7 @@ Security incident record per ISO 27001:2022 A.5.24–A.5.28 | **resolvedAt** | `number` | optional | Resolution timestamp | | **affectedSystems** | `string[]` | ✅ | Affected systems | | **affectedDataClassifications** | `Enum<'pii' \| 'phi' \| 'pci' \| 'financial' \| 'confidential' \| 'internal' \| 'public'>[]` | optional | Affected data classifications | -| **responsePhases** | `Object[]` | optional | Incident response phases | +| **responsePhases** | `{ phase: Enum<'identification' \| 'containment' \| 'eradication' \| 'recovery' \| 'lessons_learned'>; description: string; assignedTo: string; targetHours: number; … }[]` | optional | Incident response phases | | **rootCause** | `string` | optional | Root cause analysis | | **correctiveActions** | `string[]` | optional | Corrective actions taken or planned | | **lessonsLearned** | `string` | optional | Lessons learned from the incident | @@ -90,7 +90,7 @@ Incident notification matrix with escalation policies | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **rules** | `Object[]` | ✅ | Notification rules by severity level | +| **rules** | `{ severity: Enum<'critical' \| 'high' \| 'medium' \| 'low'>; channels: Enum<'email' \| 'sms' \| 'slack' \| 'pagerduty' \| 'webhook'>[]; recipients: string[]; withinMinutes: number; … }[]` | ✅ | Notification rules by severity level | | **escalationTimeoutMinutes** | `number` | ✅ | Auto-escalation timeout in minutes | | **escalationChain** | `string[]` | ✅ | Ordered escalation chain of roles | @@ -142,7 +142,7 @@ Organization-level incident response policy per ISO 27001:2022 | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable incident response management | -| **notificationMatrix** | `Object` | ✅ | Notification and escalation matrix | +| **notificationMatrix** | `{ rules: { severity: Enum<'critical' \| 'high' \| 'medium' \| 'low'>; channels: Enum<'email' \| 'sms' \| 'slack' \| 'pagerduty' \| 'webhook'>[]; recipients: string[]; withinMinutes: number; … }[]; escalationTimeoutMinutes: number; escalationChain: string[] }` | ✅ | Notification and escalation matrix | | **defaultResponseTeam** | `string` | ✅ | Default incident response team or role | | **triageDeadlineHours** | `number` | ✅ | Maximum hours to begin triage after detection | | **requirePostIncidentReview** | `boolean` | ✅ | Require post-incident review for all incidents | diff --git a/content/docs/references/system/job.mdx b/content/docs/references/system/job.mdx index 25eb272dc2..9b04b25d11 100644 --- a/content/docs/references/system/job.mdx +++ b/content/docs/references/system/job.mdx @@ -31,8 +31,8 @@ const result = CronSchedule.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string \| Object` | ✅ | Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope. | +| **type** | `'cron'` | ✅ | | +| **expression** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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") | @@ -44,7 +44,7 @@ const result = CronSchedule.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'interval'` | ✅ | | | **intervalMs** | `integer` | ✅ | Interval in milliseconds | @@ -60,9 +60,9 @@ const result = CronSchedule.parse(data); | **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 | +| **schedule** | `{ type: 'cron'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; timezone?: string } \| { type: 'interval'; intervalMs: integer } \| { type: 'once'; at: string }` | ✅ | Job schedule configuration | | **handler** | `string` | ✅ | Handler function name (must match a key in `defineStack({ functions })`) | -| **retryPolicy** | `Object` | optional | Retry policy configuration | +| **retryPolicy** | `{ maxRetries?: integer; backoffMs?: integer; backoffMultiplier?: number }` | optional | Retry policy configuration | | **timeout** | `integer` | optional | Timeout in milliseconds | | **enabled** | `boolean` | optional | Whether the job is enabled | @@ -103,7 +103,7 @@ const result = CronSchedule.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'once'` | ✅ | | | **at** | `string` | ✅ | ISO 8601 datetime when to execute | @@ -136,8 +136,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string \| Object` | ✅ | Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope. | +| **type** | `'cron'` | ✅ | | +| **expression** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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") | --- @@ -150,7 +150,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'interval'` | ✅ | | | **intervalMs** | `integer` | ✅ | Interval in milliseconds | --- @@ -163,7 +163,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'once'` | ✅ | | | **at** | `string` | ✅ | ISO 8601 datetime when to execute | --- diff --git a/content/docs/references/system/logging.mdx b/content/docs/references/system/logging.mdx index 3e03bb6ac0..7b77b6ef59 100644 --- a/content/docs/references/system/logging.mdx +++ b/content/docs/references/system/logging.mdx @@ -78,7 +78,7 @@ External service destination configuration | :--- | :--- | :--- | :--- | | **endpoint** | `string` | optional | | | **region** | `string` | optional | | -| **credentials** | `Object` | optional | | +| **credentials** | `{ accessKeyId?: string; secretAccessKey?: string; apiKey?: string; environmentId?: string }` | optional | | | **logGroup** | `string` | optional | | | **logStream** | `string` | optional | | | **index** | `string` | optional | | @@ -96,7 +96,7 @@ File destination configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **path** | `string` | ✅ | Log file path | -| **rotation** | `Object` | optional | | +| **rotation** | `{ maxSize: string; maxFiles: integer; compress: boolean; interval?: Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly'> }` | optional | | | **encoding** | `string` | ✅ | | | **append** | `boolean` | ✅ | | @@ -114,9 +114,9 @@ HTTP destination configuration | **url** | `string` | ✅ | HTTP endpoint URL | | **method** | `Enum<'POST' \| 'PUT'>` | ✅ | | | **headers** | `Record` | optional | | -| **auth** | `Object` | optional | | -| **batch** | `Object` | optional | | -| **retry** | `Object` | optional | | +| **auth** | `{ type: Enum<'basic' \| 'bearer' \| 'api_key'>; username?: string; password?: string; token?: string; … }` | optional | | +| **batch** | `{ maxSize: integer; flushInterval: integer }` | optional | | +| **retry** | `{ maxAttempts: integer; initialDelay: integer; backoffMultiplier: number }` | optional | | | **timeout** | `integer` | ✅ | | @@ -134,10 +134,10 @@ Log destination configuration | **type** | `Enum<'console' \| 'file' \| 'syslog' \| 'elasticsearch' \| 'cloudwatch' \| 'stackdriver' \| 'azure_monitor' \| 'datadog' \| 'splunk' \| 'loki' \| 'http' \| 'kafka' \| 'redis' \| 'custom'>` | ✅ | Destination type | | **level** | `Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | ✅ | Extended log severity level | | **enabled** | `boolean` | ✅ | | -| **console** | `Object` | optional | Console destination configuration | -| **file** | `Object` | optional | File destination configuration | -| **http** | `Object` | optional | HTTP destination configuration | -| **externalService** | `Object` | optional | External service destination configuration | +| **console** | `{ stream: Enum<'stdout' \| 'stderr'>; colors: boolean; prettyPrint: boolean }` | optional | Console destination configuration | +| **file** | `{ path: string; rotation?: object; encoding: string; append: boolean }` | optional | File destination configuration | +| **http** | `{ url: string; method: Enum<'POST' \| 'PUT'>; headers?: Record; auth?: object; … }` | optional | HTTP destination configuration | +| **externalService** | `{ endpoint?: string; region?: string; credentials?: object; logGroup?: string; … }` | optional | External service destination configuration | | **format** | `Enum<'json' \| 'text' \| 'pretty'>` | ✅ | | | **filterId** | `string` | optional | Filter function identifier | @@ -181,7 +181,7 @@ Log enrichment configuration | **addHostname** | `boolean` | ✅ | | | **addProcessId** | `boolean` | ✅ | | | **addEnvironment** | `boolean` | ✅ | | -| **addTimestampFormats** | `Object` | optional | | +| **addTimestampFormats** | `{ unix: boolean; iso: boolean }` | optional | | | **addCaller** | `boolean` | ✅ | | | **addCorrelationIds** | `boolean` | ✅ | | @@ -248,7 +248,7 @@ Log severity level | **redact** | `string[]` | ✅ | Keys to redact from log context | | **sourceLocation** | `boolean` | ✅ | Include file and line number | | **file** | `string` | optional | Path to log file | -| **rotation** | `Object` | optional | | +| **rotation** | `{ maxSize: string; maxFiles: number }` | optional | | --- @@ -265,14 +265,14 @@ Logging configuration | **label** | `string` | ✅ | Display label | | **enabled** | `boolean` | ✅ | | | **level** | `Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | ✅ | Extended log severity level | -| **default** | `Object` | optional | Default logger configuration | -| **loggers** | `Record` | optional | Named logger configurations | -| **destinations** | `Object[]` | ✅ | Log destinations | -| **enrichment** | `Object` | optional | Log enrichment configuration | +| **default** | `{ name?: string; level: Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>; format: Enum<'json' \| 'text' \| 'pretty'>; redact: string[]; … }` | optional | Default logger configuration | +| **loggers** | `Record; format: Enum<'json' \| 'text' \| 'pretty'>; redact: string[]; … }>` | optional | Named logger configurations | +| **destinations** | `{ name: string; type: Enum<'console' \| 'file' \| 'syslog' \| 'elasticsearch' \| 'cloudwatch' \| 'stackdriver' \| 'azure_monitor' \| 'datadog' \| 'splunk' \| 'loki' \| 'http' \| 'kafka' \| 'redis' \| 'custom'>; level: Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>; enabled: boolean; … }[]` | ✅ | Log destinations | +| **enrichment** | `{ staticFields?: Record; dynamicEnrichers?: string[]; addHostname: boolean; addProcessId: boolean; … }` | optional | Log enrichment configuration | | **redact** | `string[]` | ✅ | Fields to redact | -| **sampling** | `Object` | optional | | -| **buffer** | `Object` | optional | | -| **performance** | `Object` | optional | | +| **sampling** | `{ enabled: boolean; rate: number; rateByLevel?: Record }` | optional | | +| **buffer** | `{ enabled: boolean; size: integer; flushInterval: integer; flushOnShutdown: boolean }` | optional | | +| **performance** | `{ async: boolean; workers: integer }` | optional | | --- @@ -289,13 +289,13 @@ Structured log entry | **level** | `Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | ✅ | Log severity level | | **message** | `string` | ✅ | Log message | | **context** | `Record` | optional | Structured context | -| **error** | `Object` | optional | Error details | -| **trace** | `Object` | optional | Distributed tracing context | -| **source** | `Object` | optional | Source information | -| **host** | `Object` | optional | Host information | +| **error** | `{ name?: string; message?: string; stack?: string; code?: string; … }` | optional | Error details | +| **trace** | `{ traceId: string; spanId: string; parentSpanId?: string; traceFlags?: integer }` | optional | Distributed tracing context | +| **source** | `{ service?: string; component?: string; file?: string; line?: integer; … }` | optional | Source information | +| **host** | `{ hostname?: string; pid?: integer; ip?: string }` | optional | Host information | | **environment** | `string` | optional | Environment (e.g., production, staging) | -| **user** | `Object` | optional | User context | -| **request** | `Object` | optional | Request context | +| **user** | `{ id?: string; username?: string; email?: string }` | optional | User context | +| **request** | `{ id?: string; method?: string; path?: string; userAgent?: string; … }` | optional | Request context | | **labels** | `Record` | optional | Custom labels | | **metadata** | `Record` | optional | Additional metadata | diff --git a/content/docs/references/system/message-queue.mdx b/content/docs/references/system/message-queue.mdx index a3356c408a..42455533c9 100644 --- a/content/docs/references/system/message-queue.mdx +++ b/content/docs/references/system/message-queue.mdx @@ -65,11 +65,11 @@ Top-level message queue configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **provider** | `Enum<'kafka' \| 'rabbitmq' \| 'aws-sqs' \| 'redis-pubsub' \| 'google-pubsub' \| 'azure-service-bus'>` | ✅ | Message queue backend provider | -| **topics** | `Object[]` | ✅ | List of topic configurations | -| **consumers** | `Object[]` | optional | Consumer group configurations | -| **deadLetterQueue** | `Object` | optional | Dead letter queue for failed messages | +| **topics** | `{ name: string; partitions: number; replicationFactor: number; retentionMs?: number; … }[]` | ✅ | List of topic configurations | +| **consumers** | `{ groupId: string; autoOffsetReset: Enum<'earliest' \| 'latest'>; enableAutoCommit: boolean; maxPollRecords: number }[]` | optional | Consumer group configurations | +| **deadLetterQueue** | `{ enabled: boolean; maxRetries: number; queueName: string }` | optional | Dead letter queue for failed messages | | **ssl** | `boolean` | ✅ | Enable SSL/TLS for broker connections | -| **sasl** | `Object` | optional | SASL authentication configuration | +| **sasl** | `{ mechanism: Enum<'plain' \| 'scram-sha-256' \| 'scram-sha-512'>; username: string; password: string }` | optional | SASL authentication configuration | --- diff --git a/content/docs/references/system/metadata-loader.mdx b/content/docs/references/system/metadata-loader.mdx index 41d4550607..43bc2a5c7d 100644 --- a/content/docs/references/system/metadata-loader.mdx +++ b/content/docs/references/system/metadata-loader.mdx @@ -43,12 +43,12 @@ const result = MetadataFallbackStrategy.parse(data); | **fallback** | `Enum<'filesystem' \| 'memory' \| 'none'>` | ✅ | Fallback strategy when datasource is unavailable | | **rootDir** | `string` | optional | Root directory path | | **formats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Enabled formats | -| **cache** | `Object` | optional | Cache settings | +| **cache** | `{ enabled: boolean; ttl: integer; maxSize?: integer; databaseLoader?: object }` | optional | Cache settings | | **watch** | `boolean` | ✅ | Enable file watching | -| **watchOptions** | `Object` | optional | File watcher options | -| **validation** | `Object` | optional | Validation settings | +| **watchOptions** | `{ ignored?: string[]; persistent: boolean; ignoreInitial: boolean }` | optional | File watcher options | +| **validation** | `{ strict: boolean; throwOnError: boolean }` | optional | Validation settings | | **loaderOptions** | `Record` | optional | Loader-specific configuration | -| **persistence** | `Object` | optional | Persistence write gates | +| **persistence** | `{ writable: boolean; overlayWritable: boolean }` | optional | Persistence write gates | --- diff --git a/content/docs/references/system/metadata-persistence.mdx b/content/docs/references/system/metadata-persistence.mdx index d6d77def4b..5d5e3f1814 100644 --- a/content/docs/references/system/metadata-persistence.mdx +++ b/content/docs/references/system/metadata-persistence.mdx @@ -108,7 +108,7 @@ const result = MetadataCollectionInfo.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **records** | `Object[]` | ✅ | | +| **records** | `{ id: string; name: string; type: string; version: number; … }[]` | ✅ | | | **total** | `integer` | ✅ | | | **hasMore** | `boolean` | ✅ | | @@ -193,7 +193,7 @@ const result = MetadataCollectionInfo.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **data** | `any` | ✅ | | -| **stats** | `Object` | optional | | +| **stats** | `{ path?: string; size?: number; mtime?: string; hash?: string; … }` | optional | | | **format** | `Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>` | optional | | | **source** | `string` | optional | | | **fromCache** | `boolean` | optional | | @@ -217,7 +217,7 @@ const result = MetadataCollectionInfo.parse(data); | **supportsWatch** | `boolean` | optional | | | **supportsWrite** | `boolean` | optional | | | **supportsCache** | `boolean` | optional | | -| **capabilities** | `Object` | ✅ | | +| **capabilities** | `{ read: boolean; write: boolean; watch: boolean; list: boolean }` | ✅ | | --- @@ -286,7 +286,7 @@ const result = MetadataCollectionInfo.parse(data); | :--- | :--- | :--- | :--- | | **success** | `boolean` | ✅ | | | **path** | `string` | optional | | -| **stats** | `Object` | optional | | +| **stats** | `{ path?: string; size?: number; mtime?: string; hash?: string; … }` | optional | | | **etag** | `string` | optional | | | **size** | `number` | optional | | | **saveTime** | `number` | optional | | @@ -356,7 +356,7 @@ const result = MetadataCollectionInfo.parse(data); | **type** | `Enum<'add' \| 'change' \| 'unlink' \| 'added' \| 'changed' \| 'deleted'>` | ✅ | | | **path** | `string` | ✅ | | | **name** | `string` | optional | | -| **stats** | `Object` | optional | | +| **stats** | `{ path?: string; size?: number; mtime?: string; hash?: string; … }` | optional | | | **metadataType** | `string` | optional | | | **data** | `any` | optional | | | **timestamp** | `string` | optional | | @@ -375,7 +375,7 @@ const result = MetadataCollectionInfo.parse(data); | **version** | `integer` | ✅ | New version number after publish | | **publishedAt** | `string` | ✅ | Publish timestamp | | **itemsPublished** | `integer` | ✅ | Total metadata items published | -| **validationErrors** | `Object[]` | optional | Validation errors if publish failed | +| **validationErrors** | `{ type: string; name: string; message: string }[]` | optional | Validation errors if publish failed | --- diff --git a/content/docs/references/system/metrics.mdx b/content/docs/references/system/metrics.mdx index b399217170..3ec5f44042 100644 --- a/content/docs/references/system/metrics.mdx +++ b/content/docs/references/system/metrics.mdx @@ -44,9 +44,9 @@ Histogram bucket configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **type** | `Enum<'linear' \| 'exponential' \| 'explicit'>` | ✅ | Bucket type | -| **linear** | `Object` | optional | | -| **exponential** | `Object` | optional | | -| **explicit** | `Object` | optional | | +| **linear** | `{ start: number; width: number; count: integer }` | optional | | +| **exponential** | `{ start: number; factor: number; count: integer }` | optional | | +| **explicit** | `{ boundaries: number[] }` | optional | | --- @@ -60,7 +60,7 @@ Metric aggregation configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **type** | `Enum<'sum' \| 'avg' \| 'min' \| 'max' \| 'count' \| 'p50' \| 'p75' \| 'p90' \| 'p95' \| 'p99' \| 'p999' \| 'rate' \| 'stddev'>` | ✅ | Aggregation type | -| **window** | `Object` | optional | | +| **window** | `{ size: integer; sliding: boolean; slideInterval?: integer }` | optional | | | **groupBy** | `string[]` | optional | Group by label names | | **filters** | `Record` | optional | Filter criteria | @@ -103,8 +103,8 @@ Metric data point | **timestamp** | `string` | ✅ | Observation timestamp | | **value** | `number` | optional | Metric value | | **labels** | `Record` | optional | Metric labels | -| **histogram** | `Object` | optional | | -| **summary** | `Object` | optional | | +| **histogram** | `{ count: integer; sum: number; buckets: { upperBound: number; count: integer }[] }` | optional | | +| **summary** | `{ count: integer; sum: number; quantiles: { quantile: number; value: number }[] }` | optional | | --- @@ -123,8 +123,8 @@ Metric definition | **unit** | `Enum<'nanoseconds' \| 'microseconds' \| 'milliseconds' \| 'seconds' \| 'minutes' \| 'hours' \| 'days' \| 'bytes' \| 'kilobytes' \| 'megabytes' \| 'gigabytes' \| 'terabytes' \| 'requests_per_second' \| 'events_per_second' \| 'bytes_per_second' \| 'percent' \| 'ratio' \| 'count' \| 'operations' \| 'custom'>` | optional | Metric unit | | **description** | `string` | optional | Metric description | | **labelNames** | `string[]` | ✅ | Label names | -| **histogram** | `Object` | optional | Histogram bucket configuration | -| **summary** | `Object` | optional | | +| **histogram** | `{ type: Enum<'linear' \| 'exponential' \| 'explicit'>; linear?: object; exponential?: object; explicit?: object }` | optional | Histogram bucket configuration | +| **summary** | `{ quantiles: number[]; maxAge: integer; ageBuckets: integer }` | optional | | | **enabled** | `boolean` | ✅ | | @@ -141,8 +141,8 @@ Metric export configuration | **type** | `Enum<'prometheus' \| 'openmetrics' \| 'graphite' \| 'statsd' \| 'influxdb' \| 'datadog' \| 'cloudwatch' \| 'stackdriver' \| 'azure_monitor' \| 'http' \| 'custom'>` | ✅ | Export type | | **endpoint** | `string` | optional | Export endpoint | | **interval** | `integer` | ✅ | | -| **batch** | `Object` | optional | | -| **auth** | `Object` | optional | | +| **batch** | `{ enabled: boolean; size: integer }` | optional | | +| **auth** | `{ type: Enum<'none' \| 'basic' \| 'bearer' \| 'api_key'>; username?: string; password?: string; token?: string; … }` | optional | | | **config** | `Record` | optional | Additional configuration | @@ -206,15 +206,15 @@ Metrics configuration | **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | | **label** | `string` | ✅ | Display label | | **enabled** | `boolean` | optional | | -| **metrics** | `Object[]` | optional | | +| **metrics** | `{ name: string; label?: string; type: Enum<'counter' \| 'gauge' \| 'histogram' \| 'summary'>; unit?: Enum<'nanoseconds' \| 'microseconds' \| 'milliseconds' \| 'seconds' \| 'minutes' \| 'hours' \| 'days' \| 'bytes' \| 'kilobytes' \| 'megabytes' \| 'gigabytes' \| 'terabytes' \| 'requests_per_second' \| 'events_per_second' \| 'bytes_per_second' \| 'percent' \| 'ratio' \| 'count' \| 'operations' \| 'custom'>; … }[]` | optional | | | **defaultLabels** | `Record` | optional | Metric labels | -| **aggregations** | `Object[]` | optional | | -| **slis** | `Object[]` | optional | | -| **slos** | `Object[]` | optional | | -| **exports** | `Object[]` | optional | | +| **aggregations** | `{ type: Enum<'sum' \| 'avg' \| 'min' \| 'max' \| 'count' \| 'p50' \| 'p75' \| 'p90' \| 'p95' \| 'p99' \| 'p999' \| 'rate' \| 'stddev'>; window?: object; groupBy?: string[]; filters?: Record }[]` | optional | | +| **slis** | `{ name: string; label: string; description?: string; metric: string; … }[]` | optional | | +| **slos** | `{ name: string; label: string; description?: string; sli: string; … }[]` | optional | | +| **exports** | `{ type: Enum<'prometheus' \| 'openmetrics' \| 'graphite' \| 'statsd' \| 'influxdb' \| 'datadog' \| 'cloudwatch' \| 'stackdriver' \| 'azure_monitor' \| 'http' \| 'custom'>; endpoint?: string; interval?: integer; batch?: object; … }[]` | optional | | | **collectionInterval** | `integer` | optional | | -| **retention** | `Object` | optional | | -| **cardinalityLimits** | `Object` | optional | | +| **retention** | `{ period?: integer; downsampling?: { afterSeconds: integer; resolution: integer }[] }` | optional | | +| **cardinalityLimits** | `{ maxLabelCombinations?: integer; onLimitExceeded?: Enum<'drop' \| 'sample' \| 'alert'> }` | optional | | --- @@ -232,8 +232,8 @@ Service Level Indicator | **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 | +| **successCriteria** | `{ threshold: number; operator: Enum<'lt' \| 'lte' \| 'gt' \| 'gte' \| 'eq'>; percentile?: number } \| string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Success criteria — structured or CEL predicate | +| **window** | `{ size: integer; rolling?: boolean }` | ✅ | Measurement window | | **enabled** | `boolean` | optional | | @@ -252,9 +252,9 @@ Service Level Objective | **description** | `string` | optional | SLO description | | **sli** | `string` | ✅ | SLI name | | **target** | `number` | ✅ | Target percentage | -| **period** | `Object` | ✅ | Time period | -| **errorBudget** | `Object` | optional | | -| **alerts** | `Object[]` | ✅ | | +| **period** | `{ type: Enum<'rolling' \| 'calendar'>; duration?: integer; calendar?: Enum<'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly'> }` | ✅ | Time period | +| **errorBudget** | `{ enabled: boolean; alertThreshold: number; burnRateWindows?: { window: integer; threshold: number }[] }` | optional | | +| **alerts** | `{ name: string; severity: Enum<'info' \| 'warning' \| 'critical'>; condition: object }[]` | ✅ | | | **enabled** | `boolean` | ✅ | | @@ -270,7 +270,7 @@ Time series | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Series name | | **labels** | `Record` | optional | Series labels | -| **dataPoints** | `Object[]` | ✅ | Data points | +| **dataPoints** | `{ timestamp: string; value: number; labels?: Record }[]` | ✅ | Data points | | **startTime** | `string` | optional | Start time | | **endTime** | `string` | optional | End time | diff --git a/content/docs/references/system/migration.mdx b/content/docs/references/system/migration.mdx index c99d8fe426..b33ea9ca8a 100644 --- a/content/docs/references/system/migration.mdx +++ b/content/docs/references/system/migration.mdx @@ -29,10 +29,10 @@ Add a new field to an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'add_field'` | ✅ | | | **objectName** | `string` | ✅ | Target object name | | **fieldName** | `string` | ✅ | Name of the field to add | -| **field** | `Object` | ✅ | Full field definition to add | +| **field** | `{ name?: string; label?: string; 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'>; description?: string; … }` | ✅ | Full field definition to add | --- @@ -50,9 +50,9 @@ A versioned set of atomic schema migration operations | **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 | +| **dependencies** | `{ migrationId: string; package?: string }[]` | optional | Migrations that must run before this one | +| **operations** | `{ type: 'add_field'; objectName: string; fieldName: string; field: object } \| { type: 'modify_field'; objectName: string; fieldName: string; changes: Record } \| { type: 'remove_field'; objectName: string; fieldName: string } \| { type: 'create_object'; object: object } \| { type: 'rename_object'; oldName: string; newName: string } \| { type: 'delete_object'; objectName: string } \| { type: 'execute_sql'; sql: string; description?: string }[]` | ✅ | Ordered list of atomic migration operations | +| **rollback** | `{ type: 'add_field'; objectName: string; fieldName: string; field: object } \| { type: 'modify_field'; objectName: string; fieldName: string; changes: Record } \| { type: 'remove_field'; objectName: string; fieldName: string } \| { type: 'create_object'; object: object } \| { type: 'rename_object'; oldName: string; newName: string } \| { type: 'delete_object'; objectName: string } \| { type: 'execute_sql'; sql: string; description?: string }[]` | optional | Operations to reverse this migration | --- @@ -65,8 +65,8 @@ Create a new object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **object** | `Object` | ✅ | Full object definition to create | +| **type** | `'create_object'` | ✅ | | +| **object** | `{ name: string; label?: string; pluralLabel?: string; description?: string; … }` | ✅ | Full object definition to create | --- @@ -79,7 +79,7 @@ Delete an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'delete_object'` | ✅ | | | **objectName** | `string` | ✅ | Name of the object to delete | @@ -93,7 +93,7 @@ Execute a raw SQL statement | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'execute_sql'` | ✅ | | | **sql** | `string` | ✅ | Raw SQL statement to execute | | **description** | `string` | optional | Human-readable description of the SQL | @@ -130,10 +130,10 @@ Add a new field to an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'add_field'` | ✅ | | | **objectName** | `string` | ✅ | Target object name | | **fieldName** | `string` | ✅ | Name of the field to add | -| **field** | `Object` | ✅ | Full field definition to add | +| **field** | `{ name?: string; label?: string; 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'>; description?: string; … }` | ✅ | Full field definition to add | --- @@ -147,7 +147,7 @@ Modify properties of an existing field | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'modify_field'` | ✅ | | | **objectName** | `string` | ✅ | Target object name | | **fieldName** | `string` | ✅ | Name of the field to modify | | **changes** | `Record` | ✅ | Partial field definition updates | @@ -164,7 +164,7 @@ Remove a field from an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'remove_field'` | ✅ | | | **objectName** | `string` | ✅ | Target object name | | **fieldName** | `string` | ✅ | Name of the field to remove | @@ -180,8 +180,8 @@ Create a new object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **object** | `Object` | ✅ | Full object definition to create | +| **type** | `'create_object'` | ✅ | | +| **object** | `{ name: string; label?: string; pluralLabel?: string; description?: string; … }` | ✅ | Full object definition to create | --- @@ -195,7 +195,7 @@ Rename an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'rename_object'` | ✅ | | | **oldName** | `string` | ✅ | Current object name | | **newName** | `string` | ✅ | New object name | @@ -211,7 +211,7 @@ Delete an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'delete_object'` | ✅ | | | **objectName** | `string` | ✅ | Name of the object to delete | --- @@ -226,7 +226,7 @@ Execute a raw SQL statement | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'execute_sql'` | ✅ | | | **sql** | `string` | ✅ | Raw SQL statement to execute | | **description** | `string` | optional | Human-readable description of the SQL | @@ -243,7 +243,7 @@ Modify properties of an existing field | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'modify_field'` | ✅ | | | **objectName** | `string` | ✅ | Target object name | | **fieldName** | `string` | ✅ | Name of the field to modify | | **changes** | `Record` | ✅ | Partial field definition updates | @@ -259,7 +259,7 @@ Remove a field from an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'remove_field'` | ✅ | | | **objectName** | `string` | ✅ | Target object name | | **fieldName** | `string` | ✅ | Name of the field to remove | @@ -274,7 +274,7 @@ Rename an existing object | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'rename_object'` | ✅ | | | **oldName** | `string` | ✅ | Current object name | | **newName** | `string` | ✅ | New object name | diff --git a/content/docs/references/system/notification.mdx b/content/docs/references/system/notification.mdx index 289636b7db..f064828d25 100644 --- a/content/docs/references/system/notification.mdx +++ b/content/docs/references/system/notification.mdx @@ -66,11 +66,11 @@ const result = EmailTemplate.parse(data); | 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 | +| **subject** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Email subject — supports `{{var}`} interpolation | +| **body** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **attachments** | `{ name: string; url: string }[]` | optional | Email attachments | --- @@ -82,7 +82,7 @@ const result = EmailTemplate.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **title** | `string` | ✅ | Notification title | -| **message** | `string \| Object` | ✅ | Notification message — supports `{{var}`} interpolation | +| **message** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Notification message — supports `{{var}`} interpolation | | **type** | `Enum<'info' \| 'success' \| 'warning' \| 'error'>` | ✅ | Notification type | | **actionUrl** | `string` | optional | Action URL | | **dismissible** | `boolean` | optional | User dismissible | @@ -115,11 +115,11 @@ const result = EmailTemplate.parse(data); | **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 | +| **template** | `{ id: string; subject: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; body: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; bodyType?: Enum<'text' \| 'html' \| 'markdown'>; … } \| { id: string; message: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; maxLength?: number; variables?: string[] } \| { title: string; body: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; icon?: string; badge?: number; … } \| { title: string; message: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; type: Enum<'info' \| 'success' \| 'warning' \| 'error'>; actionUrl?: string; … }` | ✅ | Notification template | +| **recipients** | `{ to: string[]; cc?: string[]; bcc?: string[] }` | ✅ | Recipients | +| **schedule** | `{ type: Enum<'immediate' \| 'delayed' \| 'scheduled'>; delay?: number; scheduledAt?: number }` | optional | Scheduling | +| **retryPolicy** | `{ enabled?: boolean; maxRetries?: number; backoffStrategy: Enum<'exponential' \| 'linear' \| 'fixed'> }` | optional | Retry policy | +| **tracking** | `{ trackOpens?: boolean; trackClicks?: boolean; trackDelivery?: boolean }` | optional | Tracking configuration | --- @@ -131,11 +131,11 @@ const result = EmailTemplate.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **title** | `string` | ✅ | Notification title | -| **body** | `string \| Object` | ✅ | Notification body — supports `{{var}`} interpolation | +| **body** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **actions** | `{ action: string; title: string }[]` | optional | Notification actions | --- @@ -147,7 +147,7 @@ const result = EmailTemplate.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **id** | `string` | ✅ | Template identifier | -| **message** | `string \| Object` | ✅ | SMS message content — supports `{{var}`} interpolation | +| **message** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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/object-storage.mdx b/content/docs/references/system/object-storage.mdx index 3eb99bd5c4..504fd7be79 100644 --- a/content/docs/references/system/object-storage.mdx +++ b/content/docs/references/system/object-storage.mdx @@ -54,7 +54,7 @@ const result = AccessControlConfig.parse(data); | **exposeHeaders** | `string[]` | optional | CORS exposed headers | | **maxAge** | `number` | optional | CORS preflight cache duration in seconds | | **corsEnabled** | `boolean` | ✅ | Enable CORS configuration | -| **publicAccess** | `Object` | optional | Public access control | +| **publicAccess** | `{ allowPublicRead: boolean; allowPublicWrite: boolean; allowPublicList: boolean }` | optional | Public access control | | **allowedIps** | `string[]` | optional | Allowed IP addresses/CIDR blocks | | **blockedIps** | `string[]` | optional | Blocked IP addresses/CIDR blocks | @@ -75,10 +75,10 @@ const result = AccessControlConfig.parse(data); | **endpoint** | `string` | optional | Custom endpoint URL (for S3-compatible providers) | | **pathStyle** | `boolean` | ✅ | Use path-style URLs (for S3-compatible providers) | | **versioning** | `boolean` | ✅ | Enable object versioning | -| **encryption** | `Object` | optional | Server-side encryption configuration | -| **accessControl** | `Object` | optional | Access control configuration | -| **lifecyclePolicy** | `Object` | optional | Lifecycle policy configuration | -| **multipartConfig** | `Object` | optional | Multipart upload configuration | +| **encryption** | `{ enabled: boolean; algorithm: Enum<'AES256' \| 'aws:kms' \| 'azure:kms' \| 'gcp:kms'>; kmsKeyId?: string }` | optional | Server-side encryption configuration | +| **accessControl** | `{ acl: Enum<'private' \| 'public_read' \| 'public_read_write' \| 'authenticated_read' \| 'bucket_owner_read' \| 'bucket_owner_full_control'>; allowedOrigins?: string[]; allowedMethods?: Enum<'GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD'>[]; allowedHeaders?: string[]; … }` | optional | Access control configuration | +| **lifecyclePolicy** | `{ enabled: boolean; rules: { id: string; enabled: boolean; action: Enum<'transition' \| 'delete' \| 'abort'>; prefix?: string; … }[] }` | optional | Lifecycle policy configuration | +| **multipartConfig** | `{ enabled: boolean; partSize: number; maxParts: number; threshold: number; … }` | optional | Multipart upload configuration | | **tags** | `Record` | optional | Bucket tags for organization | | **description** | `string` | optional | Bucket description | | **enabled** | `boolean` | ✅ | Enable this bucket | @@ -123,7 +123,7 @@ Lifecycle policy action type | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable lifecycle policies | -| **rules** | `Object[]` | ✅ | Lifecycle rules | +| **rules** | `{ id: string; enabled: boolean; action: Enum<'transition' \| 'delete' \| 'abort'>; prefix?: string; … }[]` | ✅ | Lifecycle rules | --- @@ -178,7 +178,7 @@ Lifecycle policy action type | **lastModified** | `string` | optional | Last modification timestamp | | **versionId** | `string` | optional | Object version identifier | | **storageClass** | `Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>` | optional | Storage class/tier | -| **encryption** | `Object` | optional | Server-side encryption configuration | +| **encryption** | `{ algorithm: string; keyId?: string }` | optional | Server-side encryption configuration | | **custom** | `Record` | optional | Custom user-defined metadata | @@ -194,8 +194,8 @@ Lifecycle policy action type | **label** | `string` | ✅ | Display label | | **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>` | ✅ | Primary storage provider | | **scope** | `Enum<'global' \| 'tenant' \| 'user' \| 'session' \| 'temp' \| 'cache' \| 'data' \| 'logs' \| 'config' \| 'public'>` | ✅ | Storage scope | -| **connection** | `Object` | ✅ | Connection credentials | -| **buckets** | `Object[]` | ✅ | Configured buckets | +| **connection** | `{ accessKeyId?: string; secretAccessKey?: string; sessionToken?: string; accountName?: string; … }` | ✅ | Connection credentials | +| **buckets** | `{ name: string; label: string; bucketName: string; region?: string; … }[]` | ✅ | Configured buckets | | **defaultBucket** | `string` | optional | Default bucket name for operations | | **location** | `string` | optional | Root path (local) or base location | | **quota** | `integer` | optional | Max size in bytes | diff --git a/content/docs/references/system/provisioning.mdx b/content/docs/references/system/provisioning.mdx index 74fa57ff71..b45dcceb3e 100644 --- a/content/docs/references/system/provisioning.mdx +++ b/content/docs/references/system/provisioning.mdx @@ -101,7 +101,7 @@ Tenant provisioning result | **status** | `Enum<'provisioning' \| 'active' \| 'suspended' \| 'failed' \| 'destroying'>` | ✅ | Tenant provisioning lifecycle status | | **region** | `Enum<'us-east' \| 'us-west' \| 'eu-west' \| 'eu-central' \| 'ap-southeast' \| 'ap-northeast'>` | ✅ | Available deployment region | | **plan** | `Enum<'free' \| 'pro' \| 'enterprise'>` | ✅ | Tenant subscription plan | -| **steps** | `Object[]` | ✅ | Pipeline step statuses | +| **steps** | `{ name: string; status: Enum<'pending' \| 'running' \| 'completed' \| 'failed' \| 'skipped'>; startedAt?: string; completedAt?: string; … }[]` | ✅ | Pipeline step statuses | | **totalDurationMs** | `integer` | optional | Total provisioning duration | | **provisionedAt** | `string` | optional | Provisioning completion time | | **error** | `string` | optional | Error message on failure | diff --git a/content/docs/references/system/registry-config.mdx b/content/docs/references/system/registry-config.mdx index aa04382f5d..aad3c6eda7 100644 --- a/content/docs/references/system/registry-config.mdx +++ b/content/docs/references/system/registry-config.mdx @@ -34,14 +34,14 @@ const result = RegistryConfig.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **type** | `Enum<'public' \| 'private' \| 'hybrid'>` | ✅ | Registry deployment type | -| **upstream** | `Object[]` | optional | Upstream registries to sync from or proxy to | +| **upstream** | `{ url: string; syncPolicy: Enum<'manual' \| 'auto' \| 'proxy'>; syncInterval?: integer; auth?: object; … }[]` | optional | Upstream registries to sync from or proxy to | | **scope** | `string[]` | optional | npm-style scopes managed by this registry (e.g., @my-corp, @enterprise) | | **defaultScope** | `string` | optional | Default scope prefix for new plugins | -| **storage** | `Object` | optional | | +| **storage** | `{ backend: Enum<'local' \| 's3' \| 'gcs' \| 'azure-blob' \| 'oss'>; path?: string; credentials?: Record }` | optional | | | **visibility** | `Enum<'public' \| 'private' \| 'internal'>` | ✅ | Who can access this registry | -| **accessControl** | `Object` | optional | | -| **cache** | `Object` | optional | | -| **mirrors** | `Object[]` | optional | Mirror registries for redundancy | +| **accessControl** | `{ requireAuthForRead: boolean; requireAuthForWrite: boolean; allowedPrincipals?: string[] }` | optional | | +| **cache** | `{ enabled: boolean; ttl: integer; maxSize?: integer }` | optional | | +| **mirrors** | `{ url: string; priority: integer }[]` | optional | Mirror registries for redundancy | --- @@ -68,10 +68,10 @@ Registry synchronization strategy | **url** | `string` | ✅ | Upstream registry endpoint | | **syncPolicy** | `Enum<'manual' \| 'auto' \| 'proxy'>` | ✅ | Registry synchronization strategy | | **syncInterval** | `integer` | optional | Auto-sync interval in seconds | -| **auth** | `Object` | optional | | -| **tls** | `Object` | optional | | +| **auth** | `{ type: Enum<'none' \| 'basic' \| 'bearer' \| 'api-key' \| 'oauth2'>; username?: string; password?: string; token?: string; … }` | optional | | +| **tls** | `{ enabled: boolean; verifyCertificate: boolean; certificate?: string; privateKey?: string }` | optional | | | **timeout** | `integer` | ✅ | Request timeout in milliseconds | -| **retry** | `Object` | optional | | +| **retry** | `{ maxAttempts: integer; backoff: Enum<'fixed' \| 'linear' \| 'exponential'> }` | optional | | --- diff --git a/content/docs/references/system/search-engine.mdx b/content/docs/references/system/search-engine.mdx index 27abe86f63..bb50c87e77 100644 --- a/content/docs/references/system/search-engine.mdx +++ b/content/docs/references/system/search-engine.mdx @@ -65,9 +65,9 @@ Top-level full-text search engine configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **provider** | `Enum<'elasticsearch' \| 'algolia' \| 'meilisearch' \| 'typesense' \| 'opensearch'>` | ✅ | Search engine backend provider | -| **indexes** | `Object[]` | ✅ | Search index definitions | -| **analyzers** | `Record` | optional | Named text analyzer configurations | -| **facets** | `Object[]` | optional | Faceted search configurations | +| **indexes** | `{ indexName: string; objectName: string; fields: { name: string; type: Enum<'text' \| 'keyword' \| 'number' \| 'date' \| 'boolean' \| 'geo'>; analyzer?: string; searchable: boolean; … }[]; replicas: number; … }[]` | ✅ | Search index definitions | +| **analyzers** | `Record; language?: string; stopwords?: string[]; customFilters?: string[] }>` | optional | Named text analyzer configurations | +| **facets** | `{ field: string; maxValues: number; sort: Enum<'count' \| 'alpha'> }[]` | optional | Faceted search configurations | | **typoTolerance** | `boolean` | ✅ | Enable typo-tolerant search | | **synonyms** | `Record` | optional | Synonym mappings for search expansion | | **ranking** | `Enum<'typo' \| 'geo' \| 'words' \| 'filters' \| 'proximity' \| 'attribute' \| 'exact' \| 'custom'>[]` | optional | Custom ranking rule order | @@ -85,7 +85,7 @@ Search index definition mapping an ObjectQL object to a search engine index | :--- | :--- | :--- | :--- | | **indexName** | `string` | ✅ | Name of the search index | | **objectName** | `string` | ✅ | Source ObjectQL object | -| **fields** | `Object[]` | ✅ | Fields to include in the search index | +| **fields** | `{ name: string; type: Enum<'text' \| 'keyword' \| 'number' \| 'date' \| 'boolean' \| 'geo'>; analyzer?: string; searchable: boolean; … }[]` | ✅ | Fields to include in the search index | | **replicas** | `number` | ✅ | Number of index replicas for availability | | **shards** | `number` | ✅ | Number of index shards for distribution | diff --git a/content/docs/references/system/security-context.mdx b/content/docs/references/system/security-context.mdx index e8c11f0a00..bbcac1bfd3 100644 --- a/content/docs/references/system/security-context.mdx +++ b/content/docs/references/system/security-context.mdx @@ -27,7 +27,7 @@ audit visibility, and all security operations are correlated in a single governance context. -@see https://www.iso.org/standard/27001 +See also: https://www.iso.org/standard/27001 @category Security @@ -156,11 +156,11 @@ Unified security context governance configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable unified security context governance | -| **complianceAuditRequirements** | `Object[]` | optional | Compliance-driven audit event requirements | -| **complianceEncryptionRequirements** | `Object[]` | optional | Compliance-driven encryption requirements by data classification | -| **maskingVisibility** | `Object[]` | optional | Masking visibility rules per data classification | -| **dataClassifications** | `Object[]` | optional | Data classification policies for unified security enforcement | -| **eventCorrelation** | `Object` | optional | Cross-subsystem security event correlation settings | +| **complianceAuditRequirements** | `{ framework: Enum<'gdpr' \| 'hipaa' \| 'sox' \| 'pci_dss' \| 'ccpa' \| 'iso27001'>; requiredEvents: string[]; retentionDays: number; alertOnMissing: boolean }[]` | optional | Compliance-driven audit event requirements | +| **complianceEncryptionRequirements** | `{ framework: Enum<'gdpr' \| 'hipaa' \| 'sox' \| 'pci_dss' \| 'ccpa' \| 'iso27001'>; dataClassifications: Enum<'pii' \| 'phi' \| 'pci' \| 'financial' \| 'confidential' \| 'internal' \| 'public'>[]; minimumAlgorithm: Enum<'aes-256-gcm' \| 'aes-256-cbc' \| 'chacha20-poly1305'>; keyRotationMaxDays: number }[]` | optional | Compliance-driven encryption requirements by data classification | +| **maskingVisibility** | `{ dataClassification: Enum<'pii' \| 'phi' \| 'pci' \| 'financial' \| 'confidential' \| 'internal' \| 'public'>; defaultMasked: boolean; unmaskRoles?: string[]; auditUnmask: boolean; … }[]` | optional | Masking visibility rules per data classification | +| **dataClassifications** | `{ classification: Enum<'pii' \| 'phi' \| 'pci' \| 'financial' \| 'confidential' \| 'internal' \| 'public'>; requireEncryption: boolean; requireMasking: boolean; requireAudit: boolean; … }[]` | optional | Data classification policies for unified security enforcement | +| **eventCorrelation** | `{ enabled: boolean; correlationId: boolean; linkAuthToAudit: boolean; linkEncryptionToAudit: boolean; … }` | optional | Cross-subsystem security event correlation settings | | **enforceOnWrite** | `boolean` | ✅ | Enforce encryption and masking requirements on data write operations | | **enforceOnRead** | `boolean` | ✅ | Enforce masking and audit requirements on data read operations | | **failOpen** | `boolean` | ✅ | When false (default), deny access if security context cannot be evaluated | diff --git a/content/docs/references/system/settings-manifest.mdx b/content/docs/references/system/settings-manifest.mdx index 017be15838..58f1c0d231 100644 --- a/content/docs/references/system/settings-manifest.mdx +++ b/content/docs/references/system/settings-manifest.mdx @@ -59,7 +59,7 @@ const result = ResolvedSettingValue.parse(data); | **source** | `Enum<'env' \| 'global' \| 'tenant' \| 'user' \| 'default'>` | ✅ | Resolution source | | **locked** | `boolean` | ✅ | Cannot be overridden from UI | | **lockedReason** | `string` | optional | Reason for the lock (UI tooltip) | -| **cascadeChain** | `Object[]` | optional | Full cascade trace (env → global → tenant → user → default) | +| **cascadeChain** | `{ scope: Enum<'env' \| 'global' \| 'tenant' \| 'user' \| 'default'>; value: any; locked?: boolean; lockedReason?: string; … }[]` | optional | Full cascade trace (env → global → tenant → user → default) | --- @@ -95,8 +95,8 @@ const result = ResolvedSettingValue.parse(data); | **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 | +| **specifiers** | `{ 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'>; id?: string; key?: string; label: string; … }[]` | ✅ | Page contents (ordered) | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -109,8 +109,8 @@ const result = ResolvedSettingValue.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | | -| **values** | `Record` | ✅ | Effective values keyed by specifier.key | +| **manifest** | `{ namespace: string; version?: integer; label: string; icon?: string; … }` | ✅ | | +| **values** | `Record; locked: boolean; lockedReason?: string; … }>` | ✅ | Effective values keyed by specifier.key | --- @@ -128,7 +128,7 @@ const result = ResolvedSettingValue.parse(data); | **description** | `string` | optional | Help text | | **icon** | `string` | optional | Icon name (Lucide) | | **default** | `any` | optional | Default value | -| **visible** | `string \| Object` | optional | Visibility expression | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | @@ -138,7 +138,7 @@ const result = ResolvedSettingValue.parse(data); | **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 | +| **options** | `{ value: string \| number \| boolean; label: string; description?: string; icon?: string }[]` | optional | Options for select/radio/multiselect | | **min** | `number` | optional | | | **max** | `number` | optional | | | **step** | `number` | optional | | @@ -146,7 +146,7 @@ const result = ResolvedSettingValue.parse(data); | **maxLength** | `integer` | optional | | | **pattern** | `string` | optional | Regex pattern (text only) | | **rows** | `integer` | optional | | -| **handler** | `Object \| Object \| Object` | optional | Action handler (action_button) | +| **handler** | `{ kind: 'http'; method?: Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'>; url: string; body?: Record; … } \| { kind: 'action'; name: string; params?: Record; confirmText?: string } \| { kind: 'navigate'; url: string; target?: Enum<'_self' \| '_blank'> }` | 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 | | @@ -166,7 +166,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'http'` | ✅ | | | **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'>` | ✅ | | | **url** | `string` | ✅ | Endpoint URL; supports $`{...}` interpolation | | **body** | `Record` | optional | Optional JSON body; supports $`{...}` interpolation | @@ -180,7 +180,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'action'` | ✅ | | | **name** | `string` | ✅ | Registered action machine name | | **params** | `Record` | optional | | | **confirmText** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | @@ -193,7 +193,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | | +| **kind** | `'navigate'` | ✅ | | | **url** | `string` | ✅ | Target URL or in-app route | | **target** | `Enum<'_self' \| '_blank'>` | ✅ | | diff --git a/content/docs/references/system/supplier-security.mdx b/content/docs/references/system/supplier-security.mdx index 89fb5665b7..4f03c5e65c 100644 --- a/content/docs/references/system/supplier-security.mdx +++ b/content/docs/references/system/supplier-security.mdx @@ -11,7 +11,7 @@ Defines schemas for supplier information security management including risk assessment, security requirements, monitoring, and change control. -@see https://www.iso.org/standard/27001 +See also: https://www.iso.org/standard/27001 @category Security @@ -71,12 +71,12 @@ Supplier security assessment record per ISO 27001:2022 A.5.19–A.5.21 | **assessedBy** | `string` | ✅ | Assessor user ID or team | | **assessedAt** | `number` | ✅ | Assessment timestamp | | **validUntil** | `number` | ✅ | Assessment validity expiry timestamp | -| **requirements** | `Object[]` | ✅ | Security requirements and their compliance status | +| **requirements** | `{ id: string; description: string; controlReference?: string; mandatory: boolean; … }[]` | ✅ | Security requirements and their compliance status | | **overallCompliant** | `boolean` | ✅ | Whether supplier meets all mandatory requirements | | **dataClassificationsShared** | `Enum<'pii' \| 'phi' \| 'pci' \| 'financial' \| 'confidential' \| 'internal' \| 'public'>[]` | optional | Data classifications shared with supplier | | **servicesProvided** | `string[]` | optional | Services provided by this supplier | | **certifications** | `string[]` | optional | Supplier certifications (e.g., ISO 27001, SOC 2) | -| **remediationItems** | `Object[]` | optional | Remediation items for non-compliant requirements | +| **remediationItems** | `{ requirementId: string; action: string; deadline: number; status: Enum<'pending' \| 'in_progress' \| 'completed'> }[]` | optional | Remediation items for non-compliant requirements | | **metadata** | `Record` | optional | Custom metadata key-value pairs | diff --git a/content/docs/references/system/tenant.mdx b/content/docs/references/system/tenant.mdx index 3506e63e67..a6fa0c542a 100644 --- a/content/docs/references/system/tenant.mdx +++ b/content/docs/references/system/tenant.mdx @@ -43,11 +43,11 @@ const result = DatabaseLevelIsolationStrategy.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Database-level isolation strategy | -| **database** | `Object` | optional | Database configuration | -| **connectionPool** | `Object` | optional | Connection pool configuration | -| **backup** | `Object` | optional | Backup configuration | -| **encryption** | `Object` | optional | Encryption configuration | +| **strategy** | `'isolated_db'` | ✅ | Database-level isolation strategy | +| **database** | `{ namingPattern: string; serverStrategy: Enum<'shared' \| 'sharded' \| 'dedicated'>; separateCredentials: boolean; autoCreateDatabase: boolean }` | optional | Database configuration | +| **connectionPool** | `{ poolSize: integer; maxActivePools: integer; idleTimeout: integer; usePooler: boolean }` | optional | Connection pool configuration | +| **backup** | `{ strategy: Enum<'individual' \| 'consolidated' \| 'on_demand'>; frequencyHours: integer; retentionDays: integer }` | optional | Backup configuration | +| **encryption** | `{ perTenantKeys: boolean; algorithm: string; keyManagement?: Enum<'aws_kms' \| 'azure_key_vault' \| 'gcp_kms' \| 'hashicorp_vault' \| 'custom'> }` | optional | Encryption configuration | --- @@ -71,10 +71,10 @@ Database provider for tenant data | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Schema-level isolation strategy | -| **schema** | `Object` | optional | Schema configuration | -| **migrations** | `Object` | optional | Migration configuration | -| **performance** | `Object` | optional | Performance settings | +| **strategy** | `'isolated_schema'` | ✅ | Schema-level isolation strategy | +| **schema** | `{ namingPattern: string; includePublicSchema: boolean; sharedSchema: string; autoCreateSchema: boolean }` | optional | Schema configuration | +| **migrations** | `{ strategy: Enum<'parallel' \| 'sequential' \| 'on_demand'>; maxConcurrent: integer; rollbackOnError: boolean }` | optional | Migration configuration | +| **performance** | `{ poolPerSchema: boolean; schemaCacheTTL: integer }` | optional | Performance settings | --- @@ -102,9 +102,9 @@ Quota enforcement check result | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Row-level isolation strategy | -| **database** | `Object` | optional | Database configuration | -| **performance** | `Object` | optional | Performance settings | +| **strategy** | `'shared_schema'` | ✅ | Row-level isolation strategy | +| **database** | `{ enableRLS: boolean; contextMethod: Enum<'session_variable' \| 'search_path' \| 'application_name'>; contextVariable: string; applicationValidation: boolean }` | optional | Database configuration | +| **performance** | `{ usePartialIndexes: boolean; usePartitioning: boolean; poolSizePerTenant?: integer }` | optional | Performance settings | --- @@ -119,11 +119,11 @@ Quota enforcement check result | **name** | `string` | ✅ | Tenant display name | | **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | ✅ | | | **databaseProvider** | `Enum<'turso' \| 'postgres' \| 'memory'>` | optional | Database provider | -| **connectionConfig** | `Object` | optional | Database connection config | +| **connectionConfig** | `{ url: string; authToken?: string; group?: string }` | optional | Database connection config | | **provisioningStatus** | `Enum<'provisioning' \| 'active' \| 'suspended' \| 'failed' \| 'destroying'>` | optional | Current provisioning lifecycle status | | **plan** | `Enum<'free' \| 'pro' \| 'enterprise'>` | optional | Subscription plan | | **customizations** | `Record` | optional | Custom configuration values | -| **quotas** | `Object` | optional | | +| **quotas** | `{ maxUsers?: integer; maxStorage?: integer; apiRateLimit?: integer; maxObjects?: integer; … }` | optional | | --- @@ -155,9 +155,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Row-level isolation strategy | -| **database** | `Object` | optional | Database configuration | -| **performance** | `Object` | optional | Performance settings | +| **strategy** | `'shared_schema'` | ✅ | Row-level isolation strategy | +| **database** | `{ enableRLS: boolean; contextMethod: Enum<'session_variable' \| 'search_path' \| 'application_name'>; contextVariable: string; applicationValidation: boolean }` | optional | Database configuration | +| **performance** | `{ usePartialIndexes: boolean; usePartitioning: boolean; poolSizePerTenant?: integer }` | optional | Performance settings | --- @@ -167,10 +167,10 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Schema-level isolation strategy | -| **schema** | `Object` | optional | Schema configuration | -| **migrations** | `Object` | optional | Migration configuration | -| **performance** | `Object` | optional | Performance settings | +| **strategy** | `'isolated_schema'` | ✅ | Schema-level isolation strategy | +| **schema** | `{ namingPattern: string; includePublicSchema: boolean; sharedSchema: string; autoCreateSchema: boolean }` | optional | Schema configuration | +| **migrations** | `{ strategy: Enum<'parallel' \| 'sequential' \| 'on_demand'>; maxConcurrent: integer; rollbackOnError: boolean }` | optional | Migration configuration | +| **performance** | `{ poolPerSchema: boolean; schemaCacheTTL: integer }` | optional | Performance settings | --- @@ -180,11 +180,11 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Database-level isolation strategy | -| **database** | `Object` | optional | Database configuration | -| **connectionPool** | `Object` | optional | Connection pool configuration | -| **backup** | `Object` | optional | Backup configuration | -| **encryption** | `Object` | optional | Encryption configuration | +| **strategy** | `'isolated_db'` | ✅ | Database-level isolation strategy | +| **database** | `{ namingPattern: string; serverStrategy: Enum<'shared' \| 'sharded' \| 'dedicated'>; separateCredentials: boolean; autoCreateDatabase: boolean }` | optional | Database configuration | +| **connectionPool** | `{ poolSize: integer; maxActivePools: integer; idleTimeout: integer; usePooler: boolean }` | optional | Connection pool configuration | +| **backup** | `{ strategy: Enum<'individual' \| 'consolidated' \| 'on_demand'>; frequencyHours: integer; retentionDays: integer }` | optional | Backup configuration | +| **encryption** | `{ perTenantKeys: boolean; algorithm: string; keyManagement?: Enum<'aws_kms' \| 'azure_key_vault' \| 'gcp_kms' \| 'hashicorp_vault' \| 'custom'> }` | optional | Encryption configuration | --- @@ -225,9 +225,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **encryption** | `Object` | optional | Encryption requirements | -| **accessControl** | `Object` | optional | Access control requirements | -| **compliance** | `Object` | optional | Compliance requirements | +| **encryption** | `{ atRest: boolean; inTransit: boolean; fieldLevel: boolean }` | optional | Encryption requirements | +| **accessControl** | `{ requireMFA: boolean; requireSSO: boolean; ipWhitelist?: string[]; sessionTimeout: integer }` | optional | Access control requirements | +| **compliance** | `{ standards?: Enum<'sox' \| 'hipaa' \| 'gdpr' \| 'pci_dss' \| 'iso_27001' \| 'fedramp'>[]; requireAuditLog: boolean; auditRetentionDays: integer; dataResidency?: object }` | optional | Compliance requirements | --- diff --git a/content/docs/references/system/tracing.mdx b/content/docs/references/system/tracing.mdx index fa06c7682f..1eb38be8d8 100644 --- a/content/docs/references/system/tracing.mdx +++ b/content/docs/references/system/tracing.mdx @@ -44,9 +44,9 @@ OpenTelemetry compatibility configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **sdkVersion** | `string` | optional | OTel SDK version | -| **exporter** | `Object` | ✅ | Exporter configuration | -| **resource** | `Object` | ✅ | Resource attributes | -| **instrumentation** | `Object` | optional | | +| **exporter** | `{ type: Enum<'otlp_http' \| 'otlp_grpc' \| 'jaeger' \| 'zipkin' \| 'console' \| 'datadog' \| 'honeycomb' \| 'lightstep' \| 'newrelic' \| 'custom'>; endpoint?: string; protocol?: string; headers?: Record; … }` | ✅ | Exporter configuration | +| **resource** | `{ serviceName: string; serviceVersion?: string; serviceInstanceId?: string; serviceNamespace?: string; … }` | ✅ | Resource attributes | +| **instrumentation** | `{ autoInstrumentation: boolean; libraries?: string[]; disabledLibraries?: string[] }` | optional | | | **semanticConventionsVersion** | `string` | optional | Semantic conventions version | @@ -111,18 +111,18 @@ OpenTelemetry span | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | ✅ | Trace context | +| **context** | `{ traceId: string; spanId: string; traceFlags: integer; traceState?: object; … }` | ✅ | Trace context | | **name** | `string` | ✅ | Span name | | **kind** | `Enum<'internal' \| 'server' \| 'client' \| 'producer' \| 'consumer'>` | ✅ | Span kind | | **startTime** | `string` | ✅ | Span start time | | **endTime** | `string` | optional | Span end time | | **duration** | `number` | optional | Duration in milliseconds | -| **status** | `Object` | optional | | +| **status** | `{ code: Enum<'unset' \| 'ok' \| 'error'>; message?: string }` | optional | | | **attributes** | `Record` | ✅ | Span attributes | -| **events** | `Object[]` | ✅ | | -| **links** | `Object[]` | ✅ | | +| **events** | `{ name: string; timestamp: string; attributes?: Record }[]` | ✅ | | +| **links** | `{ context: object; attributes?: Record }[]` | ✅ | | | **resource** | `Record` | optional | Resource attributes | -| **instrumentationLibrary** | `Object` | optional | | +| **instrumentationLibrary** | `{ name: string; version?: string }` | optional | | --- @@ -215,7 +215,7 @@ Span link | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **context** | `Object` | ✅ | Linked trace context | +| **context** | `{ traceId: string; spanId: string; traceFlags: integer; traceState?: object; … }` | ✅ | Linked trace context | | **attributes** | `Record` | optional | Link attributes | @@ -245,7 +245,7 @@ Trace context (W3C Trace Context) | **traceId** | `string` | ✅ | Trace ID (32 hex chars) | | **spanId** | `string` | ✅ | Span ID (16 hex chars) | | **traceFlags** | `integer` | ✅ | Trace flags bitmap | -| **traceState** | `Object` | optional | Trace state | +| **traceState** | `{ entries: Record }` | optional | Trace state | | **parentSpanId** | `string` | optional | Parent span ID (16 hex chars) | | **sampled** | `boolean` | ✅ | | | **remote** | `boolean` | ✅ | | @@ -264,8 +264,8 @@ Trace context propagation | **formats** | `Enum<'w3c' \| 'b3' \| 'b3_multi' \| 'jaeger' \| 'xray' \| 'ottrace' \| 'custom'>[]` | ✅ | | | **extract** | `boolean` | ✅ | | | **inject** | `boolean` | ✅ | | -| **headers** | `Object` | optional | | -| **baggage** | `Object` | optional | | +| **headers** | `{ traceId?: string; spanId?: string; traceFlags?: string; traceState?: string }` | optional | | +| **baggage** | `{ enabled: boolean; maxSize: integer; allowedKeys?: string[] }` | optional | | --- @@ -301,9 +301,9 @@ Trace sampling configuration | **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 | | +| **parentBased** | `{ whenParentSampled?: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>; whenParentNotSampled?: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>; root?: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>; rootRatio?: number }` | optional | | +| **composite** | `{ strategy: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>; ratio?: number; condition?: Record \| string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } }[]` | optional | | +| **rules** | `{ name: string; match?: object; decision: Enum<'drop' \| 'record_only' \| 'record_and_sample'>; rate?: number }[]` | optional | | | **customSamplerId** | `string` | optional | Custom sampler identifier | @@ -333,13 +333,13 @@ Tracing configuration | **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 | | +| **sampling** | `{ type: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>; ratio?: number; rateLimit?: number; parentBased?: object; … }` | optional | Trace sampling configuration | +| **propagation** | `{ formats?: Enum<'w3c' \| 'b3' \| 'b3_multi' \| 'jaeger' \| 'xray' \| 'ottrace' \| 'custom'>[]; extract?: boolean; inject?: boolean; headers?: object; … }` | optional | Trace context propagation | +| **openTelemetry** | `{ sdkVersion?: string; exporter: object; resource: object; instrumentation?: object; … }` | optional | OpenTelemetry compatibility configuration | +| **spanLimits** | `{ maxAttributes?: integer; maxEvents?: integer; maxLinks?: integer; maxAttributeValueLength?: integer }` | optional | | | **traceIdGenerator** | `Enum<'random' \| 'uuid' \| 'custom'>` | optional | | | **customTraceIdGeneratorId** | `string` | optional | Custom generator identifier | -| **performance** | `Object` | optional | | +| **performance** | `{ asyncExport?: boolean; exportInterval?: integer }` | optional | | --- diff --git a/content/docs/references/system/training.mdx b/content/docs/references/system/training.mdx index 31ddc49cf9..de6716658d 100644 --- a/content/docs/references/system/training.mdx +++ b/content/docs/references/system/training.mdx @@ -11,7 +11,7 @@ Defines schemas for security awareness and training management including course definitions, completion tracking, and organizational training plans. -@see https://www.iso.org/standard/27001 +See also: https://www.iso.org/standard/27001 @category Security @@ -93,7 +93,7 @@ Organizational training plan per ISO 27001:2022 A.6.3 | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable training management | -| **courses** | `Object[]` | ✅ | Training courses | +| **courses** | `{ id: string; title: string; description: string; category: Enum<'security_awareness' \| 'data_protection' \| 'incident_response' \| 'access_control' \| 'phishing_awareness' \| 'compliance' \| 'secure_development' \| 'physical_security' \| 'business_continuity' \| 'other'>; … }[]` | ✅ | Training courses | | **recertificationIntervalDays** | `number` | ✅ | Default recertification interval in days | | **trackCompletion** | `boolean` | ✅ | Track training completion for compliance | | **gracePeriodDays** | `number` | ✅ | Grace period in days after certification expiry | diff --git a/content/docs/references/system/translation.mdx b/content/docs/references/system/translation.mdx index 81d5f348f9..6d310fe869 100644 --- a/content/docs/references/system/translation.mdx +++ b/content/docs/references/system/translation.mdx @@ -33,18 +33,18 @@ Object-first application translation bundle for a single locale | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **_meta** | `Object` | optional | Bundle-level metadata (locale, bidi direction) | +| **_meta** | `{ locale?: string; direction?: Enum<'ltr' \| 'rtl'> }` | optional | Bundle-level metadata (locale, bidi direction) | | **namespace** | `string` | optional | Namespace for plugin isolation to avoid translation key collisions | -| **o** | `Record` | optional | Object-first translations keyed by object name | +| **o** | `Record` | optional | Object-first translations keyed by object name | | **_globalOptions** | `Record>` | optional | Global picklist option translations keyed by option set name | -| **app** | `Record` | optional | App translations keyed by app name | +| **app** | `Record` | optional | App translations keyed by app name | | **nav** | `Record` | optional | Navigation item translations keyed by nav item name | -| **dashboard** | `Record` | optional | Dashboard translations keyed by dashboard name | -| **reports** | `Record` | optional | Report translations keyed by report name | -| **pages** | `Record` | optional | Page translations keyed by page name | +| **dashboard** | `Record` | optional | Dashboard translations keyed by dashboard name | +| **reports** | `Record` | optional | Report translations keyed by report name | +| **pages** | `Record` | optional | Page translations keyed by page name | | **messages** | `Record` | optional | UI message translations keyed by message ID (supports ICU MessageFormat) | | **validationMessages** | `Record` | optional | Validation error message translations keyed by rule name (supports ICU MessageFormat) | -| **notifications** | `Record` | optional | Global notification translations keyed by notification name | +| **notifications** | `Record` | optional | Global notification translations keyed by notification name | | **errors** | `Record` | optional | Global error message translations keyed by error code | @@ -108,10 +108,10 @@ Translation data for a single object | **label** | `string` | ✅ | Translated singular label | | **pluralLabel** | `string` | optional | Translated plural label | | **description** | `string` | optional | Translated object description | -| **fields** | `Record` | optional | Field-level translations | -| **_views** | `Record` | optional | View translations keyed by view name | -| **_actions** | `Record` | optional | Action translations keyed by action name | -| **_sections** | `Record` | optional | Section translations keyed by section name | +| **fields** | `Record }>` | optional | Field-level translations | +| **_views** | `Record` | optional | View translations keyed by view name | +| **_actions** | `Record }> }>` | optional | Action translations keyed by action name | +| **_sections** | `Record` | optional | Section translations keyed by section name | --- @@ -128,12 +128,12 @@ Object-first aggregated translation node | **pluralLabel** | `string` | optional | Translated plural label | | **description** | `string` | optional | Translated object description | | **helpText** | `string` | optional | Translated help text for the object | -| **fields** | `Record` | optional | Field translations keyed by field name | +| **fields** | `Record }>` | optional | Field translations keyed by field name | | **_options** | `Record>` | optional | Object-scoped picklist option translations keyed by field name | -| **_views** | `Record` | optional | View translations keyed by view name | -| **_sections** | `Record` | optional | Section translations keyed by section name | -| **_actions** | `Record` | optional | Action translations keyed by action name | -| **_notifications** | `Record` | optional | Notification translations keyed by notification name | +| **_views** | `Record` | optional | View translations keyed by view name | +| **_sections** | `Record` | optional | Section translations keyed by section name | +| **_actions** | `Record }> }>` | optional | Action translations keyed by action name | +| **_notifications** | `Record` | optional | Notification translations keyed by notification name | | **_errors** | `Record` | optional | Error message translations keyed by error code | @@ -177,8 +177,8 @@ Aggregated translation coverage result | **redundantKeys** | `integer` | ✅ | Number of redundant translations | | **staleKeys** | `integer` | ✅ | Number of stale translations | | **coveragePercent** | `number` | ✅ | Translation coverage percentage | -| **items** | `Object[]` | ✅ | Detailed diff items | -| **breakdown** | `Object[]` | optional | Per-group coverage breakdown | +| **items** | `{ key: string; status: Enum<'missing' \| 'redundant' \| 'stale'>; objectName?: string; locale: string; … }[]` | ✅ | Detailed diff items | +| **breakdown** | `{ group: string; totalKeys: integer; translatedKeys: integer; coveragePercent: number }[]` | optional | Per-group coverage breakdown | --- @@ -191,15 +191,15 @@ Translation data for objects, apps, and UI messages | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **objects** | `Record` | optional | Object translations keyed by object name | -| **apps** | `Record` | optional | App translations keyed by app name | +| **objects** | `Record }>; … }>` | optional | Object translations keyed by object name | +| **apps** | `Record }>` | optional | App translations keyed by app name | | **messages** | `Record` | optional | UI message translations keyed by message ID | | **validationMessages** | `Record` | optional | Translatable validation error messages keyed by rule name (e.g., `{"discount_limit": "折扣不能超过40%"}`) | -| **globalActions** | `Record` | optional | Global action translations keyed by action name | -| **dashboards** | `Record` | optional | Dashboard translations keyed by dashboard name | -| **settings** | `Record` | optional | Settings manifest translations keyed by namespace | -| **metadataForms** | `Record` | optional | Translations for metadata-type configuration forms keyed by metadata type | -| **settingsCommon** | `Object` | optional | Cross-namespace Settings UI strings | +| **globalActions** | `Record }> }>` | optional | Global action translations keyed by action name | +| **dashboards** | `Record; widgets?: Record }>` | optional | Dashboard translations keyed by dashboard name | +| **settings** | `Record; keys?: Record }>; … }>` | optional | Settings manifest translations keyed by namespace | +| **metadataForms** | `Record; fields?: Record }>` | optional | Translations for metadata-type configuration forms keyed by metadata type | +| **settingsCommon** | `{ sourceLabels?: object }` | optional | Cross-namespace Settings UI strings | --- diff --git a/content/docs/references/system/worker.mdx b/content/docs/references/system/worker.mdx index 85c521be41..fcc53643ca 100644 --- a/content/docs/references/system/worker.mdx +++ b/content/docs/references/system/worker.mdx @@ -94,11 +94,11 @@ const result = BatchProgress.parse(data); | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Queue name (snake_case) | | **concurrency** | `integer` | ✅ | Max concurrent task executions | -| **rateLimit** | `Object` | optional | Rate limit configuration | -| **defaultRetryPolicy** | `Object` | optional | Default retry policy for tasks | +| **rateLimit** | `{ max: integer; duration: integer }` | optional | Rate limit configuration | +| **defaultRetryPolicy** | `{ maxRetries: integer; backoffStrategy: Enum<'fixed' \| 'linear' \| 'exponential'>; initialDelayMs: integer; maxDelayMs: integer; … }` | optional | Default retry policy for tasks | | **deadLetterQueue** | `string` | optional | Dead letter queue name | | **priority** | `integer` | ✅ | Queue priority (lower = higher priority) | -| **autoScale** | `Object` | optional | Auto-scaling configuration | +| **autoScale** | `{ enabled: boolean; minWorkers: integer; maxWorkers: integer; scaleUpThreshold: integer; … }` | optional | Auto-scaling configuration | --- @@ -114,12 +114,12 @@ const result = BatchProgress.parse(data); | **payload** | `any` | ✅ | Task payload data | | **queue** | `string` | ✅ | Queue name | | **priority** | `Enum<'critical' \| 'high' \| 'normal' \| 'low' \| 'background'>` | ✅ | Task priority level | -| **retryPolicy** | `Object` | optional | Retry policy configuration | +| **retryPolicy** | `{ maxRetries: integer; backoffStrategy: Enum<'fixed' \| 'linear' \| 'exponential'>; initialDelayMs: integer; maxDelayMs: integer; … }` | optional | Retry policy configuration | | **timeoutMs** | `integer` | optional | Task timeout in milliseconds | | **scheduledAt** | `string` | optional | ISO 8601 datetime to execute task | | **attempts** | `integer` | ✅ | Number of execution attempts | | **status** | `Enum<'pending' \| 'queued' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'timeout' \| 'dead'>` | ✅ | Current task status | -| **metadata** | `Object` | optional | Task metadata | +| **metadata** | `{ createdAt?: string; updatedAt?: string; createdBy?: string; tags?: string[] }` | optional | Task metadata | --- @@ -133,7 +133,7 @@ const result = BatchProgress.parse(data); | **taskId** | `string` | ✅ | Task identifier | | **status** | `Enum<'pending' \| 'queued' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'timeout' \| 'dead'>` | ✅ | Execution status | | **result** | `any` | optional | Execution result data | -| **error** | `Object` | optional | Error details if failed | +| **error** | `{ message: string; stack?: string; code?: string }` | optional | Error details if failed | | **durationMs** | `integer` | optional | Execution duration in milliseconds | | **startedAt** | `string` | ✅ | When execution started | | **completedAt** | `string` | optional | When execution completed | @@ -200,7 +200,7 @@ const result = BatchProgress.parse(data); | **active** | `integer` | ✅ | Currently active tasks | | **avgExecutionMs** | `number` | optional | Average execution time in milliseconds | | **uptimeMs** | `integer` | ✅ | Worker uptime in milliseconds | -| **queues** | `Record` | optional | Per-queue statistics | +| **queues** | `Record` | optional | Per-queue statistics | --- diff --git a/content/docs/references/ui/action.mdx b/content/docs/references/ui/action.mdx index 2734e0b14c..939fb22a29 100644 --- a/content/docs/references/ui/action.mdx +++ b/content/docs/references/ui/action.mdx @@ -72,9 +72,9 @@ const result = Action.parse(data); | **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`. | +| **body** | `{ language: 'expression'; source: string } \| { language: 'js'; source: string; capabilities?: Enum<'api.read' \| 'api.write' \| 'api.transaction' \| 'crypto.uuid' \| 'crypto.hash' \| 'log'>[]; timeoutMs?: integer; … }` | 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 | +| **params** | `{ name?: string; field?: string; objectOverride?: string; label?: string; … }[]` | 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 | @@ -82,24 +82,24 @@ const result = Action.parse(data); | **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). | +| **resultDialog** | `{ title?: string; description?: string; acknowledge?: string; format?: Enum<'qrcode' \| 'code-list' \| 'secret' \| 'text' \| 'json'>; … }` | optional | Render API response in a one-shot reveal dialog (suppresses successMessage when set). | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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. | +| **disabled** | `boolean \| string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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. | +| **ai** | `{ exposed?: boolean; description?: string; category?: Enum<'data' \| 'action' \| 'flow' \| 'integration' \| 'vector_search' \| 'analytics' \| 'utility'>; paramHints?: Record; … }` | 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. | +| **bodyShape** | `'flat' \| { wrap: string }` | 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 | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -113,7 +113,7 @@ const result = Action.parse(data); | **exposed** | `boolean` | ✅ | Expose this action to AI agents. Requires `description` when true. | | **description** | `string` | optional | LLM-facing description (≥40 chars). Required when exposed. | | **category** | `Enum<'data' \| 'action' \| 'flow' \| 'integration' \| 'vector_search' \| 'analytics' \| 'utility'>` | optional | Tool category override (defaults to "action"). | -| **paramHints** | `Record` | optional | Per-parameter AI hints keyed by param name. | +| **paramHints** | `Record` | optional | Per-parameter AI hints keyed by param name. | | **outputSchema** | `Record` | optional | JSON Schema for the action return value. | | **requiresConfirmation** | `boolean` | optional | Override HITL confirmation for AI invocations. | @@ -147,12 +147,12 @@ const result = Action.parse(data); | **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 | | +| **options** | `{ label: string; value: string }[]` | 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. | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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. | diff --git a/content/docs/references/ui/animation.mdx b/content/docs/references/ui/animation.mdx index adf61c0a3b..7567234107 100644 --- a/content/docs/references/ui/animation.mdx +++ b/content/docs/references/ui/animation.mdx @@ -51,9 +51,9 @@ Component-level animation configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **label** | `string` | optional | Descriptive label for this animation configuration | -| **enter** | `Object` | optional | Enter/mount animation | -| **exit** | `Object` | optional | Exit/unmount animation | -| **hover** | `Object` | optional | Hover state animation | +| **enter** | `{ preset?: Enum<'fade' \| 'slide_up' \| 'slide_down' \| 'slide_left' \| 'slide_right' \| 'scale' \| 'rotate' \| 'flip' \| 'none'>; duration?: number; easing?: Enum<'linear' \| 'ease' \| 'ease_in' \| 'ease_out' \| 'ease_in_out' \| 'spring'>; delay?: number; … }` | optional | Enter/mount animation | +| **exit** | `{ preset?: Enum<'fade' \| 'slide_up' \| 'slide_down' \| 'slide_left' \| 'slide_right' \| 'scale' \| 'rotate' \| 'flip' \| 'none'>; duration?: number; easing?: Enum<'linear' \| 'ease' \| 'ease_in' \| 'ease_out' \| 'ease_in_out' \| 'spring'>; delay?: number; … }` | optional | Exit/unmount animation | +| **hover** | `{ preset?: Enum<'fade' \| 'slide_up' \| 'slide_down' \| 'slide_left' \| 'slide_right' \| 'scale' \| 'rotate' \| 'flip' \| 'none'>; duration?: number; easing?: Enum<'linear' \| 'ease' \| 'ease_in' \| 'ease_out' \| 'ease_in_out' \| 'spring'>; delay?: number; … }` | optional | Hover state animation | | **trigger** | `Enum<'on_mount' \| 'on_unmount' \| 'on_hover' \| 'on_focus' \| 'on_click' \| 'on_scroll' \| 'on_visible'>` | optional | When to trigger the animation | | **reducedMotion** | `Enum<'respect' \| 'disable' \| 'alternative'>` | ✅ | Accessibility: how to handle prefers-reduced-motion | | **ariaLabel** | `string` | optional | Accessible label for screen readers (WAI-ARIA aria-label) | @@ -88,9 +88,9 @@ Top-level motion and animation design configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **label** | `string` | optional | Descriptive label for the motion configuration | -| **defaultTransition** | `Object` | optional | Default transition applied to all animations | -| **pageTransitions** | `Object` | optional | Page navigation transition settings | -| **componentAnimations** | `Record` | optional | Component name to animation configuration mapping | +| **defaultTransition** | `{ preset?: Enum<'fade' \| 'slide_up' \| 'slide_down' \| 'slide_left' \| 'slide_right' \| 'scale' \| 'rotate' \| 'flip' \| 'none'>; duration?: number; easing?: Enum<'linear' \| 'ease' \| 'ease_in' \| 'ease_out' \| 'ease_in_out' \| 'spring'>; delay?: number; … }` | optional | Default transition applied to all animations | +| **pageTransitions** | `{ type: Enum<'fade' \| 'slide_up' \| 'slide_down' \| 'slide_left' \| 'slide_right' \| 'scale' \| 'rotate' \| 'flip' \| 'none'>; duration: number; easing: Enum<'linear' \| 'ease' \| 'ease_in' \| 'ease_out' \| 'ease_in_out' \| 'spring'>; crossFade: boolean }` | optional | Page navigation transition settings | +| **componentAnimations** | `Record` | optional | Component name to animation configuration mapping | | **reducedMotion** | `boolean` | ✅ | When true, respect prefers-reduced-motion and suppress animations globally | | **enabled** | `boolean` | ✅ | Enable or disable all animations globally | diff --git a/content/docs/references/ui/app.mdx b/content/docs/references/ui/app.mdx index 5cefe27efe..1b54fa315a 100644 --- a/content/docs/references/ui/app.mdx +++ b/content/docs/references/ui/app.mdx @@ -54,12 +54,12 @@ const result = ActionNavItem.parse(data); | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **type** | `'action'` | ✅ | | +| **actionDef** | `{ actionName: string; params?: Record }` | ✅ | Action definition to execute when clicked | --- @@ -75,23 +75,23 @@ const result = ActionNavItem.parse(data); | **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 | +| **branding** | `{ primaryColor?: string; logo?: string; favicon?: string }` | 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 | +| **navigation** | `{ id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … }[]` | optional | Full navigation tree for the app sidebar | +| **areas** | `{ id: string; label: string; icon?: string; order?: number; … }[]` | optional | Navigation areas for partitioning navigation by business domain | +| **contextSelectors** | `{ id: string; label: string; icon?: string; optionsSource: 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 | +| **sharing** | `{ enabled?: boolean; publicLink?: string; password?: string; allowedDomains?: string[]; … }` | optional | Public sharing configuration | +| **embed** | `{ enabled?: boolean; allowedOrigins?: string[]; width?: string; height?: string; … }` | optional | Iframe embedding configuration | +| **mobileNavigation** | `{ mode?: Enum<'drawer' \| 'bottom_nav' \| 'hamburger'>; bottomNavItems?: string[] }` | 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. | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes for the application | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -125,7 +125,7 @@ const result = ActionNavItem.parse(data); | **id** | `string` | ✅ | Selector id; selected value is exposed as the nav template var `{}` | | **label** | `string` | ✅ | Dropdown label | | **icon** | `string` | optional | Icon name | -| **optionsSource** | `Object` | ✅ | Option data source | +| **optionsSource** | `{ endpoint: string; valueKey: string; labelKey: string; filter?: { key: string; op: Enum<'eq' \| 'ne' \| 'in' \| 'nin'>; value: string \| string[] }[] }` | ✅ | Option data source | | **includeAll** | `boolean` | ✅ | Prepend an "All" option that clears the scope | | **allValue** | `string` | ✅ | Template value when "All" is selected (empty = no filter) | | **persist** | `Enum<'query' \| 'session' \| 'none'>` | ✅ | Persist selection via URL query, sessionStorage, or not at all | @@ -145,11 +145,11 @@ const result = ActionNavItem.parse(data); | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'component'` | ✅ | | | **componentRef** | `string` | ✅ | Component registry key (e.g. "metadata:directory") | | **params** | `Record` | optional | Props passed to the component | @@ -167,11 +167,11 @@ const result = ActionNavItem.parse(data); | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'dashboard'` | ✅ | | | **dashboardName** | `string` | ✅ | Target dashboard name | @@ -188,11 +188,11 @@ const result = ActionNavItem.parse(data); | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'group'` | ✅ | | | **expanded** | `boolean` | optional | Default expansion state in sidebar | @@ -209,9 +209,9 @@ const result = ActionNavItem.parse(data); | **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. | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **navigation** | `{ id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … }[]` | ✅ | Navigation items within this area | --- @@ -227,7 +227,7 @@ A navigation contribution: a package injecting nav items into an app it does not | **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 | +| **items** | `{ id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … }[]` | ✅ | Navigation items contributed into the target app/group | --- @@ -251,17 +251,17 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'object'` | ✅ | | | **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) | +| **children** | `[NavigationItem](#navigationitem)[]` | optional | Child navigation items (e.g. specific views) | --- @@ -278,11 +278,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'dashboard'` | ✅ | | | **dashboardName** | `string` | ✅ | Target dashboard name | --- @@ -300,11 +300,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'page'` | ✅ | | | **pageName** | `string` | ✅ | Target custom page component name | | **params** | `Record` | optional | Parameters passed to the page context | @@ -323,11 +323,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'url'` | ✅ | | | **url** | `string` | ✅ | Target external URL | | **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | @@ -346,11 +346,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'report'` | ✅ | | | **reportName** | `string` | ✅ | Target report name | --- @@ -368,12 +368,12 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 | +| **type** | `'action'` | ✅ | | +| **actionDef** | `{ actionName: string; params?: Record }` | ✅ | Action definition to execute when clicked | --- @@ -390,11 +390,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'component'` | ✅ | | | **componentRef** | `string` | ✅ | Component registry key (e.g. "metadata:directory") | | **params** | `Record` | optional | Props passed to the component | @@ -413,13 +413,13 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'group'` | ✅ | | | **expanded** | `boolean` | optional | Default expansion state in sidebar | -| **children** | `[#](./#)[]` | ✅ | Child navigation items | +| **children** | `[NavigationItem](#navigationitem)[]` | ✅ | Child navigation items | --- @@ -437,11 +437,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'object'` | ✅ | | | **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}`. | @@ -462,11 +462,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'page'` | ✅ | | | **pageName** | `string` | ✅ | Target custom page component name | | **params** | `Record` | optional | Parameters passed to the page context | @@ -484,11 +484,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'report'` | ✅ | | | **reportName** | `string` | ✅ | Target report name | @@ -505,11 +505,11 @@ This schema accepts one of the following structures: | **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` | +| **visible** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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` | ✅ | | +| **type** | `'url'` | ✅ | | | **url** | `string` | ✅ | Target external URL | | **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | diff --git a/content/docs/references/ui/chart.mdx b/content/docs/references/ui/chart.mdx index 8d2f2555e9..f2c0b07d77 100644 --- a/content/docs/references/ui/chart.mdx +++ b/content/docs/references/ui/chart.mdx @@ -73,16 +73,16 @@ const result = ChartAnnotation.parse(data); | **title** | `string` | optional | Chart title | | **subtitle** | `string` | optional | Chart subtitle | | **description** | `string` | optional | Accessibility description | -| **xAxis** | `Object` | optional | X-Axis configuration | -| **yAxis** | `Object[]` | optional | Y-Axis configuration (support dual axis) | -| **series** | `Object[]` | optional | Defined series configuration | +| **xAxis** | `{ field: string; title?: string; format?: string; min?: number; … }` | optional | X-Axis configuration | +| **yAxis** | `{ field: string; title?: string; format?: string; min?: number; … }[]` | optional | Y-Axis configuration (support dual axis) | +| **series** | `{ name: string; label?: string; type?: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; color?: string; … }[]` | optional | Defined series configuration | | **colors** | `string[] \| Record` | optional | Color palette (string[]) or value→color map (`{ value: color }`) | | **height** | `number` | optional | Fixed height in pixels | | **showLegend** | `boolean` | ✅ | Display legend | | **showDataLabels** | `boolean` | ✅ | Display data labels | -| **annotations** | `Object[]` | optional | | -| **interaction** | `Object` | optional | | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **annotations** | `{ type: Enum<'line' \| 'region'>; axis: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]` | optional | | +| **interaction** | `{ tooltips: boolean; zoom: boolean; brush: boolean; clickAction?: string }` | optional | | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- diff --git a/content/docs/references/ui/component.mdx b/content/docs/references/ui/component.mdx index 539b251007..06a143659b 100644 --- a/content/docs/references/ui/component.mdx +++ b/content/docs/references/ui/component.mdx @@ -32,7 +32,7 @@ const result = AIChatWindowProps.parse(data); | **mode** | `Enum<'float' \| 'sidebar' \| 'inline'>` | ✅ | Display mode for the chat window | | **agentId** | `string` | optional | Specific AI agent to use | | **context** | `Record` | optional | Contextual data to pass to the AI | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -49,7 +49,7 @@ const result = AIChatWindowProps.parse(data); | **icon** | `string` | optional | Icon name (Lucide icon) | | **iconPosition** | `Enum<'left' \| 'right'>` | ✅ | Icon position relative to label | | **disabled** | `boolean` | ✅ | Disable the button | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -65,7 +65,7 @@ const result = AIChatWindowProps.parse(data); | **targetVariable** | `string` | optional | Page variable to store filter state | | **layout** | `Enum<'inline' \| 'dropdown' \| 'sidebar'>` | ✅ | Filter display layout | | **showSearch** | `boolean` | ✅ | Show search input | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -80,8 +80,8 @@ const result = AIChatWindowProps.parse(data); | **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 | +| **onSubmit** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Action expression on form submit (CEL) | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -96,7 +96,7 @@ const result = AIChatWindowProps.parse(data); | **alt** | `string` | optional | Alt text for accessibility | | **fit** | `Enum<'cover' \| 'contain' \| 'fill'>` | ✅ | Image object-fit mode | | **height** | `number` | optional | Fixed height in pixels | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -112,7 +112,7 @@ const result = AIChatWindowProps.parse(data); | **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) | | **detail** | `Enum<'business' \| 'technical'>` | ✅ | Authoring altitude (ADR-0051 §3.4): business collapses technical flow nodes to business steps + approvals. NOT access (cf. book.audience); permission projection is automatic and render-time, never set here | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -126,11 +126,11 @@ const result = AIChatWindowProps.parse(data); | **object** | `string` | ✅ | Source object | | **field** | `string` | optional | Field to aggregate | | **aggregate** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>` | ✅ | Aggregation function | -| **filter** | `[__schema0](./__schema0)` | optional | Filter criteria | +| **filter** | `any` | optional | Filter criteria | | **format** | `Enum<'number' \| 'currency' \| 'percent'>` | optional | Number display format | | **prefix** | `string` | optional | Prefix text (e.g. "$") | | **suffix** | `string` | optional | Suffix text (e.g. "%") | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -144,11 +144,11 @@ const result = AIChatWindowProps.parse(data); | **object** | `string` | ✅ | Object to pick records from | | **displayField** | `string` | ✅ | Field to display as the record label | | **searchFields** | `string[]` | optional | Fields to search against | -| **filter** | `[__schema0](./__schema0)` | optional | Filter criteria for available records | +| **filter** | `any` | optional | Filter criteria for available records | | **multiple** | `boolean` | ✅ | Allow multiple record selection | | **targetVariable** | `string` | optional | Page variable to bind selected record ID(s) | | **placeholder** | `string` | optional | Placeholder text | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -167,7 +167,7 @@ const result = AIChatWindowProps.parse(data); | **disabled** | `boolean` | ✅ | Disable the input | | **description** | `string` | optional | Helper text shown below the input | | **targetVariable** | `string` | optional | Page variable this input writes to. Declarative hint; the live binding resolves via the variable whose `source` equals this component id (see PageVariableSchema). | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -181,7 +181,7 @@ const result = AIChatWindowProps.parse(data); | **content** | `string` | ✅ | Text or Markdown content | | **variant** | `Enum<'heading' \| 'subheading' \| 'body' \| 'caption'>` | ✅ | Text style variant | | **align** | `Enum<'left' \| 'center' \| 'right'>` | ✅ | Text alignment | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -192,9 +192,9 @@ const result = AIChatWindowProps.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **items** | `Object[]` | ✅ | | +| **items** | `{ label: string; icon?: string; collapsed: boolean; children: any[] }[]` | ✅ | | | **allowMultiple** | `boolean` | ✅ | Allow multiple panels to be expanded simultaneously | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -210,7 +210,7 @@ const result = AIChatWindowProps.parse(data); | **actions** | `string[]` | optional | | | **body** | `any[]` | optional | Card content components (slot) | | **footer** | `any[]` | optional | Card footer components (slot) | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -226,7 +226,7 @@ const result = AIChatWindowProps.parse(data); | **icon** | `string` | optional | Icon name | | **breadcrumb** | `boolean` | ✅ | Show breadcrumb | | **actions** | `string[]` | optional | Action IDs to show in header | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -239,8 +239,8 @@ const result = AIChatWindowProps.parse(data); | :--- | :--- | :--- | :--- | | **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | | | **position** | `Enum<'top' \| 'left'>` | optional | | -| **items** | `Object[]` | ✅ | | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **items** | `{ label: string; icon?: string; visibleWhen?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; children: any[] }[]` | ✅ | | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -262,7 +262,7 @@ const result = AIChatWindowProps.parse(data); | **enableReactions** | `boolean` | ✅ | Enable emoji reactions on feed items | | **enableThreading** | `boolean` | ✅ | Enable threaded replies on comments | | **showSubscriptionToggle** | `boolean` | ✅ | Show bell icon for record-level notification subscription | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -277,8 +277,8 @@ const result = AIChatWindowProps.parse(data); | **width** | `string \| number` | optional | Panel width (e.g., "350px", "30%") | | **collapsible** | `boolean` | ✅ | Whether the panel can be collapsed | | **defaultCollapsed** | `boolean` | ✅ | Whether the panel starts collapsed | -| **feed** | `Object` | optional | Embedded activity feed configuration | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **feed** | `{ types?: Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'>[]; filterMode: Enum<'all' \| 'comments_only' \| 'changes_only' \| 'tasks_only'>; showFilterToggle: boolean; limit: integer; … }` | optional | Embedded activity feed configuration | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -293,7 +293,7 @@ const result = AIChatWindowProps.parse(data); | **layout** | `Enum<'auto' \| 'custom'>` | ✅ | Layout mode: auto uses object highlightFields, custom uses explicit sections | | **sections** | `string[]` | optional | Section IDs to show (required when layout is "custom") | | **fields** | `string[]` | optional | Explicit field list to display (optional, overrides highlightFields) | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -334,9 +334,9 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **fields** | `string \| Object[]` | ✅ | Key fields to highlight (1-7 fields max, typically displayed as prominent cards). Each item may be a bare field name or `{name, label?, icon?, type?}` for inline overrides. | +| **fields** | `string \| { name: string; label?: string; icon?: string; type?: string }[]` | ✅ | Key fields to highlight (1-7 fields max, typically displayed as prominent cards). Each item may be a bare field name or `{name, label?, icon?, type?}` for inline overrides. | | **layout** | `Enum<'horizontal' \| 'vertical'>` | ✅ | Layout orientation for highlight fields | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -348,8 +348,8 @@ Type: `string` | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **statusField** | `string` | ✅ | Field name representing the current status/stage | -| **stages** | `Object[]` | optional | Explicit stage definitions (if not using field metadata) | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **stages** | `{ value: string; label: string }[]` | optional | Explicit stage definitions (if not using field metadata) | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -364,14 +364,14 @@ Type: `string` | **relationshipField** | `string` | ✅ | Field on related object that points to this record (e.g., "account_id") | | **relationshipValueField** | `string` | ✅ | Parent-record field whose value relationshipField stores (default 'id'; e.g. 'name' for name-keyed junctions). | | **columns** | `string[]` | optional | Fields to display in the related list. Optional: when omitted, columns derive from the related object's highlightFields / default list columns (a related list is just another surface that lists that object). Override chain: child highlightFields → field-level relatedListColumns → this inline list. | -| **sort** | `string \| Object[]` | optional | Sort order for related records | +| **sort** | `string \| { field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sort order for related records | | **limit** | `integer` | ✅ | Number of records to display initially | -| **filter** | `Object[]` | optional | Additional filter criteria for related records | +| **filter** | `{ field: string; operator: string; value?: string \| number \| boolean \| null \| string \| number[] }[]` | optional | Additional filter criteria for related records | | **title** | `string` | optional | Custom title for the related list | | **showViewAll** | `boolean` | ✅ | Show "View All" link to see all related records | | **actions** | `string[]` | optional | Action IDs available for related records | -| **add** | `Object` | optional | Add-existing-via-picker config (generic m2m/junction assignment). | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **add** | `{ picker: object; linkField?: string; label?: string }` | optional | Add-existing-via-picker config (generic m2m/junction assignment). | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx index 27e99be4a9..082284608c 100644 --- a/content/docs/references/ui/dashboard.mdx +++ b/content/docs/references/ui/dashboard.mdx @@ -32,16 +32,16 @@ const result = Dashboard.parse(data); | **name** | `string` | ✅ | Dashboard unique name | | **label** | `string` | ✅ | Dashboard label | | **description** | `string` | optional | Dashboard description | -| **header** | `Object` | optional | Dashboard header configuration | -| **widgets** | `Object[]` | ✅ | Widgets to display | +| **header** | `{ showTitle: boolean; showDescription: boolean; actions?: { label: string; actionUrl: string; actionType?: Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>; icon?: string }[] }` | optional | Dashboard header configuration | +| **widgets** | `{ id: string; title?: string; description?: string; type: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; … }[]` | ✅ | Widgets to display | | **columns** | `integer` | optional | Number of grid columns (default 12) | | **gap** | `integer` | optional | Grid gap in Tailwind spacing units | | **refreshInterval** | `number` | optional | Auto-refresh interval in seconds | -| **dateRange** | `Object` | optional | Global dashboard date range filter configuration | -| **globalFilters** | `Object[]` | optional | Global filters that apply to all widgets in the dashboard | -| **aria** | `Object` | optional | ARIA accessibility attributes | -| **performance** | `Object` | optional | Performance optimization settings | -| **protection** | `Object` | optional | Package author protection block — lock policy for this dashboard. | +| **dateRange** | `{ field?: string; defaultRange: Enum<'today' \| 'yesterday' \| 'this_week' \| 'last_week' \| 'this_month' \| 'last_month' \| 'this_quarter' \| 'last_quarter' \| 'this_year' \| 'last_year' \| 'last_7_days' \| 'last_30_days' \| 'last_90_days' \| 'custom'>; allowCustomRange: boolean }` | optional | Global dashboard date range filter configuration | +| **globalFilters** | `{ name?: string; field: string; label?: string; type?: Enum<'text' \| 'select' \| 'date' \| 'number' \| 'lookup'>; … }[]` | optional | Global filters that apply to all widgets in the dashboard | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | +| **performance** | `{ lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' \| 'cache-first' \| 'network-first' \| 'stale-while-revalidate'>; prefetch?: boolean; … }` | optional | Performance optimization settings | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -63,7 +63,7 @@ Dashboard header configuration | :--- | :--- | :--- | :--- | | **showTitle** | `boolean` | ✅ | Show dashboard title in header | | **showDescription** | `boolean` | ✅ | Show dashboard description in header | -| **actions** | `Object[]` | optional | Header action buttons | +| **actions** | `{ label: string; actionUrl: string; actionType?: Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>; icon?: string }[]` | optional | Header action buttons | --- @@ -94,24 +94,24 @@ Dashboard header action | **title** | `string` | optional | Widget title | | **description** | `string` | optional | Widget description text below the header | | **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>` | ✅ | Visualization type | -| **chartConfig** | `Object` | optional | Chart visualization configuration | +| **chartConfig** | `{ type: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; title?: string; subtitle?: string; description?: string; … }` | optional | Chart visualization configuration | | **colorVariant** | `Enum<'default' \| 'blue' \| 'teal' \| 'orange' \| 'purple' \| 'success' \| 'warning' \| 'danger'>` | optional | Widget color variant for theming | | **requiresObject** | `string` | optional | Hide the widget unless the named object is registered | | **requiresService** | `string` | optional | Hide the widget unless the named kernel service is registered | | **actionUrl** | `string` | optional | URL or target for the widget action button | | **actionType** | `Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>` | optional | Type of action for the widget action button | | **actionIcon** | `string` | optional | Icon identifier for the widget action button | -| **filter** | `[__schema0](./__schema0)` | optional | Presentation-scope filter (runtimeFilter) | -| **compareTo** | `string \| string \| Object` | optional | Period-over-period comparison window | +| **filter** | `any` | optional | Presentation-scope filter (runtimeFilter) | +| **compareTo** | `'previousPeriod' \| 'previousYear' \| { offset: string }` | optional | Period-over-period comparison window | | **dataset** | `string` | ✅ | Dataset name to bind (ADR-0021) | | **dimensions** | `string[]` | optional | Dimension names — X/group/split | | **values** | `string[]` | ✅ | Measure names — Y (at least one) | -| **layout** | `Object` | optional | Grid layout position (auto-flowed when omitted) | +| **layout** | `{ x: number; y: number; w: number; h: number }` | optional | Grid layout position (auto-flowed when omitted) | | **options** | `any` | optional | Widget specific configuration | -| **filterBindings** | `Record` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out | +| **filterBindings** | `Record` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out | | **suppressWarnings** | `string[]` | optional | Build diagnostic rule ids suppressed on this widget | -| **responsive** | `Object` | optional | Responsive layout configuration | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive layout configuration | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -126,8 +126,8 @@ Dashboard header action | **field** | `string` | ✅ | Field name to filter on | | **label** | `string` | optional | Display label for the filter | | **type** | `Enum<'text' \| 'select' \| 'date' \| 'number' \| 'lookup'>` | optional | Filter input type | -| **options** | `Object[]` | optional | Static filter options | -| **optionsFrom** | `Object` | optional | Dynamic filter options from object | +| **options** | `{ value: string \| number \| boolean; label: string }[]` | optional | Static filter options | +| **optionsFrom** | `{ object: string; valueField: string; labelField: string; filter?: any }` | optional | Dynamic filter options from object | | **defaultValue** | `string \| number \| boolean` | optional | Default filter value | | **scope** | `Enum<'dashboard' \| 'widget'>` | ✅ | Filter application scope | | **targetWidgets** | `string[]` | optional | Widget IDs to apply this filter to | @@ -146,7 +146,7 @@ Dynamic filter options from object | **object** | `string` | ✅ | Source object name | | **valueField** | `string` | ✅ | Field to use as option value | | **labelField** | `string` | ✅ | Field to use as option label | -| **filter** | `[__schema0](./__schema0)` | optional | Filter to apply to source object | +| **filter** | `any` | optional | Filter to apply to source object | --- diff --git a/content/docs/references/ui/dataset.mdx b/content/docs/references/ui/dataset.mdx index 235afe3b46..eb1ae05142 100644 --- a/content/docs/references/ui/dataset.mdx +++ b/content/docs/references/ui/dataset.mdx @@ -35,7 +35,7 @@ vocabulary (LookML / dbt / Cube / PowerBI). The Zod export identifiers are do not clash with the Cube layer's `DimensionSchema` / `MetricSchema` in -`data/analytics.zod.ts` while the two layers coexist (Phase 1). The Cube +`[data/analytics.zod.ts](/docs/references/data/analytics)` while the two layers coexist (Phase 1). The Cube layer is absorbed/retired in a later phase (D-A). @@ -66,10 +66,10 @@ const result = Dataset.parse(data); | **description** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | | **object** | `string` | ✅ | Base object name | | **include** | `string[]` | optional | Relationship names/paths to join (derived from object graph; max 3 hops) | -| **filter** | `[__schema0](./__schema0)` | optional | Intrinsic dataset scope filter | -| **dimensions** | `Object[]` | ✅ | Groupable axes | -| **measures** | `Object[]` | ✅ | Aggregatable values | -| **protection** | `Object` | optional | Package author protection block — lock policy for this dataset. | +| **filter** | `any` | optional | Intrinsic dataset scope filter | +| **dimensions** | `{ name: string; label?: string; field: string; type?: Enum<'string' \| 'number' \| 'date' \| 'boolean' \| 'lookup'>; … }[]` | ✅ | Groupable axes | +| **measures** | `{ name: string; label?: string; aggregate?: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; … }[]` | ✅ | Aggregatable values | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -106,11 +106,11 @@ const result = Dataset.parse(data); | **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | | **aggregate** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>` | optional | Aggregation (sum/avg/count/...); omit when `derived` is set | | **field** | `string` | optional | Aggregated field; optional for count(*) | -| **filter** | `[__schema0](./__schema0)` | optional | | +| **filter** | `any` | optional | | | **format** | `string` | optional | | | **currency** | `string` | optional | Display currency code (ISO 4217) | | **certified** | `boolean` | ✅ | Blessed metric (governance checkpoint) | -| **derived** | `Object` | optional | | +| **derived** | `{ op: Enum<'ratio' \| 'sum' \| 'difference' \| 'product'>; of: string[] }` | optional | | --- diff --git a/content/docs/references/ui/dnd.mdx b/content/docs/references/ui/dnd.mdx index 05fc8eb4d2..9a0061e12c 100644 --- a/content/docs/references/ui/dnd.mdx +++ b/content/docs/references/ui/dnd.mdx @@ -34,8 +34,8 @@ Drag and drop interaction configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable drag and drop | -| **dragItem** | `Object` | optional | Configuration for draggable item | -| **dropZone** | `Object` | optional | Configuration for drop target | +| **dragItem** | `{ type: string; label?: string; handle: Enum<'element' \| 'handle' \| 'grip_icon'>; constraint?: object; … }` | optional | Configuration for draggable item | +| **dropZone** | `{ label?: string; accept: string[]; maxItems?: number; highlightOnDragOver: boolean; … }` | optional | Configuration for drop target | | **sortable** | `boolean` | ✅ | Enable sortable list behavior | | **autoScroll** | `boolean` | ✅ | Auto-scroll during drag near edges | | **touchDelay** | `number` | ✅ | Delay in ms before drag starts on touch devices | @@ -82,7 +82,7 @@ Draggable item configuration | **type** | `string` | ✅ | Drag item type identifier for matching with drop zones | | **label** | `string` | optional | Accessible label describing the draggable item | | **handle** | `Enum<'element' \| 'handle' \| 'grip_icon'>` | ✅ | How to initiate drag | -| **constraint** | `Object` | optional | Drag movement constraints | +| **constraint** | `{ axis: Enum<'x' \| 'y' \| 'both'>; bounds: Enum<'parent' \| 'viewport' \| 'none'>; grid?: any[] }` | optional | Drag movement constraints | | **preview** | `Enum<'element' \| 'custom' \| 'none'>` | ✅ | Drag preview type | | **disabled** | `boolean` | ✅ | Disable dragging | | **ariaLabel** | `string` | optional | Accessible label for screen readers (WAI-ARIA aria-label) | diff --git a/content/docs/references/ui/i18n.mdx b/content/docs/references/ui/i18n.mdx index 3a79b31caf..e69df5ce08 100644 --- a/content/docs/references/ui/i18n.mdx +++ b/content/docs/references/ui/i18n.mdx @@ -99,8 +99,8 @@ Locale configuration | **code** | `string` | ✅ | BCP 47 language code (e.g., "en-US", "zh-CN") | | **fallbackChain** | `string[]` | optional | Fallback language codes in priority order (e.g., ["zh-TW", "en"]) | | **direction** | `Enum<'ltr' \| 'rtl'>` | ✅ | Text direction: left-to-right or right-to-left | -| **numberFormat** | `Object` | optional | Default number formatting rules | -| **dateFormat** | `Object` | optional | Default date/time formatting rules | +| **numberFormat** | `{ style: Enum<'decimal' \| 'currency' \| 'percent' \| 'unit'>; currency?: string; unit?: string; minimumFractionDigits?: number; … }` | optional | Default number formatting rules | +| **dateFormat** | `{ dateStyle?: Enum<'full' \| 'long' \| 'medium' \| 'short'>; timeStyle?: Enum<'full' \| 'long' \| 'medium' \| 'short'>; timeZone?: string; hour12?: boolean }` | optional | Default date/time formatting rules | --- diff --git a/content/docs/references/ui/keyboard.mdx b/content/docs/references/ui/keyboard.mdx index b090fe6679..1728c03a60 100644 --- a/content/docs/references/ui/keyboard.mdx +++ b/content/docs/references/ui/keyboard.mdx @@ -36,7 +36,7 @@ Focus and tab navigation management | **tabOrder** | `Enum<'auto' \| 'manual'>` | ✅ | Tab order strategy: auto (DOM order) or manual (explicit tabIndex) | | **skipLinks** | `boolean` | ✅ | Provide skip-to-content navigation links | | **focusVisible** | `boolean` | ✅ | Show visible focus indicators for keyboard users | -| **focusTrap** | `Object` | optional | Focus trap settings | +| **focusTrap** | `{ enabled: boolean; initialFocus?: string; returnFocus: boolean; escapeDeactivates: boolean }` | optional | Focus trap settings | | **arrowNavigation** | `boolean` | ✅ | Enable arrow key navigation between focusable items | @@ -66,8 +66,8 @@ Keyboard navigation and shortcut configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **shortcuts** | `Object[]` | optional | Registered keyboard shortcuts | -| **focusManagement** | `Object` | optional | Focus and tab order management | +| **shortcuts** | `{ key: string; action: string; description?: string; scope: Enum<'global' \| 'view' \| 'form' \| 'modal' \| 'list'> }[]` | optional | Registered keyboard shortcuts | +| **focusManagement** | `{ tabOrder: Enum<'auto' \| 'manual'>; skipLinks: boolean; focusVisible: boolean; focusTrap?: object; … }` | optional | Focus and tab order management | | **rovingTabindex** | `boolean` | ✅ | Enable roving tabindex pattern for composite widgets | | **ariaLabel** | `string` | optional | Accessible label for screen readers (WAI-ARIA aria-label) | | **ariaDescribedBy** | `string` | optional | ID of element providing additional description (WAI-ARIA aria-describedby) | diff --git a/content/docs/references/ui/notification.mdx b/content/docs/references/ui/notification.mdx index 6fa16f4e17..d5c069d56e 100644 --- a/content/docs/references/ui/notification.mdx +++ b/content/docs/references/ui/notification.mdx @@ -40,7 +40,7 @@ Notification instance definition | **icon** | `string` | optional | Icon name override | | **duration** | `number` | optional | Auto-dismiss duration in ms, omit for persistent | | **dismissible** | `boolean` | ✅ | Allow user to dismiss the notification | -| **actions** | `Object[]` | optional | Action buttons | +| **actions** | `{ label: string; action: string; variant: Enum<'primary' \| 'secondary' \| 'link'> }[]` | optional | Action buttons | | **position** | `Enum<'top_left' \| 'top_center' \| 'top_right' \| 'bottom_left' \| 'bottom_center' \| 'bottom_right'>` | optional | Override default position | | **ariaLabel** | `string` | optional | Accessible label for screen readers (WAI-ARIA aria-label) | | **ariaDescribedBy** | `string` | optional | ID of element providing additional description (WAI-ARIA aria-describedby) | diff --git a/content/docs/references/ui/offline.mdx b/content/docs/references/ui/offline.mdx index 8db809406a..a6232f4f1e 100644 --- a/content/docs/references/ui/offline.mdx +++ b/content/docs/references/ui/offline.mdx @@ -78,8 +78,8 @@ Offline support configuration | :--- | :--- | :--- | :--- | | **enabled** | `boolean` | ✅ | Enable offline support | | **strategy** | `Enum<'cache_first' \| 'network_first' \| 'stale_while_revalidate' \| 'network_only' \| 'cache_only'>` | ✅ | Default offline fetch strategy | -| **cache** | `Object` | optional | Cache settings for offline data | -| **sync** | `Object` | optional | Sync settings for offline mutations | +| **cache** | `{ maxSize?: number; ttl?: number; persistStorage: Enum<'indexeddb' \| 'localstorage' \| 'sqlite'>; evictionPolicy: Enum<'lru' \| 'lfu' \| 'fifo'> }` | optional | Cache settings for offline data | +| **sync** | `{ strategy: Enum<'cache_first' \| 'network_first' \| 'stale_while_revalidate' \| 'network_only' \| 'cache_only'>; conflictResolution: Enum<'client_wins' \| 'server_wins' \| 'manual' \| 'last_write_wins'>; retryInterval?: number; maxRetries?: number; … }` | optional | Sync settings for offline mutations | | **offlineIndicator** | `boolean` | ✅ | Show a visual indicator when offline | | **offlineMessage** | `string` | optional | Customizable offline status message shown to users | | **queueMaxSize** | `number` | optional | Maximum number of queued offline mutations | diff --git a/content/docs/references/ui/page.mdx b/content/docs/references/ui/page.mdx index c9cc413060..1d9afd6bea 100644 --- a/content/docs/references/ui/page.mdx +++ b/content/docs/references/ui/page.mdx @@ -33,8 +33,8 @@ const result = ElementDataSource.parse(data); | :--- | :--- | :--- | :--- | | **object** | `string` | ✅ | Object to query | | **view** | `string` | optional | Named view to apply | -| **filter** | `[__schema0](./__schema0)` | optional | Additional filter criteria | -| **sort** | `Object[]` | optional | Sort order | +| **filter** | `any` | optional | Additional filter criteria | +| **sort** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sort order | | **limit** | `integer` | optional | Max records to display | @@ -49,15 +49,15 @@ Interface-level page configuration (Airtable parity) | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **source** | `string` | optional | Source object name for the page | -| **columns** | `string[] \| Object[]` | optional | Columns shown by the page. Blank = all object fields. Defined directly on the page (no view inheritance). | -| **sort** | `Object[]` | optional | Default sort order for the page, defined directly on the page. | -| **filterBy** | `Object[]` | optional | Always-on page filter (base filter). | +| **columns** | `string[] \| { field: string; label?: string; width?: number; align?: Enum<'left' \| 'center' \| 'right'>; … }[]` | optional | Columns shown by the page. Blank = all object fields. Defined directly on the page (no view inheritance). | +| **sort** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Default sort order for the page, defined directly on the page. | +| **filterBy** | `{ field: string; operator: string; value?: string \| number \| boolean \| null \| string \| number[] }[]` | optional | Always-on page filter (base filter). | | **levels** | `integer` | optional | Number of hierarchy levels to display | | **sourceView** | `string` | optional | @deprecated Legacy named-view inheritance. Define columns/sort/filterBy on the page instead. | -| **appearance** | `Object` | optional | Appearance and visualization configuration | -| **userFilters** | `Object` | optional | End-user quick-filter bar for this page (overrides the source view's userFilters) | -| **userActions** | `Object` | optional | User action toggles | -| **addRecord** | `Object` | optional | Add record entry point configuration | +| **appearance** | `{ showDescription: boolean; allowedVisualizations?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>[] }` | optional | Appearance and visualization configuration | +| **userFilters** | `{ element: Enum<'dropdown' \| 'tabs' \| 'toggle'>; fields?: { field: string; label?: string; type?: Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>; options?: { value: string \| number \| boolean; label: string; color?: string }[]; … }[]; tabs?: { name: string; label?: string; icon?: string; view?: string; … }[]; showAllRecords?: boolean }` | optional | End-user quick-filter bar for this page (overrides the source view's userFilters) | +| **userActions** | `{ sort: boolean; search: boolean; filter: boolean; rowHeight: boolean; … }` | optional | User action toggles | +| **addRecord** | `{ enabled: boolean; position: Enum<'top' \| 'bottom' \| 'both'>; mode: Enum<'inline' \| 'form' \| 'modal'>; formView?: string }` | 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 | | **showRecordCount** | `boolean` | optional | Show record count at page bottom | @@ -77,16 +77,16 @@ Interface-level page configuration (Airtable parity) | **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). | +| **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array' \| 'record_id'>; defaultValue?: any; source?: string }[]` | 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. | +| **regions** | `{ name: string; width?: Enum<'small' \| 'medium' \| 'large' \| 'full'>; components: { 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; id?: string; label?: string; properties?: Record; … }[] }[]` | 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 | +| **interfaceConfig** | `{ source?: string; columns?: string[] \| { field: string; label?: string; width?: number; align?: Enum<'left' \| 'center' \| 'right'>; … }[]; sort?: { field: string; order: Enum<'asc' \| 'desc'> }[]; filterBy?: { field: string; operator: string; value?: string \| number \| boolean \| null \| string \| number[] }[]; … }` | optional | Interface-level page configuration (for Airtable-style interface pages) | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | 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 | +| **slots** | `{ header?: { 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; id?: string; label?: string; properties?: Record; … } \| { 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; id?: string; label?: string; properties?: Record; … }[]; actions?: { 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; id?: string; label?: string; properties?: Record; … } \| { 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; id?: string; label?: string; properties?: Record; … }[]; alerts?: { 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; id?: string; label?: string; properties?: Record; … } \| { 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; id?: string; label?: string; properties?: Record; … }[]; highlights?: { 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; id?: string; label?: string; properties?: Record; … } \| { 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; id?: string; label?: string; properties?: Record; … }[]; … }` | 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) | @@ -106,12 +106,12 @@ Interface-level page configuration (Airtable parity) | **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 | +| **responsiveStyles** | `{ large?: Record; medium?: Record; small?: Record; xsmall?: Record }` | optional | Per-breakpoint scoped style maps (ADR-0065) | +| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — component rendered only when TRUE. Binds `record`, `current_user`, `page.`. e.g. "page.selectedProjectId != ''" | +| **visibility** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | [DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Normalized to `visibleWhen` at parse. | +| **dataSource** | `{ object: string; view?: string; filter?: any; sort?: { field: string; order: Enum<'asc' \| 'desc'> }[]; … }` | optional | Per-element data binding for multi-object pages | +| **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive layout configuration | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | --- @@ -166,7 +166,7 @@ Interface-level page configuration (Airtable parity) | :--- | :--- | :--- | :--- | | **name** | `string` | ✅ | Region name (e.g. "sidebar", "main", "header") | | **width** | `Enum<'small' \| 'medium' \| 'large' \| 'full'>` | optional | | -| **components** | `Object[]` | ✅ | Components in this region | +| **components** | `{ 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; id?: string; label?: string; properties?: Record; … }[]` | ✅ | Components in this region | --- diff --git a/content/docs/references/ui/portal.mdx b/content/docs/references/ui/portal.mdx index a655a49d4e..85b7da66ee 100644 --- a/content/docs/references/ui/portal.mdx +++ b/content/docs/references/ui/portal.mdx @@ -89,22 +89,22 @@ const result = Portal.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **kind** | `string` | ✅ | Metadata kind discriminator. | +| **kind** | `'portal'` | ✅ | Metadata kind discriminator. | | **id** | `string` | ✅ | Portal unique machine name (lowercase snake_case). | | **label** | `string` | ✅ | Portal display label. | | **description** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) | | **routePrefix** | `string` | ✅ | Root URL path for the portal (must start with "/"). | | **domain** | `string` | optional | Optional vanity domain (e.g. "support.acme.com"). | -| **layout** | `string \| string \| string \| string` | ✅ | Shell layout for the portal. | -| **theme** | `Object` | optional | Theme tokens. | -| **locale** | `string \| string` | ✅ | Locale resolution strategy. | -| **seo** | `Object` | optional | | -| **authMode** | `string \| string \| string \| string` | ✅ | Authentication mode for the portal. | +| **layout** | `'console' \| 'minimal' \| 'embedded' \| string` | ✅ | Shell layout for the portal. | +| **theme** | `{ primaryColor?: string; accentColor?: string; backgroundColor?: string; surfaceColor?: string; … }` | optional | Theme tokens. | +| **locale** | `'auto' \| string` | ✅ | Locale resolution strategy. | +| **seo** | `{ title?: string; description?: string; openGraphImage?: string; robots: Enum<'index' \| 'noindex'> }` | optional | | +| **authMode** | `'authenticated' \| 'magic-link' \| 'anonymous' \| string` | ✅ | Authentication mode for the portal. | | **positions** | `string[]` | ✅ | Positions admitted to the portal. | | **profiles** | `any` | optional | | -| **anonymousEntry** | `Object` | optional | | -| **navigation** | `Object \| Object \| Object \| Object[]` | ✅ | Flat list of portal entry points (references to existing metadata). | -| **defaultRoute** | `Object` | optional | Landing surface when the user hits the portal root. | +| **anonymousEntry** | `{ routes: { path: string; viewRef?: string; actionRef?: string; rateLimit?: object; … }[]; defaultRateLimit?: object }` | optional | | +| **navigation** | `{ id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … } \| { id: string; label: string; icon?: string; order?: number; … }[]` | ✅ | Flat list of portal entry points (references to existing metadata). | +| **defaultRoute** | `{ viewRef?: string; actionRef?: string; dashboardName?: string }` | optional | Landing surface when the user hits the portal root. | | **embeddable** | `boolean` | ✅ | | | **allowedEmbedOrigins** | `string[]` | optional | | | **active** | `boolean` | ✅ | | @@ -123,7 +123,7 @@ const result = Portal.parse(data); | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'action'` | ✅ | | | **actionRef** | `string` | ✅ | Reference to an existing action, e.g. "helpdesk_ticket.create". | @@ -135,8 +135,8 @@ const result = Portal.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **routes** | `Object[]` | ✅ | List of anonymous-accessible routes. | -| **defaultRateLimit** | `Object` | optional | | +| **routes** | `{ path: string; viewRef?: string; actionRef?: string; rateLimit?: object; … }[]` | ✅ | List of anonymous-accessible routes. | +| **defaultRateLimit** | `{ rule: string; scope: Enum<'ip' \| 'tenant' \| 'route'> }` | optional | | --- @@ -150,7 +150,7 @@ const result = Portal.parse(data); | **path** | `string` | ✅ | Path within the portal, e.g. "/submit" or "/kb". | | **viewRef** | `string` | optional | Reference to a public view (read-only). | | **actionRef** | `string` | optional | Reference to an action to perform anonymously (mutation). | -| **rateLimit** | `Object` | optional | Rate-limit for anonymous traffic on this route. | +| **rateLimit** | `{ rule: string; scope: Enum<'ip' \| 'tenant' \| 'route'> }` | optional | Rate-limit for anonymous traffic on this route. | | **captcha** | `boolean` | ✅ | Require CAPTCHA / proof-of-work challenge before invoking. | | **bindIdentityFromField** | `string` | optional | Field name on the action input to use for magic-link identity binding (e.g. "customer_email"). | @@ -165,19 +165,19 @@ This schema accepts one of the following structures: #### Option 1 -Type: `string` +Type: `'authenticated'` --- #### Option 2 -Type: `string` +Type: `'magic-link'` --- #### Option 3 -Type: `string` +Type: `'anonymous'` --- @@ -201,7 +201,7 @@ Type: `string` | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'dashboard'` | ✅ | | | **dashboardName** | `string` | ✅ | Existing dashboard id. | @@ -215,19 +215,19 @@ This schema accepts one of the following structures: #### Option 1 -Type: `string` +Type: `'console'` --- #### Option 2 -Type: `string` +Type: `'minimal'` --- #### Option 3 -Type: `string` +Type: `'embedded'` --- @@ -259,7 +259,7 @@ This schema accepts one of the following structures: | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'view'` | ✅ | | | **viewRef** | `string` | ✅ | Reference to an existing view, e.g. "helpdesk_ticket.list.my_tickets". | --- @@ -277,7 +277,7 @@ This schema accepts one of the following structures: | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'action'` | ✅ | | | **actionRef** | `string` | ✅ | Reference to an existing action, e.g. "helpdesk_ticket.create". | --- @@ -295,7 +295,7 @@ This schema accepts one of the following structures: | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'dashboard'` | ✅ | | | **dashboardName** | `string` | ✅ | Existing dashboard id. | --- @@ -313,7 +313,7 @@ This schema accepts one of the following structures: | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'url'` | ✅ | | | **url** | `string` | ✅ | Absolute or root-relative URL. | | **target** | `Enum<'_self' \| '_blank'>` | ✅ | | @@ -378,7 +378,7 @@ This schema accepts one of the following structures: | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'url'` | ✅ | | | **url** | `string` | ✅ | Absolute or root-relative URL. | | **target** | `Enum<'_self' \| '_blank'>` | ✅ | | @@ -396,7 +396,7 @@ This schema accepts one of the following structures: | **icon** | `string` | optional | Icon name (Lucide). | | **order** | `number` | optional | Sort order; lower appears first. | | **badge** | `string \| number` | optional | Optional badge (e.g. unread count). | -| **type** | `string` | ✅ | | +| **type** | `'view'` | ✅ | | | **viewRef** | `string` | ✅ | Reference to an existing view, e.g. "helpdesk_ticket.list.my_tickets". | diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx index ab8e9d2417..dfbfc9e3f3 100644 --- a/content/docs/references/ui/report.mdx +++ b/content/docs/references/ui/report.mdx @@ -33,12 +33,12 @@ const result = JoinedReportBlock.parse(data); | **label** | `string` | optional | 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) | | **type** | `Enum<'tabular' \| 'summary' \| 'matrix'>` | ✅ | | -| **chart** | `Object` | optional | | +| **chart** | `{ type: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; title?: string; subtitle?: string; description?: string; … }` | optional | | | **dataset** | `string` | optional | Dataset name to bind (ADR-0021) | | **rows** | `string[]` | optional | Dimension names down (dataset-bound) | | **columns** | `string[]` | optional | Dimension names across (matrix, dataset-bound) | | **values** | `string[]` | optional | Measure names to show (dataset-bound) | -| **runtimeFilter** | `[__schema0](./__schema0)` | optional | Render-time scope filter (dataset-bound) | +| **runtimeFilter** | `any` | optional | Render-time scope filter (dataset-bound) | --- @@ -57,13 +57,13 @@ const result = JoinedReportBlock.parse(data); | **rows** | `string[]` | optional | Dimension names down | | **columns** | `string[]` | optional | Dimension names across (matrix) | | **values** | `string[]` | optional | Measure names to show | -| **runtimeFilter** | `[__schema0](./__schema0)` | optional | Render-time scope filter | +| **runtimeFilter** | `any` | optional | Render-time scope filter | | **drilldown** | `boolean` | ✅ | Click-through to underlying records | -| **chart** | `Object` | optional | Embedded chart configuration | -| **aria** | `Object` | optional | ARIA accessibility attributes | -| **performance** | `Object` | optional | Performance optimization settings | -| **blocks** | `Object[]` | optional | Sub-reports for type=joined | -| **protection** | `Object` | optional | Package author protection block — lock policy for this report. | +| **chart** | `{ type: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; title?: string; subtitle?: string; description?: string; … }` | optional | Embedded chart configuration | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | +| **performance** | `{ lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' \| 'cache-first' \| 'network-first' \| 'stale-while-revalidate'>; prefetch?: boolean; … }` | optional | Performance optimization settings | +| **blocks** | `{ name: string; label?: string; description?: string; type: Enum<'tabular' \| 'summary' \| 'matrix'>; … }[]` | optional | Sub-reports for type=joined | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -87,14 +87,14 @@ const result = JoinedReportBlock.parse(data); | **description** | `string` | optional | Accessibility description | | **xAxis** | `string` | ✅ | Grouping field for X-Axis | | **yAxis** | `string` | ✅ | Summary field for Y-Axis | -| **series** | `Object[]` | optional | Defined series configuration | +| **series** | `{ name: string; label?: string; type?: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>; color?: string; … }[]` | optional | Defined series configuration | | **colors** | `string[] \| Record` | optional | Color palette (string[]) or value→color map (`{ value: color }`) | | **height** | `number` | optional | Fixed height in pixels | | **showLegend** | `boolean` | ✅ | Display legend | | **showDataLabels** | `boolean` | ✅ | Display data labels | -| **annotations** | `Object[]` | optional | | -| **interaction** | `Object` | optional | | -| **aria** | `Object` | optional | ARIA accessibility attributes | +| **annotations** | `{ type: Enum<'line' \| 'region'>; axis: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]` | optional | | +| **interaction** | `{ tooltips: boolean; zoom: boolean; brush: boolean; clickAction?: string }` | optional | | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | | **groupBy** | `string` | optional | Additional grouping field | @@ -109,7 +109,7 @@ const result = JoinedReportBlock.parse(data); | **field** | `string` | ✅ | Field name | | **label** | `string` | optional | Override label | | **aggregate** | `Enum<'sum' \| 'avg' \| 'max' \| 'min' \| 'count' \| 'unique'>` | optional | Aggregation function | -| **responsive** | `Object` | optional | Responsive visibility for this column | +| **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive visibility for this column | --- diff --git a/content/docs/references/ui/responsive.mdx b/content/docs/references/ui/responsive.mdx index 6ff01d2bd6..e3ef904700 100644 --- a/content/docs/references/ui/responsive.mdx +++ b/content/docs/references/ui/responsive.mdx @@ -84,7 +84,7 @@ Performance optimization configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **lazyLoad** | `boolean` | optional | Enable lazy loading (defer rendering until visible) | -| **virtualScroll** | `Object` | optional | Virtual scrolling configuration | +| **virtualScroll** | `{ enabled: boolean; itemHeight?: number; overscan?: number }` | optional | Virtual scrolling configuration | | **cacheStrategy** | `Enum<'none' \| 'cache-first' \| 'network-first' \| 'stale-while-revalidate'>` | optional | Client-side data caching strategy | | **prefetch** | `boolean` | optional | Prefetch data before component is visible | | **pageSize** | `number` | optional | Number of items per page for pagination | @@ -103,8 +103,8 @@ Responsive layout configuration | :--- | :--- | :--- | :--- | | **breakpoint** | `Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>` | optional | Minimum breakpoint for visibility | | **hiddenOn** | `Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]` | optional | Hide on these breakpoints | -| **columns** | `Object` | optional | Grid columns per breakpoint | -| **order** | `Object` | optional | Display order per breakpoint | +| **columns** | `{ xs?: number; sm?: number; md?: number; lg?: number; … }` | optional | Grid columns per breakpoint | +| **order** | `{ xs?: number; sm?: number; md?: number; lg?: number; … }` | optional | Display order per breakpoint | --- diff --git a/content/docs/references/ui/theme.mdx b/content/docs/references/ui/theme.mdx index 9ebe78fce0..31041c2df6 100644 --- a/content/docs/references/ui/theme.mdx +++ b/content/docs/references/ui/theme.mdx @@ -31,8 +31,8 @@ const result = Animation.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **duration** | `Object` | optional | | -| **timing** | `Object` | optional | | +| **duration** | `{ fast?: string; base?: string; slow?: string }` | optional | | +| **timing** | `{ linear?: string; ease?: string; ease_in?: string; ease_out?: string; … }` | optional | | --- @@ -160,22 +160,22 @@ const result = Animation.parse(data); | **label** | `string` | ✅ | Human-readable theme name | | **description** | `string` | optional | Theme description | | **mode** | `Enum<'light' \| 'dark' \| 'auto'>` | ✅ | Theme mode (light, dark, or auto) | -| **colors** | `Object` | ✅ | Color palette configuration | -| **typography** | `Object` | optional | Typography settings | -| **spacing** | `Object` | optional | Spacing scale | -| **borderRadius** | `Object` | optional | Border radius scale | -| **shadows** | `Object` | optional | Box shadow effects | -| **breakpoints** | `Object` | optional | Responsive breakpoints | -| **animation** | `Object` | optional | Animation settings | -| **zIndex** | `Object` | optional | Z-index scale for layering | +| **colors** | `{ primary: string; secondary?: string; accent?: string; success?: string; … }` | ✅ | Color palette configuration | +| **typography** | `{ fontFamily?: object; fontSize?: object; fontWeight?: object; lineHeight?: object; … }` | optional | Typography settings | +| **spacing** | `{ 0?: string; 1?: string; 2?: string; 3?: string; … }` | optional | Spacing scale | +| **borderRadius** | `{ none?: string; sm?: string; base?: string; md?: string; … }` | optional | Border radius scale | +| **shadows** | `{ none?: string; sm?: string; base?: string; md?: string; … }` | optional | Box shadow effects | +| **breakpoints** | `{ xs?: string; sm?: string; md?: string; lg?: string; … }` | optional | Responsive breakpoints | +| **animation** | `{ duration?: object; timing?: object }` | optional | Animation settings | +| **zIndex** | `{ base?: number; dropdown?: number; sticky?: number; fixed?: number; … }` | optional | Z-index scale for layering | | **customVars** | `Record` | optional | Custom CSS variables (key-value pairs) | -| **logo** | `Object` | optional | Logo assets | +| **logo** | `{ light?: string; dark?: string; favicon?: string }` | optional | Logo assets | | **extends** | `string` | optional | Base theme to extend from | | **density** | `Enum<'compact' \| 'regular' \| 'spacious'>` | optional | Display density: compact, regular, or spacious | | **wcagContrast** | `Enum<'AA' \| 'AAA'>` | optional | WCAG color contrast level (AA or AAA) | | **rtl** | `boolean` | optional | Enable right-to-left layout direction | -| **touchTarget** | `Object` | optional | Touch target sizing defaults | -| **keyboardNavigation** | `Object` | optional | Keyboard focus management settings | +| **touchTarget** | `{ minWidth: number; minHeight: number; padding?: number; hitSlop?: object }` | optional | Touch target sizing defaults | +| **keyboardNavigation** | `{ tabOrder: Enum<'auto' \| 'manual'>; skipLinks: boolean; focusVisible: boolean; focusTrap?: object; … }` | optional | Keyboard focus management settings | --- @@ -197,11 +197,11 @@ const result = Animation.parse(data); | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **fontFamily** | `Object` | optional | | -| **fontSize** | `Object` | optional | | -| **fontWeight** | `Object` | optional | | -| **lineHeight** | `Object` | optional | | -| **letterSpacing** | `Object` | optional | | +| **fontFamily** | `{ base?: string; heading?: string; mono?: string }` | optional | | +| **fontSize** | `{ xs?: string; sm?: string; base?: string; lg?: string; … }` | optional | | +| **fontWeight** | `{ light?: number; normal?: number; medium?: number; semibold?: number; … }` | optional | | +| **lineHeight** | `{ tight?: string; normal?: string; relaxed?: string; loose?: string }` | optional | | +| **letterSpacing** | `{ tighter?: string; tight?: string; normal?: string; wide?: string; … }` | optional | | --- diff --git a/content/docs/references/ui/touch.mdx b/content/docs/references/ui/touch.mdx index 9f20c191bd..f594634c40 100644 --- a/content/docs/references/ui/touch.mdx +++ b/content/docs/references/ui/touch.mdx @@ -36,9 +36,9 @@ Per-gesture configuration | **type** | `Enum<'swipe' \| 'pinch' \| 'long_press' \| 'double_tap' \| 'drag' \| 'rotate' \| 'pan'>` | ✅ | Gesture type to configure | | **label** | `string` | optional | Descriptive label for the gesture action | | **enabled** | `boolean` | ✅ | Whether this gesture is active | -| **swipe** | `Object` | optional | Swipe gesture settings (when type is swipe) | -| **pinch** | `Object` | optional | Pinch gesture settings (when type is pinch) | -| **longPress** | `Object` | optional | Long press settings (when type is long_press) | +| **swipe** | `{ direction: Enum<'up' \| 'down' \| 'left' \| 'right'>[]; threshold?: number; velocity?: number }` | optional | Swipe gesture settings (when type is swipe) | +| **pinch** | `{ minScale?: number; maxScale?: number }` | optional | Pinch gesture settings (when type is pinch) | +| **longPress** | `{ duration: number; moveTolerance?: number }` | optional | Long press settings (when type is long_press) | --- @@ -123,8 +123,8 @@ Touch and gesture interaction configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **gestures** | `Object[]` | optional | Configured gesture recognizers | -| **touchTarget** | `Object` | optional | Touch target sizing and hit area | +| **gestures** | `{ type: Enum<'swipe' \| 'pinch' \| 'long_press' \| 'double_tap' \| 'drag' \| 'rotate' \| 'pan'>; label?: string; enabled: boolean; swipe?: object; … }[]` | optional | Configured gesture recognizers | +| **touchTarget** | `{ minWidth: number; minHeight: number; padding?: number; hitSlop?: object }` | optional | Touch target sizing and hit area | | **hapticFeedback** | `boolean` | optional | Enable haptic feedback on touch interactions | | **ariaLabel** | `string` | optional | Accessible label for screen readers (WAI-ARIA aria-label) | | **ariaDescribedBy** | `string` | optional | ID of element providing additional description (WAI-ARIA aria-describedby) | @@ -144,7 +144,7 @@ Touch target sizing configuration (WCAG accessible) | **minWidth** | `number` | ✅ | Minimum touch target width in pixels (WCAG 2.5.5: 44px) | | **minHeight** | `number` | ✅ | Minimum touch target height in pixels (WCAG 2.5.5: 44px) | | **padding** | `number` | optional | Additional padding around touch target in pixels | -| **hitSlop** | `Object` | optional | Invisible hit area extension beyond the visible bounds | +| **hitSlop** | `{ top?: number; right?: number; bottom?: number; left?: number }` | optional | Invisible hit area extension beyond the visible bounds | --- diff --git a/content/docs/references/ui/view.mdx b/content/docs/references/ui/view.mdx index 2afaab81cf..145d9460c4 100644 --- a/content/docs/references/ui/view.mdx +++ b/content/docs/references/ui/view.mdx @@ -7,7 +7,7 @@ description: View protocol schemas HTTP Method Enum & HTTP Request Schema -Migrated to shared/http.zod.ts. Re-exported here for backward compatibility. +Migrated to [shared/http.zod.ts](/docs/references/shared/http). Re-exported here for backward compatibility. **Source:** `packages/spec/src/ui/view.zod.ts` @@ -110,7 +110,7 @@ Aggregation function for column footer summary | :--- | :--- | :--- | :--- | | **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 | +| **options** | `{ label: string; value: string; color?: string; default?: boolean; … }[]` | 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 | @@ -130,11 +130,11 @@ Aggregation function for column footer summary | **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 | +| **fields** | `[FormField](#formfield)[]` | optional | Sub-fields for composite/repeater/record types | +| **keyField** | `{ field?: string; label?: string; placeholder?: string; helpText?: string; … }` | 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. | +| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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 \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: 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). | @@ -151,10 +151,10 @@ Aggregation function for column footer summary | **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)[]` | ✅ | | +| **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — section shown only when TRUE. Root: `record`+`current_user` (runtime forms) or `data` (metadata forms). | +| **visibleOn** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | [DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Hides the whole section when false. Normalized to `visibleWhen` at parse. | +| **columns** | `Enum<'1' \| '2' \| '3' \| '4'> \| '1' \| '2' \| '3' \| '4'` | optional | | +| **fields** | `string \| { field: string; 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'>; options?: { label: string; value: string; color?: string; default?: boolean; … }[]; reference?: string; … }[]` | ✅ | | --- @@ -180,16 +180,16 @@ Aggregation function for column footer summary | **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 | -| **buttons** | `Object` | optional | [EXPERIMENTAL — NOT ENFORCED, #2998] Form action-button visibility & labels. Renderer wiring pending in ObjectUI (objectui#2545). | +| **data** | `{ provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }` | optional | Data source configuration (defaults to "object" provider) | +| **sections** | `{ name?: string; label?: string; description?: string; collapsible?: boolean; … }[]` | optional | | +| **groups** | `{ name?: string; label?: string; description?: string; collapsible?: boolean; … }[]` | optional | | +| **subforms** | `{ childObject: string; relationshipField?: string; columns?: any[]; amountField?: string; … }[]` | optional | Inline master-detail child collections | +| **defaultSort** | `{ field: string; order?: Enum<'asc' \| 'desc'> }[]` | optional | Default sort order for related list views within this form | +| **sharing** | `{ enabled?: boolean; publicLink?: string; password?: string; allowedDomains?: string[]; … }` | optional | Public sharing configuration for this form | +| **submitBehavior** | `{ kind: 'thank-you'; title?: string; message?: string } \| { kind: 'redirect'; url: string; delayMs?: integer } \| { kind: 'continue' } \| { kind: 'next-record' }` | optional | Post-submit behavior | +| **buttons** | `{ submit?: object; cancel?: object; reset?: object }` | optional | [EXPERIMENTAL — NOT ENFORCED, #2998] Form action-button visibility & labels. Renderer wiring pending in ObjectUI (objectui#2545). | | **defaults** | `Record` | optional | [EXPERIMENTAL — NOT ENFORCED, #2998] Initial field values for create-mode forms (spec home for ObjectUI `initialValues`). Renderer wiring pending (objectui#2545). | -| **aria** | `Object` | optional | ARIA accessibility attributes for the form view | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes for the form view | --- @@ -232,8 +232,8 @@ Gallery/card view configuration | **assigneeField** | `string` | optional | Resource field to bucket load by (resource view) | | **effortField** | `string` | optional | Per-task load units (resource view; default 1) | | **capacity** | `number` | optional | Per-resource capacity ceiling; loads above this flag overload | -| **tooltipFields** | `string \| Object[]` | optional | Fields to surface in the hover tooltip, in display order | -| **quickFilters** | `Object[]` | optional | Multi-select filter dropdowns rendered above the chart | +| **tooltipFields** | `string \| { field: string; label?: string }[]` | optional | Fields to surface in the hover tooltip, in display order | +| **quickFilters** | `{ field: string; label?: string; options?: string \| { value: string \| number; label?: string }[] }[]` | optional | Multi-select filter dropdowns rendered above the chart | | **autoZoomToFilter** | `boolean` | optional | When true (default), filtering zooms the range to the filtered tasks | @@ -247,7 +247,7 @@ Gallery/card view configuration | :--- | :--- | :--- | :--- | | **field** | `string` | ✅ | Record field / dot-path the dimension filters on | | **label** | `string` | optional | Trigger label (falls back to the field label) | -| **options** | `string \| Object[]` | optional | Explicit option override for fixed enums | +| **options** | `string \| { value: string \| number; label?: string }[]` | optional | Explicit option override for fixed enums | --- @@ -260,7 +260,7 @@ Record grouping configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **fields** | `Object[]` | ✅ | Fields to group by (supports up to 3 levels) | +| **fields** | `{ field: string; order: Enum<'asc' \| 'desc'>; collapsed: boolean }[]` | ✅ | Fields to group by (supports up to 3 levels) | --- @@ -339,51 +339,51 @@ List chart view configuration | **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 | | +| **data** | `{ provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }` | optional | Data source configuration (defaults to "object" provider) | +| **columns** | `string[] \| { field: string; label?: string; width?: number; align?: Enum<'left' \| 'center' \| 'right'>; … }[]` | ✅ | Fields to display as columns | +| **filter** | `{ field: string; operator: string; value?: string \| number \| boolean \| null \| string \| number[] }[]` | optional | Filter criteria (JSON Rules) | +| **sort** | `string \| { field: string; order: Enum<'asc' \| 'desc'> }[]` | 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 | +| **userFilters** | `{ element?: Enum<'dropdown' \| 'tabs' \| 'toggle'>; fields?: { field: string; label?: string; type?: Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>; options?: { value: string \| number \| boolean; label: string; color?: string }[]; … }[]; tabs?: { name: string; label?: string; icon?: string; view?: string; … }[]; showAllRecords?: boolean }` | 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 | | +| **selection** | `{ type?: Enum<'none' \| 'single' \| 'multiple'> }` | optional | Row selection configuration | +| **navigation** | `{ mode?: Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>; view?: string; preventNavigation?: boolean; openNewTab?: boolean; … }` | optional | Configuration for item click navigation (page, drawer, modal, etc.) | +| **pagination** | `{ pageSize?: integer; pageSizeOptions?: integer[] }` | optional | Pagination configuration | +| **kanban** | `{ groupByField: string; summarizeField?: string; columns: string[] }` | optional | | +| **calendar** | `{ startDateField: string; endDateField?: string; titleField: string; colorField?: string }` | optional | | | **gantt** | `Record` | optional | | -| **gallery** | `Object` | optional | Gallery/card view configuration | -| **timeline** | `Object` | optional | Timeline view configuration | -| **chart** | `Object` | optional | List chart view configuration | +| **gallery** | `{ coverField?: string; coverFit?: Enum<'cover' \| 'contain'>; cardSize?: Enum<'small' \| 'medium' \| 'large'>; titleField?: string; … }` | optional | Gallery/card view configuration | +| **timeline** | `{ startDateField: string; endDateField?: string; titleField: string; groupByField?: string; … }` | optional | Timeline view configuration | +| **chart** | `{ chartType?: Enum<'bar' \| 'line' \| 'pie' \| 'area' \| 'scatter'>; dataset: string; dimensions?: string[]; values: string[] }` | optional | List chart view configuration | | **tree** | `Record` | optional | | | **description** | `string` | optional | View description for documentation/tooltips | -| **sharing** | `Object` | optional | View sharing and access configuration | +| **sharing** | `{ type?: Enum<'personal' \| 'collaborative'>; lockedBy?: string }` | 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 | +| **grouping** | `{ fields: { field: string; order?: Enum<'asc' \| 'desc'>; collapsed?: boolean }[] }` | optional | Group records by one or more fields | +| **rowColor** | `{ field: string; colors?: Record }` | 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 | +| **conditionalFormatting** | `{ condition: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; style: Record }[]` | 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 | +| **userActions** | `{ sort?: boolean; search?: boolean; filter?: boolean; rowHeight?: boolean; … }` | optional | User action toggles for the view toolbar | +| **appearance** | `{ showDescription?: boolean; allowedVisualizations?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>[] }` | optional | Appearance and visualization configuration | +| **tabs** | `{ name: string; label?: string; icon?: string; view?: string; … }[]` | optional | Tab definitions for multi-tab view interface | +| **addRecord** | `{ enabled?: boolean; position?: Enum<'top' \| 'bottom' \| 'both'>; mode?: Enum<'inline' \| 'form' \| 'modal'>; formView?: string }` | 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 | +| **emptyState** | `{ title?: string; message?: string; icon?: string }` | optional | Empty state configuration when no records found | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes for the list view | +| **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive layout configuration | +| **performance** | `{ lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' \| 'cache-first' \| 'network-first' \| 'stale-while-revalidate'>; prefetch?: boolean; … }` | optional | Performance optimization settings | --- @@ -428,51 +428,51 @@ List chart view configuration | **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 | | +| **data** | `{ provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }` | optional | Data source configuration (defaults to "object" provider) | +| **columns** | `string[] \| { field: string; label?: string; width?: number; align?: Enum<'left' \| 'center' \| 'right'>; … }[]` | ✅ | Fields to display as columns | +| **filter** | `{ field: string; operator: string; value?: string \| number \| boolean \| null \| string \| number[] }[]` | optional | Filter criteria (JSON Rules) | +| **sort** | `string \| { field: string; order: Enum<'asc' \| 'desc'> }[]` | 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 | | +| **selection** | `{ type?: Enum<'none' \| 'single' \| 'multiple'> }` | optional | Row selection configuration | +| **navigation** | `{ mode?: Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>; view?: string; preventNavigation?: boolean; openNewTab?: boolean; … }` | optional | Configuration for item click navigation (page, drawer, modal, etc.) | +| **pagination** | `{ pageSize?: integer; pageSizeOptions?: integer[] }` | optional | Pagination configuration | +| **kanban** | `{ groupByField: string; summarizeField?: string; columns: string[] }` | optional | | +| **calendar** | `{ startDateField: string; endDateField?: string; titleField: string; colorField?: string }` | optional | | | **gantt** | `Record` | optional | | -| **gallery** | `Object` | optional | Gallery/card view configuration | -| **timeline** | `Object` | optional | Timeline view configuration | -| **chart** | `Object` | optional | List chart view configuration | +| **gallery** | `{ coverField?: string; coverFit?: Enum<'cover' \| 'contain'>; cardSize?: Enum<'small' \| 'medium' \| 'large'>; titleField?: string; … }` | optional | Gallery/card view configuration | +| **timeline** | `{ startDateField: string; endDateField?: string; titleField: string; groupByField?: string; … }` | optional | Timeline view configuration | +| **chart** | `{ chartType?: Enum<'bar' \| 'line' \| 'pie' \| 'area' \| 'scatter'>; dataset: string; dimensions?: string[]; values: string[] }` | optional | List chart view configuration | | **tree** | `Record` | optional | | | **description** | `string` | optional | View description for documentation/tooltips | -| **sharing** | `Object` | optional | View sharing and access configuration | +| **sharing** | `{ type?: Enum<'personal' \| 'collaborative'>; lockedBy?: string }` | 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 | +| **grouping** | `{ fields: { field: string; order?: Enum<'asc' \| 'desc'>; collapsed?: boolean }[] }` | optional | Group records by one or more fields | +| **rowColor** | `{ field: string; colors?: Record }` | 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 | +| **conditionalFormatting** | `{ condition: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; style: Record }[]` | 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 | +| **userActions** | `{ sort?: boolean; search?: boolean; filter?: boolean; rowHeight?: boolean; … }` | optional | User action toggles for the view toolbar | +| **appearance** | `{ showDescription?: boolean; allowedVisualizations?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>[] }` | optional | Appearance and visualization configuration | +| **tabs** | `{ name: string; label?: string; icon?: string; view?: string; … }[]` | optional | Tab definitions for multi-tab view interface | +| **addRecord** | `{ enabled?: boolean; position?: Enum<'top' \| 'bottom' \| 'both'>; mode?: Enum<'inline' \| 'form' \| 'modal'>; formView?: string }` | 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 | | +| **emptyState** | `{ title?: string; message?: string; icon?: string }` | optional | Empty state configuration when no records found | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes for the list view | +| **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive layout configuration | +| **performance** | `{ lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' \| 'cache-first' \| 'network-first' \| 'stale-while-revalidate'>; prefetch?: boolean; … }` | optional | Performance optimization settings | +| **userFilters** | `{ element?: Enum<'dropdown' \| 'toggle'>; fields?: { field: string; label?: string; type?: Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>; options?: { value: string \| number \| boolean; label: string; color?: string }[]; … }[] }` | optional | | --- @@ -484,7 +484,7 @@ List chart view configuration | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **element** | `Enum<'dropdown' \| 'toggle'>` | ✅ | Filter control style on object views: "dropdown" (per-field value chips). "toggle" is deprecated. "tabs" is page-only — use `listViews` for named presets. | -| **fields** | `Object[]` | optional | Fields exposed as quick filters (dropdown/toggle elements) | +| **fields** | `{ field: string; label?: string; type?: Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>; options?: { value: string \| number \| boolean; label: string; color?: string }[]; … }[]` | optional | Fields exposed as quick filters (dropdown/toggle elements) | --- @@ -603,7 +603,7 @@ Quick-filter field configuration | **field** | `string` | ✅ | Field name on the source object (must exist — checked by reference diagnostics) | | **label** | `string` | optional | Display label override (defaults to the field label) | | **type** | `Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>` | optional | Filter control type. Omit to infer from the field definition | -| **options** | `Object[]` | optional | Static options. Omit to derive from the field definition (select options / lookup records) | +| **options** | `{ value: string \| number \| boolean; label: string; color?: string }[]` | optional | Static options. Omit to derive from the field definition (select options / lookup records) | | **showCount** | `boolean` | optional | Show per-option record counts | | **defaultValues** | `string \| number \| boolean[]` | optional | Pre-selected values when the view loads | @@ -619,8 +619,8 @@ End-user quick-filter configuration (Airtable "User filters" parity) | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | **element** | `Enum<'dropdown' \| 'tabs' \| 'toggle'>` | ✅ | Filter control style: "dropdown" (per-field value selectors) or "tabs" (named presets). "toggle" is deprecated. | -| **fields** | `Object[]` | optional | Fields exposed as quick filters (dropdown/toggle elements) | -| **tabs** | `Object[]` | optional | Named filter presets rendered as tabs (tabs element). Reuses ViewTabSchema | +| **fields** | `{ field: string; label?: string; type?: Enum<'select' \| 'multi-select' \| 'boolean' \| 'date-range' \| 'text'>; options?: { value: string \| number \| boolean; label: string; color?: string }[]; … }[]` | optional | Fields exposed as quick filters (dropdown/toggle elements) | +| **tabs** | `{ name: string; label?: string; icon?: string; view?: string; … }[]` | optional | Named filter presets rendered as tabs (tabs element). Reuses ViewTabSchema | | **showAllRecords** | `boolean` | optional | Show an "All records" tab before the presets (tabs element) | @@ -632,11 +632,11 @@ End-user quick-filter configuration (Airtable "User filters" parity) | 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. | +| **list** | `{ name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }` | optional | | +| **form** | `{ type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }` | optional | | +| **listViews** | `Record; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }>` | optional | Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047) | +| **formViews** | `Record; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }>` | optional | Additional named form views | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -660,7 +660,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | +| **provider** | `'object'` | ✅ | | | **object** | `string` | ✅ | Target object name | --- @@ -671,9 +671,9 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | -| **read** | `Object` | optional | Configuration for fetching data | -| **write** | `Object` | optional | Configuration for submitting data (for forms/editable tables) | +| **provider** | `'api'` | ✅ | | +| **read** | `{ url: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>; headers?: Record; params?: Record; … }` | optional | Configuration for fetching data | +| **write** | `{ url: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>; headers?: Record; params?: Record; … }` | optional | Configuration for submitting data (for forms/editable tables) | --- @@ -683,7 +683,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | +| **provider** | `'value'` | ✅ | | | **items** | `any[]` | ✅ | Static data array | --- @@ -694,7 +694,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | +| **provider** | `'schema'` | ✅ | | | **schemaId** | `string` | ✅ | Schema identifier — typically the metadata type name | | **schema** | `Record` | optional | Inline JSON Schema (Draft 2020-12). Optional when schemaId is resolvable. | @@ -730,8 +730,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **viewKind** | `string` | ✅ | | -| **config** | `Object` | ✅ | List-family view configuration. | +| **viewKind** | `'list'` | ✅ | | +| **config** | `{ name?: string; label?: string; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: { provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record }; … }` | ✅ | 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). | @@ -740,7 +740,7 @@ This schema accepts one of the following structures: | **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. | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -757,8 +757,8 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **viewKind** | `string` | ✅ | | -| **config** | `Object` | ✅ | Form view configuration. | +| **viewKind** | `'form'` | ✅ | | +| **config** | `{ type?: Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>; layout?: Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>; columns?: integer; title?: string; … }` | ✅ | 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). | @@ -767,7 +767,7 @@ This schema accepts one of the following structures: | **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. | +| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | 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). | @@ -835,7 +835,7 @@ Tab configuration for multi-tab view interface | **label** | `string` | optional | Display label | | **icon** | `string` | optional | Tab icon name | | **view** | `string` | optional | Referenced list view name from listViews | -| **filter** | `Object[]` | optional | Tab-specific filter criteria | +| **filter** | `{ field: string; operator: string; value?: string \| number \| boolean \| null \| string \| number[] }[]` | optional | Tab-specific filter criteria | | **order** | `integer` | optional | Tab display order | | **pinned** | `boolean` | ✅ | Pin tab (cannot be removed by users) | | **isDefault** | `boolean` | ✅ | Set as the default active tab | diff --git a/content/docs/references/ui/widget.mdx b/content/docs/references/ui/widget.mdx index 9b4a8439ce..85fcc44b2e 100644 --- a/content/docs/references/ui/widget.mdx +++ b/content/docs/references/ui/widget.mdx @@ -11,9 +11,9 @@ Defines lifecycle callbacks for custom widgets inspired by Web Components and Re These hooks allow widgets to perform initialization, cleanup, and respond to changes. -@see https://developer.mozilla.org/en-US/docs/Web/API/Web_components +See also: https://developer.mozilla.org/en-US/docs/Web/API/Web_components -@see https://react.dev/reference/react/Component#component-lifecycle +See also: https://react.dev/reference/react/Component#component-lifecycle @example @@ -100,17 +100,17 @@ const result = WidgetEvent.parse(data); | **icon** | `string` | optional | Widget icon | | **fieldTypes** | `string[]` | optional | Supported field types | | **category** | `Enum<'input' \| 'display' \| 'picker' \| 'editor' \| 'custom'>` | ✅ | Widget category | -| **lifecycle** | `Object` | optional | Lifecycle hooks | -| **events** | `Object[]` | optional | Custom events | -| **properties** | `Object[]` | optional | Configuration properties | -| **implementation** | `Object \| Object \| Object` | optional | Widget implementation source | -| **dependencies** | `Object[]` | optional | Widget dependencies | +| **lifecycle** | `{ onMount?: string; onUpdate?: string; onUnmount?: string; onValidate?: string; … }` | optional | Lifecycle hooks | +| **events** | `{ name: string; label?: string; description?: string; bubbles: boolean; … }[]` | optional | Custom events | +| **properties** | `{ name: string; label?: string; type: Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'function' \| 'any'>; required: boolean; … }[]` | optional | Configuration properties | +| **implementation** | `{ type: 'npm'; packageName: string; version: string; exportName?: string } \| { type: 'remote'; url: string; moduleName: string; scope: string } \| { type: 'inline'; code: string }` | optional | Widget implementation source | +| **dependencies** | `{ name: string; version?: string; url?: string }[]` | optional | Widget dependencies | | **screenshots** | `string[]` | optional | Screenshot URLs | | **documentation** | `string` | optional | Documentation URL | | **license** | `string` | optional | License (SPDX identifier) | | **tags** | `string[]` | optional | Tags for categorization | -| **aria** | `Object` | optional | ARIA accessibility attributes | -| **performance** | `Object` | optional | Performance optimization settings | +| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes | +| **performance** | `{ lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' \| 'cache-first' \| 'network-first' \| 'stale-while-revalidate'>; prefetch?: boolean; … }` | optional | Performance optimization settings | --- @@ -147,7 +147,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'npm'` | ✅ | | | **packageName** | `string` | ✅ | NPM package name | | **version** | `string` | ✅ | | | **exportName** | `string` | optional | Named export (default: default) | @@ -162,7 +162,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'remote'` | ✅ | | | **url** | `string` | ✅ | Remote entry URL (.js) | | **moduleName** | `string` | ✅ | Exposed module name | | **scope** | `string` | ✅ | Remote scope name | @@ -177,7 +177,7 @@ This schema accepts one of the following structures: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | +| **type** | `'inline'` | ✅ | | | **code** | `string` | ✅ | JavaScript code body | --- diff --git a/packages/spec/scripts/build-docs.ts b/packages/spec/scripts/build-docs.ts index db8d95850b..59c636a8da 100644 --- a/packages/spec/scripts/build-docs.ts +++ b/packages/spec/scripts/build-docs.ts @@ -185,38 +185,112 @@ function scanCategories() { scanCategories(); +/** + * Context a page needs to turn a `$ref` into a link that actually resolves. + * + * Pages are named after the *zod file* (`data/object.mdx`) while refs name a + * *schema* (`Field`), so a ref can only be linked by looking the schema name up + * in the maps built by scanCategories(). Anonymous refs (`__schemaN`, emitted + * when Zod hoists a reused inline schema into `$defs`) have no page at all and + * are rendered structurally instead. + */ +interface TypeContext { + /** `$defs` of the document being rendered — for resolving local refs. */ + defs: Record; + /** The schema whose section is being rendered — target of a self `$ref` (`"#"`). */ + currentSchema: string; + /** + * Anonymous refs already being expanded on this branch. Schemas are cyclic + * (a node contains nodes), so inlining without this recurses forever. + */ + expanding?: Set; +} + +const refName = (ref: string): string => ref.split('/').pop() || ref; +const isAnonymousRef = (name: string) => /^__schema\d+$/.test(name); + +/** A page-local anchor, matching how fumadocs slugs the `## SchemaName` heading. */ +const anchorFor = (schemaName: string) => `#${schemaName.toLowerCase()}`; + +/** + * Resolve a schema name to its page. Returns null when the schema isn't one we + * generate a page for — callers then render the type without a link rather than + * emitting a 404. + */ +function schemaHref(name: string): string | null { + const category = schemaCategoryMap.get(name); + const zodFile = schemaZodFileMap.get(name); + if (!category || !zodFile) return null; + return `/docs/references/${category}/${zodFile}${anchorFor(name)}`; +} + // Helpers to format types -function formatType(prop: any): string { +function formatType(prop: any, ctx?: TypeContext): string { if (!prop) return 'any'; - + if (prop.$ref) { - const ref = prop.$ref.split('/').pop(); - return `[${ref}](./${ref})`; + // Self-reference: link to the current section rather than a bare `#`. + if (prop.$ref === '#') { + return ctx ? `[${ctx.currentSchema}](${anchorFor(ctx.currentSchema)})` : 'object'; + } + + const name = refName(prop.$ref); + + // Zod-hoisted inline schema: no page exists. Render its shape instead. + if (isAnonymousRef(name)) { + const target = ctx?.defs?.[name]; + if (!target) return 'object'; + // Cycle guard: these schemas are recursive (a node contains nodes). + if (ctx!.expanding?.has(name)) return 'object'; + const expanding = new Set(ctx!.expanding ?? []); + expanding.add(name); + return formatType({ ...target, $ref: undefined }, { ...ctx!, expanding }); + } + + const href = schemaHref(name); + return href ? `[${name}](${href})` : name; } - + if (prop.type === 'array') { - return `${formatType(prop.items)}[]`; + return `${formatType(prop.items, ctx)}[]`; } - + if (prop.enum) { return `Enum<${prop.enum.map((e: any) => `'${e}'`).join(' | ')}>`; } - + + if (prop.const !== undefined) { + return `'${prop.const}'`; + } + if (prop.anyOf || prop.oneOf) { const variants = prop.anyOf || prop.oneOf; - return variants.map(formatType).join(' | '); + return variants.map((v: any) => formatType(v, ctx)).join(' | '); } if (prop.type === 'object' && prop.additionalProperties) { - return `Record`; + return `Record`; } if (prop.type === 'object' && !prop.properties && !prop.additionalProperties) { return 'object'; } - // Handle inline objects slightly better by just calling them 'Object' - if (prop.type === 'object') return 'Object'; + // Inline object: show its shape one level deep instead of an opaque `Object`. + if (prop.type === 'object' && prop.properties) { + const keys = Object.keys(prop.properties); + const shown = keys.slice(0, 4).map(k => { + const child = prop.properties[k]; + const optional = (prop.required || []).includes(k) ? '' : '?'; + // Depth-limited: nested objects stay opaque so a table cell can't explode. + const childType = child?.type === 'object' && child.properties + ? 'object' + : formatType(child, ctx); + return `${k}${optional}: ${childType}`; + }); + if (keys.length > shown.length) shown.push('…'); + return `{ ${shown.join('; ')} }`; + } if (Array.isArray(prop.type)) { return prop.type.join(' | '); @@ -225,6 +299,19 @@ function formatType(prop: any): string { return prop.type || 'any'; } +/** + * Rewrite a source path referenced from JSDoc (`../automation/sync.zod.ts`) to + * the docs route that renders it. Without this the generated page links to a + * path that only exists in the repo, i.e. a 404 on the site. + */ +function sourcePathToDocsRoute(target: string): string | null { + const m = target.match(/(?:^|\/)([\w-]+)\/([\w.-]+)\.zod\.ts$/); + if (!m) return null; + const [, category, zodFile] = m; + if (!CATEGORIES[category]) return null; + return `/docs/references/${category}/${zodFile}`; +} + // Extract file-level JSDoc description from source function getFileDescription(content: string): string { const match = content.match(/\/\*\*([\s\S]*?)\*\//); @@ -233,9 +320,20 @@ function getFileDescription(content: string): string { .split('\n') .map(line => line.replace(/^\s*\*\s?/, '').trim()) .filter(line => line) + // A bare `@see ` tag renders as noise — turn it into prose. + .map(line => line.replace(/^@see\s+/, 'See also: ')) .join('\n\n') - .replace(/\{@link\s+([^|]+?)\s*\|\s*([^}]+?)\s*\}/g, '[$2]($1)') // {@link url | text} -> [text](url) - .replace(/\{@link\s+([^}]+?)\s*\}/g, '[$1]($1)') // {@link url} -> [url](url) + .replace(/\{@link\s+([^|]+?)\s*\|\s*([^}]+?)\s*\}/g, (_m, target: string, text: string) => + `[${text.trim()}](${sourcePathToDocsRoute(target.trim()) ?? target.trim()})`) + .replace(/\{@link\s+([^}]+?)\s*\}/g, (_m, target: string) => { + const route = sourcePathToDocsRoute(target.trim()); + return route ? `[${target.trim()}](${route})` : `\`${target.trim()}\``; + }) + // Same for a bare source path left in prose by `See also:` above. + .replace(/(? { + const route = sourcePathToDocsRoute(p); + return route ? `[${p}](${route})` : `\`${p}\``; + }) .replace(/file:\/\//g, '') // Remove file:// protocol .replace(/\{/g, '\\{').replace(/\}/g, '\\}') // Escape { } for MDX } @@ -311,12 +409,19 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod md += `${escapeMdxDescription(mainDef.description)}\n\n`; } + const typeCtx: TypeContext = { defs, currentSchema: schemaName }; + const renderProperties = (props: any, required: Set = new Set()) => { let t = `### Properties\n\n`; t += `| Property | Type | Required | Description |\n`; t += `| :--- | :--- | :--- | :--- |\n`; for (const [key, prop] of Object.entries(props) as [string, any][]) { - const typeStr = formatType(prop).replace(/\|/g, '\\|'); + // Backslashes first, then pipes — same order as `desc` below, and for + // the same reason: escaping pipes first lets a literal backslash in + // the input pair with the escape and free the pipe again. + const typeStr = formatType(prop, typeCtx) + .replace(/\\/g, '\\\\') + .replace(/\|/g, '\\|'); const isReq = required.has(key) ? '✅' : 'optional'; // Escape for the GFM table cell last: backslashes first (so an existing // `\|` in a description can't decay into an escaped backslash + live @@ -354,10 +459,9 @@ function generateMarkdown(schemaName: string, schema: any, category: string, zod } else if (variant.enum) { md += `Allowed Values: ${variant.enum.map((e:string) => `\`${e}\``).join(', ')}\n\n`; } else if (variant.$ref) { - const refName = variant.$ref.split('/').pop(); - md += `Reference: [${refName}](./${refName})\n\n`; + md += `Reference: ${formatType(variant, typeCtx)}\n\n`; } else { - md += `Type: \`${formatType(variant)}\`\n\n`; + md += `Type: \`${formatType(variant, typeCtx)}\`\n\n`; } md += `---\n\n`; });