From a9f1833b7556e174c0a8c5f5db4fcd3e7afb4691 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 02:21:22 +0000 Subject: [PATCH 1/6] Initial plan From 9f87caf08217818bbb5b868416e5b9dc2072396a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 02:24:33 +0000 Subject: [PATCH 2/6] fix: ensure category directories exist before writing index.mdx in build-docs script Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- content/docs/references/ai/agent-action.mdx | 607 ------------- content/docs/references/ai/agent.mdx | 86 -- content/docs/references/ai/conversation.mdx | 385 -------- content/docs/references/ai/cost.mdx | 367 -------- content/docs/references/ai/devops-agent.mdx | 344 ------- content/docs/references/ai/feedback-loop.mdx | 84 -- content/docs/references/ai/index.mdx | 1 + content/docs/references/ai/meta.json | 18 - content/docs/references/ai/model-registry.mdx | 204 ----- content/docs/references/ai/nlq.mdx | 260 ------ content/docs/references/ai/orchestration.mdx | 222 ----- .../docs/references/ai/plugin-development.mdx | 169 ---- content/docs/references/ai/predictive.mdx | 247 ----- content/docs/references/ai/rag-pipeline.mdx | 427 --------- content/docs/references/ai/runtime-ops.mdx | 178 ---- .../docs/references/api/.!52095!websocket.mdx | 262 ------ content/docs/references/api/analytics.mdx | 104 --- content/docs/references/api/auth.mdx | 145 --- content/docs/references/api/batch.mdx | 161 ---- content/docs/references/api/connector.mdx | 33 - content/docs/references/api/contract.mdx | 180 ---- content/docs/references/api/discovery.mdx | 76 -- content/docs/references/api/documentation.mdx | 270 ------ content/docs/references/api/endpoint.mdx | 74 -- content/docs/references/api/errors.mdx | 167 ---- content/docs/references/api/graphql.mdx | 397 -------- content/docs/references/api/http-cache.mdx | 177 ---- content/docs/references/api/hub.mdx | 636 ------------- content/docs/references/api/identity.mdx | 37 - content/docs/references/api/index.mdx | 4 +- content/docs/references/api/meta.json | 29 - content/docs/references/api/metadata.mdx | 69 -- content/docs/references/api/odata.mdx | 249 ----- .../docs/references/api/package-registry.mdx | 163 ---- content/docs/references/api/protocol.mdx | 525 ----------- content/docs/references/api/realtime.mdx | 142 --- content/docs/references/api/registry.mdx | 314 ------- content/docs/references/api/rest-server.mdx | 196 ---- content/docs/references/api/router.mdx | 73 -- content/docs/references/api/storage.mdx | 84 -- content/docs/references/api/view.mdx | 36 - content/docs/references/api/websocket.mdx | 629 ------------- .../docs/references/automation/approval.mdx | 105 --- .../docs/references/automation/connector.mdx | 122 --- content/docs/references/automation/etl.mdx | 291 ------ content/docs/references/automation/events.mdx | 33 - content/docs/references/automation/flow.mdx | 113 --- content/docs/references/automation/meta.json | 15 - .../references/automation/state-machine.mdx | 131 --- content/docs/references/automation/sync.mdx | 237 ----- .../automation/trigger-registry.mdx | 257 ------ .../docs/references/automation/webhook.mdx | 81 -- .../docs/references/automation/workflow.mdx | 315 ------- content/docs/references/contracts/meta.json | 4 - content/docs/references/data/analytics.mdx | 143 --- content/docs/references/data/data-engine.mdx | 464 ---------- content/docs/references/data/dataset.mdx | 53 -- content/docs/references/data/datasource.mdx | 88 -- content/docs/references/data/document.mdx | 121 --- content/docs/references/data/driver-nosql.mdx | 256 ------ content/docs/references/data/driver-sql.mdx | 90 -- content/docs/references/data/driver.mdx | 124 --- .../docs/references/data/external-lookup.mdx | 109 --- content/docs/references/data/field.mdx | 286 ------ content/docs/references/data/filter.mdx | 189 ---- content/docs/references/data/hook.mdx | 88 -- content/docs/references/data/mapping.mdx | 74 -- content/docs/references/data/meta.json | 23 - content/docs/references/data/metrics.mdx | 38 - content/docs/references/data/object.mdx | 211 ----- content/docs/references/data/query.mdx | 227 ----- .../docs/references/data/search-engine.mdx | 34 - content/docs/references/data/validation.mdx | 501 ---------- content/docs/references/identity/identity.mdx | 106 --- content/docs/references/identity/meta.json | 9 - .../docs/references/identity/organization.mdx | 93 -- content/docs/references/identity/role.mdx | 73 -- content/docs/references/identity/scim.mdx | 318 ------- .../docs/references/integration/connector.mdx | 448 --------- content/docs/references/integration/http.mdx | 37 - .../docs/references/integration/mapping.mdx | 38 - .../references/integration/message-queue.mdx | 63 -- content/docs/references/integration/meta.json | 11 - content/docs/references/integration/misc.mdx | 856 ------------------ .../references/integration/object-storage.mdx | 35 - content/docs/references/kernel/context.mdx | 57 -- content/docs/references/kernel/events.mdx | 288 ------ content/docs/references/kernel/feature.mdx | 54 -- content/docs/references/kernel/index.mdx | 3 + content/docs/references/kernel/manifest.mdx | 79 -- content/docs/references/kernel/meta.json | 25 - .../kernel/metadata-persistence.mdx | 215 ----- .../references/kernel/package-registry.mdx | 224 ----- content/docs/references/kernel/permission.mdx | 34 - .../references/kernel/plugin-capability.mdx | 174 ---- .../kernel/plugin-lifecycle-advanced.mdx | 185 ---- .../kernel/plugin-lifecycle-events.mdx | 216 ----- .../docs/references/kernel/plugin-loading.mdx | 282 ------ .../references/kernel/plugin-registry.mdx | 144 --- .../kernel/plugin-security-advanced.mdx | 82 -- .../references/kernel/plugin-security.mdx | 163 ---- .../references/kernel/plugin-structure.mdx | 58 -- .../references/kernel/plugin-validator.mdx | 86 -- .../references/kernel/plugin-versioning.mdx | 51 -- content/docs/references/kernel/plugin.mdx | 83 -- .../references/kernel/service-registry.mdx | 122 --- .../kernel/startup-orchestrator.mdx | 89 -- content/docs/references/meta.json | 1 + content/docs/references/qa/meta.json | 6 - content/docs/references/qa/testing.mdx | 135 --- content/docs/references/security/meta.json | 10 - .../docs/references/security/permission.mdx | 82 -- content/docs/references/security/policy.mdx | 96 -- content/docs/references/security/rls.mdx | 237 ----- content/docs/references/security/sharing.mdx | 158 ---- .../docs/references/security/territory.mdx | 89 -- content/docs/references/shared/http.mdx | 68 -- .../docs/references/shared/identifiers.mdx | 114 --- content/docs/references/shared/index.mdx | 2 + content/docs/references/shared/mapping.mdx | 171 ---- content/docs/references/shared/meta.json | 9 - content/docs/references/shared/view.mdx | 36 - content/docs/references/studio/index.mdx | 10 + content/docs/references/system/audit.mdx | 267 ------ .../docs/references/system/auth-config.mdx | 72 -- content/docs/references/system/cache.mdx | 114 --- .../references/system/change-management.mdx | 120 --- .../docs/references/system/collaboration.mdx | 568 ------------ content/docs/references/system/compliance.mdx | 97 -- content/docs/references/system/encryption.mdx | 92 -- .../docs/references/system/http-server.mdx | 161 ---- content/docs/references/system/index.mdx | 5 +- content/docs/references/system/job.mdx | 169 ---- content/docs/references/system/license.mdx | 76 -- content/docs/references/system/logging.mdx | 302 ------ content/docs/references/system/masking.mdx | 68 -- .../docs/references/system/message-queue.mdx | 97 -- content/docs/references/system/meta.json | 30 - .../system/metadata-persistence.mdx | 272 ------ content/docs/references/system/metrics.mdx | 32 - content/docs/references/system/migration.mdx | 249 ----- .../docs/references/system/notification.mdx | 154 ---- .../docs/references/system/object-storage.mdx | 314 ------- .../references/system/registry-config.mdx | 76 -- .../docs/references/system/search-engine.mdx | 97 -- .../references/system/service-registry.mdx | 100 -- content/docs/references/system/tenant.mdx | 179 ---- content/docs/references/system/tracing.mdx | 352 ------- .../docs/references/system/translation.mdx | 64 -- content/docs/references/system/worker.mdx | 241 ----- content/docs/references/ui/action.mdx | 64 -- content/docs/references/ui/app.mdx | 261 ------ content/docs/references/ui/chart.mdx | 162 ---- content/docs/references/ui/component.mdx | 105 --- content/docs/references/ui/dashboard.mdx | 59 -- content/docs/references/ui/meta.json | 15 - content/docs/references/ui/page.mdx | 118 --- content/docs/references/ui/report.mdx | 105 --- content/docs/references/ui/theme.mdx | 208 ----- content/docs/references/ui/view.mdx | 302 ------ content/docs/references/ui/widget.mdx | 200 ---- packages/spec/scripts/build-docs.ts | 6 +- 162 files changed, 29 insertions(+), 25623 deletions(-) delete mode 100644 content/docs/references/ai/agent-action.mdx delete mode 100644 content/docs/references/ai/agent.mdx delete mode 100644 content/docs/references/ai/conversation.mdx delete mode 100644 content/docs/references/ai/cost.mdx delete mode 100644 content/docs/references/ai/devops-agent.mdx delete mode 100644 content/docs/references/ai/feedback-loop.mdx delete mode 100644 content/docs/references/ai/meta.json delete mode 100644 content/docs/references/ai/model-registry.mdx delete mode 100644 content/docs/references/ai/nlq.mdx delete mode 100644 content/docs/references/ai/orchestration.mdx delete mode 100644 content/docs/references/ai/plugin-development.mdx delete mode 100644 content/docs/references/ai/predictive.mdx delete mode 100644 content/docs/references/ai/rag-pipeline.mdx delete mode 100644 content/docs/references/ai/runtime-ops.mdx delete mode 100644 content/docs/references/api/.!52095!websocket.mdx delete mode 100644 content/docs/references/api/analytics.mdx delete mode 100644 content/docs/references/api/auth.mdx delete mode 100644 content/docs/references/api/batch.mdx delete mode 100644 content/docs/references/api/connector.mdx delete mode 100644 content/docs/references/api/contract.mdx delete mode 100644 content/docs/references/api/discovery.mdx delete mode 100644 content/docs/references/api/documentation.mdx delete mode 100644 content/docs/references/api/endpoint.mdx delete mode 100644 content/docs/references/api/errors.mdx delete mode 100644 content/docs/references/api/graphql.mdx delete mode 100644 content/docs/references/api/http-cache.mdx delete mode 100644 content/docs/references/api/hub.mdx delete mode 100644 content/docs/references/api/identity.mdx delete mode 100644 content/docs/references/api/meta.json delete mode 100644 content/docs/references/api/metadata.mdx delete mode 100644 content/docs/references/api/odata.mdx delete mode 100644 content/docs/references/api/package-registry.mdx delete mode 100644 content/docs/references/api/protocol.mdx delete mode 100644 content/docs/references/api/realtime.mdx delete mode 100644 content/docs/references/api/registry.mdx delete mode 100644 content/docs/references/api/rest-server.mdx delete mode 100644 content/docs/references/api/router.mdx delete mode 100644 content/docs/references/api/storage.mdx delete mode 100644 content/docs/references/api/view.mdx delete mode 100644 content/docs/references/api/websocket.mdx delete mode 100644 content/docs/references/automation/approval.mdx delete mode 100644 content/docs/references/automation/connector.mdx delete mode 100644 content/docs/references/automation/etl.mdx delete mode 100644 content/docs/references/automation/events.mdx delete mode 100644 content/docs/references/automation/flow.mdx delete mode 100644 content/docs/references/automation/meta.json delete mode 100644 content/docs/references/automation/state-machine.mdx delete mode 100644 content/docs/references/automation/sync.mdx delete mode 100644 content/docs/references/automation/trigger-registry.mdx delete mode 100644 content/docs/references/automation/webhook.mdx delete mode 100644 content/docs/references/automation/workflow.mdx delete mode 100644 content/docs/references/contracts/meta.json delete mode 100644 content/docs/references/data/analytics.mdx delete mode 100644 content/docs/references/data/data-engine.mdx delete mode 100644 content/docs/references/data/dataset.mdx delete mode 100644 content/docs/references/data/datasource.mdx delete mode 100644 content/docs/references/data/document.mdx delete mode 100644 content/docs/references/data/driver-nosql.mdx delete mode 100644 content/docs/references/data/driver-sql.mdx delete mode 100644 content/docs/references/data/driver.mdx delete mode 100644 content/docs/references/data/external-lookup.mdx delete mode 100644 content/docs/references/data/field.mdx delete mode 100644 content/docs/references/data/filter.mdx delete mode 100644 content/docs/references/data/hook.mdx delete mode 100644 content/docs/references/data/mapping.mdx delete mode 100644 content/docs/references/data/meta.json delete mode 100644 content/docs/references/data/metrics.mdx delete mode 100644 content/docs/references/data/object.mdx delete mode 100644 content/docs/references/data/query.mdx delete mode 100644 content/docs/references/data/search-engine.mdx delete mode 100644 content/docs/references/data/validation.mdx delete mode 100644 content/docs/references/identity/identity.mdx delete mode 100644 content/docs/references/identity/meta.json delete mode 100644 content/docs/references/identity/organization.mdx delete mode 100644 content/docs/references/identity/role.mdx delete mode 100644 content/docs/references/identity/scim.mdx delete mode 100644 content/docs/references/integration/connector.mdx delete mode 100644 content/docs/references/integration/http.mdx delete mode 100644 content/docs/references/integration/mapping.mdx delete mode 100644 content/docs/references/integration/message-queue.mdx delete mode 100644 content/docs/references/integration/meta.json delete mode 100644 content/docs/references/integration/misc.mdx delete mode 100644 content/docs/references/integration/object-storage.mdx delete mode 100644 content/docs/references/kernel/context.mdx delete mode 100644 content/docs/references/kernel/events.mdx delete mode 100644 content/docs/references/kernel/feature.mdx delete mode 100644 content/docs/references/kernel/manifest.mdx delete mode 100644 content/docs/references/kernel/meta.json delete mode 100644 content/docs/references/kernel/metadata-persistence.mdx delete mode 100644 content/docs/references/kernel/package-registry.mdx delete mode 100644 content/docs/references/kernel/permission.mdx delete mode 100644 content/docs/references/kernel/plugin-capability.mdx delete mode 100644 content/docs/references/kernel/plugin-lifecycle-advanced.mdx delete mode 100644 content/docs/references/kernel/plugin-lifecycle-events.mdx delete mode 100644 content/docs/references/kernel/plugin-loading.mdx delete mode 100644 content/docs/references/kernel/plugin-registry.mdx delete mode 100644 content/docs/references/kernel/plugin-security-advanced.mdx delete mode 100644 content/docs/references/kernel/plugin-security.mdx delete mode 100644 content/docs/references/kernel/plugin-structure.mdx delete mode 100644 content/docs/references/kernel/plugin-validator.mdx delete mode 100644 content/docs/references/kernel/plugin-versioning.mdx delete mode 100644 content/docs/references/kernel/plugin.mdx delete mode 100644 content/docs/references/kernel/service-registry.mdx delete mode 100644 content/docs/references/kernel/startup-orchestrator.mdx delete mode 100644 content/docs/references/qa/meta.json delete mode 100644 content/docs/references/qa/testing.mdx delete mode 100644 content/docs/references/security/meta.json delete mode 100644 content/docs/references/security/permission.mdx delete mode 100644 content/docs/references/security/policy.mdx delete mode 100644 content/docs/references/security/rls.mdx delete mode 100644 content/docs/references/security/sharing.mdx delete mode 100644 content/docs/references/security/territory.mdx delete mode 100644 content/docs/references/shared/http.mdx delete mode 100644 content/docs/references/shared/identifiers.mdx delete mode 100644 content/docs/references/shared/mapping.mdx delete mode 100644 content/docs/references/shared/meta.json delete mode 100644 content/docs/references/shared/view.mdx create mode 100644 content/docs/references/studio/index.mdx delete mode 100644 content/docs/references/system/audit.mdx delete mode 100644 content/docs/references/system/auth-config.mdx delete mode 100644 content/docs/references/system/cache.mdx delete mode 100644 content/docs/references/system/change-management.mdx delete mode 100644 content/docs/references/system/collaboration.mdx delete mode 100644 content/docs/references/system/compliance.mdx delete mode 100644 content/docs/references/system/encryption.mdx delete mode 100644 content/docs/references/system/http-server.mdx delete mode 100644 content/docs/references/system/job.mdx delete mode 100644 content/docs/references/system/license.mdx delete mode 100644 content/docs/references/system/logging.mdx delete mode 100644 content/docs/references/system/masking.mdx delete mode 100644 content/docs/references/system/message-queue.mdx delete mode 100644 content/docs/references/system/meta.json delete mode 100644 content/docs/references/system/metadata-persistence.mdx delete mode 100644 content/docs/references/system/metrics.mdx delete mode 100644 content/docs/references/system/migration.mdx delete mode 100644 content/docs/references/system/notification.mdx delete mode 100644 content/docs/references/system/object-storage.mdx delete mode 100644 content/docs/references/system/registry-config.mdx delete mode 100644 content/docs/references/system/search-engine.mdx delete mode 100644 content/docs/references/system/service-registry.mdx delete mode 100644 content/docs/references/system/tenant.mdx delete mode 100644 content/docs/references/system/tracing.mdx delete mode 100644 content/docs/references/system/translation.mdx delete mode 100644 content/docs/references/system/worker.mdx delete mode 100644 content/docs/references/ui/action.mdx delete mode 100644 content/docs/references/ui/app.mdx delete mode 100644 content/docs/references/ui/chart.mdx delete mode 100644 content/docs/references/ui/component.mdx delete mode 100644 content/docs/references/ui/dashboard.mdx delete mode 100644 content/docs/references/ui/meta.json delete mode 100644 content/docs/references/ui/page.mdx delete mode 100644 content/docs/references/ui/report.mdx delete mode 100644 content/docs/references/ui/theme.mdx delete mode 100644 content/docs/references/ui/view.mdx delete mode 100644 content/docs/references/ui/widget.mdx diff --git a/content/docs/references/ai/agent-action.mdx b/content/docs/references/ai/agent-action.mdx deleted file mode 100644 index 77eb18e2e..000000000 --- a/content/docs/references/ai/agent-action.mdx +++ /dev/null @@ -1,607 +0,0 @@ ---- -title: Agent Action -description: Agent Action protocol schemas ---- - -AI Agent Action Protocol - -Defines how AI agents can interact with the UI by mapping natural language intents - -to structured UI actions. This enables agents to not only query data but also - -manipulate the interface, navigate between views, and trigger workflows. - -Architecture Alignment: - -- Salesforce Einstein: Action recommendations and automated UI interactions - -- ServiceNow Virtual Agent: UI action automation - -- Microsoft Power Virtual Agents: Bot actions and UI integration - -Use Cases: - -- "Open the new account form" → Navigate to form view - -- "Show me all active opportunities" → Navigate to list view with filter - -- "Create a new task for John" → Open form with pre-filled data - -- "Switch to the kanban view" → Change view mode - - -**Source:** `packages/spec/src/ai/agent-action.zod.ts` - - -## TypeScript Usage - -```typescript -import { AgentAction, AgentActionResult, AgentActionSequence, AgentActionSequenceResult, ComponentActionParams, ComponentActionType, ComponentAgentAction, DataActionParams, DataActionType, DataAgentAction, FormActionParams, FormActionType, FormAgentAction, IntentActionMapping, NavigationActionParams, NavigationActionType, NavigationAgentAction, TypedAgentAction, UIActionType, ViewActionParams, ViewActionType, ViewAgentAction, WorkflowActionParams, WorkflowActionType, WorkflowAgentAction } from '@objectstack/spec/ai'; -import type { AgentAction, AgentActionResult, AgentActionSequence, AgentActionSequenceResult, ComponentActionParams, ComponentActionType, ComponentAgentAction, DataActionParams, DataActionType, DataAgentAction, FormActionParams, FormActionType, FormAgentAction, IntentActionMapping, NavigationActionParams, NavigationActionType, NavigationAgentAction, TypedAgentAction, UIActionType, ViewActionParams, ViewActionType, ViewAgentAction, WorkflowActionParams, WorkflowActionType, WorkflowAgentAction } from '@objectstack/spec/ai'; - -// Validate data -const result = AgentAction.parse(data); -``` - ---- - -## AgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'navigate_to_object_list' \| 'navigate_to_object_form' \| 'navigate_to_record_detail' \| 'navigate_to_dashboard' \| 'navigate_to_report' \| 'navigate_to_app' \| 'navigate_back' \| 'navigate_home' \| 'open_tab' \| 'close_tab' \| 'change_view_mode' \| 'apply_filter' \| 'clear_filter' \| 'apply_sort' \| 'change_grouping' \| 'show_columns' \| 'expand_record' \| 'collapse_record' \| 'refresh_view' \| 'export_data' \| 'create_record' \| 'update_record' \| 'delete_record' \| 'fill_field' \| 'clear_field' \| 'submit_form' \| 'cancel_form' \| 'validate_form' \| 'save_draft' \| 'select_record' \| 'deselect_record' \| 'select_all' \| 'deselect_all' \| 'bulk_update' \| 'bulk_delete' \| 'bulk_export' \| 'trigger_flow' \| 'trigger_approval' \| 'trigger_webhook' \| 'run_report' \| 'send_email' \| 'send_notification' \| 'schedule_task' \| 'open_modal' \| 'close_modal' \| 'open_sidebar' \| 'close_sidebar' \| 'show_notification' \| 'hide_notification' \| 'open_dropdown' \| 'close_dropdown' \| 'toggle_section'>` | ✅ | Type of UI action to perform | -| **params** | `Object \| Object \| Object \| Object \| Object \| Object` | ✅ | Action-specific parameters | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - -## AgentActionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **actionId** | `string` | ✅ | ID of the executed action | -| **status** | `Enum<'success' \| 'error' \| 'cancelled' \| 'pending'>` | ✅ | Execution status | -| **data** | `any` | optional | Action result data | -| **error** | `Object` | optional | Error details if status is "error" | -| **metadata** | `Object` | optional | | - - ---- - -## AgentActionSequence - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique sequence ID | -| **actions** | `Object[]` | ✅ | Ordered list of actions | -| **mode** | `Enum<'sequential' \| 'parallel'>` | optional | Execution mode | -| **stopOnError** | `boolean` | optional | Stop sequence on first error | -| **atomic** | `boolean` | optional | Transaction mode (all-or-nothing) | -| **startTime** | `string` | optional | Execution start time (ISO 8601) | -| **endTime** | `string` | optional | Execution end time (ISO 8601) | -| **metadata** | `Object` | optional | | - - ---- - -## AgentActionSequenceResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sequenceId** | `string` | ✅ | ID of the executed sequence | -| **status** | `Enum<'success' \| 'partial_success' \| 'error' \| 'cancelled'>` | ✅ | Overall execution status | -| **results** | `Object[]` | ✅ | Results for each action | -| **summary** | `Object` | ✅ | | -| **metadata** | `Object` | optional | | - - ---- - -## ComponentActionParams - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **componentId** | `string` | optional | Component ID | -| **modalConfig** | `Object` | optional | | -| **notificationConfig** | `Object` | optional | | -| **sidebarConfig** | `Object` | optional | | - - ---- - -## ComponentActionType - -### Allowed Values - -* `open_modal` -* `close_modal` -* `open_sidebar` -* `close_sidebar` -* `show_notification` -* `hide_notification` -* `open_dropdown` -* `close_dropdown` -* `toggle_section` - - ---- - -## ComponentAgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'open_modal' \| 'close_modal' \| 'open_sidebar' \| 'close_sidebar' \| 'show_notification' \| 'hide_notification' \| 'open_dropdown' \| 'close_dropdown' \| 'toggle_section'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - -## DataActionParams - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **recordIds** | `string[]` | optional | Record IDs to select/operate on | -| **filters** | `Record` | optional | Filter for bulk operations | -| **updateData** | `Record` | optional | Data for bulk update | -| **exportFormat** | `Enum<'csv' \| 'xlsx' \| 'pdf' \| 'json'>` | optional | | - - ---- - -## DataActionType - -### Allowed Values - -* `select_record` -* `deselect_record` -* `select_all` -* `deselect_all` -* `bulk_update` -* `bulk_delete` -* `bulk_export` - - ---- - -## DataAgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'select_record' \| 'deselect_record' \| 'select_all' \| 'deselect_all' \| 'bulk_update' \| 'bulk_delete' \| 'bulk_export'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - -## FormActionParams - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | optional | Object name | -| **recordId** | `string` | optional | Record ID (for edit/delete) | -| **fieldValues** | `Record` | optional | Field name-value pairs | -| **fieldName** | `string` | optional | Specific field to fill/clear | -| **fieldValue** | `any` | optional | Value to set | -| **validateOnly** | `boolean` | optional | Validate without saving | - - ---- - -## FormActionType - -### Allowed Values - -* `create_record` -* `update_record` -* `delete_record` -* `fill_field` -* `clear_field` -* `submit_form` -* `cancel_form` -* `validate_form` -* `save_draft` - - ---- - -## FormAgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'create_record' \| 'update_record' \| 'delete_record' \| 'fill_field' \| 'clear_field' \| 'submit_form' \| 'cancel_form' \| 'validate_form' \| 'save_draft'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - -## IntentActionMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **intent** | `string` | ✅ | Intent pattern (e.g., "open_new_record_form") | -| **examples** | `string[]` | optional | Example user queries | -| **actionTemplate** | `Object` | ✅ | Action to execute | -| **paramExtraction** | `Record` | optional | Rules for extracting parameters from user input | -| **minConfidence** | `number` | optional | Minimum confidence to execute | - - ---- - -## NavigationActionParams - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | optional | Object name (for object-specific navigation) | -| **recordId** | `string` | optional | Record ID (for detail page) | -| **viewType** | `Enum<'list' \| 'form' \| 'detail' \| 'kanban' \| 'calendar' \| 'gantt'>` | optional | | -| **dashboardId** | `string` | optional | Dashboard ID | -| **reportId** | `string` | optional | Report ID | -| **appName** | `string` | optional | App name | -| **mode** | `Enum<'new' \| 'edit' \| 'view'>` | optional | Form mode | -| **openInNewTab** | `boolean` | optional | Open in new tab | - - ---- - -## NavigationActionType - -### Allowed Values - -* `navigate_to_object_list` -* `navigate_to_object_form` -* `navigate_to_record_detail` -* `navigate_to_dashboard` -* `navigate_to_report` -* `navigate_to_app` -* `navigate_back` -* `navigate_home` -* `open_tab` -* `close_tab` - - ---- - -## NavigationAgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'navigate_to_object_list' \| 'navigate_to_object_form' \| 'navigate_to_record_detail' \| 'navigate_to_dashboard' \| 'navigate_to_report' \| 'navigate_to_app' \| 'navigate_back' \| 'navigate_home' \| 'open_tab' \| 'close_tab'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - -## TypedAgentAction - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'navigate_to_object_list' \| 'navigate_to_object_form' \| 'navigate_to_record_detail' \| 'navigate_to_dashboard' \| 'navigate_to_report' \| 'navigate_to_app' \| 'navigate_back' \| 'navigate_home' \| 'open_tab' \| 'close_tab'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'change_view_mode' \| 'apply_filter' \| 'clear_filter' \| 'apply_sort' \| 'change_grouping' \| 'show_columns' \| 'expand_record' \| 'collapse_record' \| 'refresh_view' \| 'export_data'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - ---- - -#### Option 3 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'create_record' \| 'update_record' \| 'delete_record' \| 'fill_field' \| 'clear_field' \| 'submit_form' \| 'cancel_form' \| 'validate_form' \| 'save_draft'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - ---- - -#### Option 4 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'select_record' \| 'deselect_record' \| 'select_all' \| 'deselect_all' \| 'bulk_update' \| 'bulk_delete' \| 'bulk_export'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - ---- - -#### Option 5 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'trigger_flow' \| 'trigger_approval' \| 'trigger_webhook' \| 'run_report' \| 'send_email' \| 'send_notification' \| 'schedule_task'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - ---- - -#### Option 6 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'open_modal' \| 'close_modal' \| 'open_sidebar' \| 'close_sidebar' \| 'show_notification' \| 'hide_notification' \| 'open_dropdown' \| 'close_dropdown' \| 'toggle_section'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - ---- - - ---- - -## UIActionType - -### Allowed Values - -* `navigate_to_object_list` -* `navigate_to_object_form` -* `navigate_to_record_detail` -* `navigate_to_dashboard` -* `navigate_to_report` -* `navigate_to_app` -* `navigate_back` -* `navigate_home` -* `open_tab` -* `close_tab` -* `change_view_mode` -* `apply_filter` -* `clear_filter` -* `apply_sort` -* `change_grouping` -* `show_columns` -* `expand_record` -* `collapse_record` -* `refresh_view` -* `export_data` -* `create_record` -* `update_record` -* `delete_record` -* `fill_field` -* `clear_field` -* `submit_form` -* `cancel_form` -* `validate_form` -* `save_draft` -* `select_record` -* `deselect_record` -* `select_all` -* `deselect_all` -* `bulk_update` -* `bulk_delete` -* `bulk_export` -* `trigger_flow` -* `trigger_approval` -* `trigger_webhook` -* `run_report` -* `send_email` -* `send_notification` -* `schedule_task` -* `open_modal` -* `close_modal` -* `open_sidebar` -* `close_sidebar` -* `show_notification` -* `hide_notification` -* `open_dropdown` -* `close_dropdown` -* `toggle_section` - - ---- - -## ViewActionParams - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **viewMode** | `Enum<'list' \| 'kanban' \| 'calendar' \| 'gantt' \| 'pivot'>` | optional | | -| **filters** | `Record` | optional | Filter conditions | -| **sort** | `Object[]` | optional | | -| **groupBy** | `string` | optional | Field to group by | -| **columns** | `string[]` | optional | Columns to show/hide | -| **recordId** | `string` | optional | Record to expand/collapse | -| **exportFormat** | `Enum<'csv' \| 'xlsx' \| 'pdf' \| 'json'>` | optional | | - - ---- - -## ViewActionType - -### Allowed Values - -* `change_view_mode` -* `apply_filter` -* `clear_filter` -* `apply_sort` -* `change_grouping` -* `show_columns` -* `expand_record` -* `collapse_record` -* `refresh_view` -* `export_data` - - ---- - -## ViewAgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'change_view_mode' \| 'apply_filter' \| 'clear_filter' \| 'apply_sort' \| 'change_grouping' \| 'show_columns' \| 'expand_record' \| 'collapse_record' \| 'refresh_view' \| 'export_data'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - -## WorkflowActionParams - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **flowName** | `string` | optional | Flow/workflow name | -| **approvalProcessName** | `string` | optional | Approval process name | -| **webhookUrl** | `string` | optional | Webhook URL | -| **reportName** | `string` | optional | Report name | -| **emailTemplate** | `string` | optional | Email template | -| **recipients** | `string[]` | optional | Email recipients | -| **subject** | `string` | optional | Email subject | -| **message** | `string` | optional | Notification/email message | -| **taskData** | `Record` | optional | Task creation data | -| **scheduleTime** | `string` | optional | Schedule time (ISO 8601) | -| **contextData** | `Record` | optional | Additional context data | - - ---- - -## WorkflowActionType - -### Allowed Values - -* `trigger_flow` -* `trigger_approval` -* `trigger_webhook` -* `run_report` -* `send_email` -* `send_notification` -* `schedule_task` - - ---- - -## WorkflowAgentAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique action ID | -| **type** | `Enum<'trigger_flow' \| 'trigger_approval' \| 'trigger_webhook' \| 'run_report' \| 'send_email' \| 'send_notification' \| 'schedule_task'>` | ✅ | | -| **params** | `Object` | ✅ | | -| **requireConfirmation** | `boolean` | optional | Require user confirmation before executing | -| **confirmationMessage** | `string` | optional | Message to show in confirmation dialog | -| **successMessage** | `string` | optional | Message to show on success | -| **onError** | `Enum<'retry' \| 'skip' \| 'abort'>` | optional | Error handling strategy | -| **metadata** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/ai/agent.mdx b/content/docs/references/ai/agent.mdx deleted file mode 100644 index a1a104d2d..000000000 --- a/content/docs/references/ai/agent.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Agent -description: Agent protocol schemas ---- - -AI Model Configuration - - -**Source:** `packages/spec/src/ai/agent.zod.ts` - - -## TypeScript Usage - -```typescript -import { AIKnowledge, AIModelConfig, AITool, Agent } from '@objectstack/spec/ai'; -import type { AIKnowledge, AIModelConfig, AITool, Agent } from '@objectstack/spec/ai'; - -// Validate data -const result = AIKnowledge.parse(data); -``` - ---- - -## AIKnowledge - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **topics** | `string[]` | ✅ | Topics/Tags to recruit knowledge from | -| **indexes** | `string[]` | ✅ | Vector Store Indexes | - - ---- - -## AIModelConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>` | optional | | -| **model** | `string` | ✅ | Model name (e.g. gpt-4, claude-3-opus) | -| **temperature** | `number` | optional | | -| **maxTokens** | `number` | optional | | -| **topP** | `number` | optional | | - - ---- - -## AITool - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'action' \| 'flow' \| 'query' \| 'vector_search'>` | ✅ | | -| **name** | `string` | ✅ | Reference name (Action Name, Flow Name) | -| **description** | `string` | optional | Override description for the LLM | - - ---- - -## Agent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Agent unique identifier | -| **label** | `string` | ✅ | Agent display name | -| **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 | -| **tools** | `Object[]` | optional | Available tools | -| **knowledge** | `Object` | optional | RAG access | -| **active** | `boolean` | optional | | -| **access** | `string[]` | optional | Who can chat with this agent | -| **tenantId** | `string` | optional | Tenant/Organization ID | -| **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | optional | | - - ---- - diff --git a/content/docs/references/ai/conversation.mdx b/content/docs/references/ai/conversation.mdx deleted file mode 100644 index 80f0c828b..000000000 --- a/content/docs/references/ai/conversation.mdx +++ /dev/null @@ -1,385 +0,0 @@ ---- -title: Conversation -description: Conversation protocol schemas ---- - -AI Conversation Memory Protocol - -Multi-turn AI conversations with token budget management. - -Enables context preservation, conversation history, and token optimization. - - -**Source:** `packages/spec/src/ai/conversation.zod.ts` - - -## TypeScript Usage - -```typescript -import { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai'; -import type { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai'; - -// Validate data -const result = CodeContent.parse(data); -``` - ---- - -## CodeContent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **text** | `string` | ✅ | Code snippet | -| **language** | `string` | optional | | -| **metadata** | `Record` | optional | | - - ---- - -## ConversationAnalytics - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sessionId** | `string` | ✅ | | -| **totalMessages** | `integer` | ✅ | | -| **userMessages** | `integer` | ✅ | | -| **assistantMessages** | `integer` | ✅ | | -| **systemMessages** | `integer` | ✅ | | -| **totalTokens** | `integer` | ✅ | | -| **averageTokensPerMessage** | `number` | ✅ | | -| **peakTokenUsage** | `integer` | ✅ | | -| **pruningEvents** | `integer` | optional | | -| **summarizationEvents** | `integer` | optional | | -| **tokensSavedByPruning** | `integer` | optional | | -| **tokensSavedBySummarization** | `integer` | optional | | -| **duration** | `number` | optional | Session duration in seconds | -| **firstMessageAt** | `string` | optional | ISO 8601 timestamp | -| **lastMessageAt** | `string` | optional | ISO 8601 timestamp | - - ---- - -## ConversationContext - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sessionId** | `string` | ✅ | Conversation session ID | -| **userId** | `string` | optional | User identifier | -| **agentId** | `string` | optional | AI agent identifier | -| **object** | `string` | optional | Related object (e.g., "case", "project") | -| **recordId** | `string` | optional | Related record ID | -| **scope** | `Record` | optional | Additional context scope | -| **systemMessage** | `string` | optional | System prompt/instructions | -| **metadata** | `Record` | optional | | - - ---- - -## ConversationMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | -| **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 | -| **cost** | `number` | optional | Cost for this message in USD | -| **pinned** | `boolean` | optional | Prevent removal during pruning | -| **importance** | `number` | optional | Importance score for pruning | -| **embedding** | `number[]` | optional | Vector embedding for semantic search | -| **metadata** | `Record` | optional | | - - ---- - -## ConversationSession - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique session ID | -| **name** | `string` | optional | Session name/title | -| **context** | `Object` | ✅ | | -| **modelId** | `string` | optional | AI model ID | -| **tokenBudget** | `Object` | ✅ | | -| **messages** | `Object[]` | optional | | -| **tokens** | `Object` | optional | | -| **totalTokens** | `Object` | optional | Total tokens across all messages | -| **totalCost** | `number` | optional | Total cost for this session in USD | -| **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | optional | | -| **createdAt** | `string` | ✅ | ISO 8601 timestamp | -| **updatedAt** | `string` | ✅ | ISO 8601 timestamp | -| **expiresAt** | `string` | optional | ISO 8601 timestamp | -| **metadata** | `Record` | optional | | - - ---- - -## ConversationSummary - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **summary** | `string` | ✅ | Conversation summary | -| **keyPoints** | `string[]` | optional | Key discussion points | -| **originalTokens** | `integer` | ✅ | Original token count | -| **summaryTokens** | `integer` | ✅ | Summary token count | -| **tokensSaved** | `integer` | ✅ | Tokens saved | -| **messageRange** | `Object` | ✅ | Range of messages summarized | -| **generatedAt** | `string` | ✅ | ISO 8601 timestamp | -| **modelId** | `string` | optional | Model used for summarization | - - ---- - -## FileContent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **fileUrl** | `string` | ✅ | File attachment URL | -| **mimeType** | `string` | ✅ | MIME type | -| **fileName** | `string` | optional | | -| **metadata** | `Record` | optional | | - - ---- - -## FunctionCall - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Function name | -| **arguments** | `string` | ✅ | JSON string of function arguments | -| **result** | `string` | optional | Function execution result | - - ---- - -## ImageContent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **imageUrl** | `string` | ✅ | Image URL | -| **detail** | `Enum<'low' \| 'high' \| 'auto'>` | optional | | -| **metadata** | `Record` | optional | | - - ---- - -## MessageContent - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `text` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **text** | `string` | ✅ | Text content | -| **metadata** | `Record` | optional | | - ---- - -#### Option 2 - -**Type:** `image` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **imageUrl** | `string` | ✅ | Image URL | -| **detail** | `Enum<'low' \| 'high' \| 'auto'>` | optional | | -| **metadata** | `Record` | optional | | - ---- - -#### Option 3 - -**Type:** `file` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **fileUrl** | `string` | ✅ | File attachment URL | -| **mimeType** | `string` | ✅ | MIME type | -| **fileName** | `string` | optional | | -| **metadata** | `Record` | optional | | - ---- - -#### Option 4 - -**Type:** `code` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **text** | `string` | ✅ | Code snippet | -| **language** | `string` | optional | | -| **metadata** | `Record` | optional | | - ---- - - ---- - -## MessageContentType - -### Allowed Values - -* `text` -* `image` -* `file` -* `code` -* `structured` - - ---- - -## MessagePruningEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `string` | ✅ | Event timestamp | -| **prunedMessages** | `Object[]` | ✅ | | -| **tokensFreed** | `integer` | ✅ | | -| **messagesRemoved** | `integer` | ✅ | | -| **remainingTokens** | `integer` | ✅ | | -| **remainingMessages** | `integer` | ✅ | | - - ---- - -## MessageRole - -### Allowed Values - -* `system` -* `user` -* `assistant` -* `function` -* `tool` - - ---- - -## TextContent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **text** | `string` | ✅ | Text content | -| **metadata** | `Record` | optional | | - - ---- - -## TokenBudgetConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxTokens** | `integer` | ✅ | Maximum total tokens | -| **maxPromptTokens** | `integer` | optional | Max tokens for prompt | -| **maxCompletionTokens** | `integer` | optional | Max tokens for completion | -| **reserveTokens** | `integer` | optional | Reserve tokens for system messages | -| **bufferPercentage** | `number` | optional | Buffer percentage (0.1 = 10%) | -| **strategy** | `Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>` | optional | | -| **slidingWindowSize** | `integer` | optional | Number of recent messages to keep | -| **minImportanceScore** | `number` | optional | Minimum importance to keep | -| **semanticThreshold** | `number` | optional | Semantic similarity threshold | -| **enableSummarization** | `boolean` | optional | Enable context summarization | -| **summarizationThreshold** | `integer` | optional | Trigger summarization at N tokens | -| **summaryModel** | `string` | optional | Model ID for summarization | -| **warnThreshold** | `number` | optional | Warn at % of budget (0.8 = 80%) | - - ---- - -## TokenBudgetStrategy - -### Allowed Values - -* `fifo` -* `importance` -* `semantic` -* `sliding_window` -* `summary` - - ---- - -## TokenUsageStats - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **promptTokens** | `integer` | optional | | -| **completionTokens** | `integer` | optional | | -| **totalTokens** | `integer` | optional | | -| **budgetLimit** | `integer` | ✅ | | -| **budgetUsed** | `integer` | optional | | -| **budgetRemaining** | `integer` | ✅ | | -| **budgetPercentage** | `number` | ✅ | Usage as percentage of budget | -| **messageCount** | `integer` | optional | | -| **prunedMessageCount** | `integer` | optional | | -| **summarizedMessageCount** | `integer` | optional | | - - ---- - -## ToolCall - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Tool call ID | -| **type** | `Enum<'function'>` | optional | | -| **function** | `Object` | ✅ | | - - ---- - diff --git a/content/docs/references/ai/cost.mdx b/content/docs/references/ai/cost.mdx deleted file mode 100644 index cb8c85d1e..000000000 --- a/content/docs/references/ai/cost.mdx +++ /dev/null @@ -1,367 +0,0 @@ ---- -title: Cost -description: Cost protocol schemas ---- - -AI Cost Tracking Protocol - -Monitor and control AI API costs with budgets, alerts, and analytics. - -Provides cost optimization, budget enforcement, and financial reporting. - - -**Source:** `packages/spec/src/ai/cost.zod.ts` - - -## TypeScript Usage - -```typescript -import { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai'; -import type { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai'; - -// Validate data -const result = AIOperationCost.parse(data); -``` - ---- - -## AIOperationCost - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operationId** | `string` | ✅ | | -| **operationType** | `Enum<'conversation' \| 'orchestration' \| 'prediction' \| 'rag' \| 'nlq'>` | ✅ | | -| **agentName** | `string` | optional | Agent that performed the operation | -| **modelId** | `string` | ✅ | | -| **tokens** | `Object` | ✅ | | -| **cost** | `number` | ✅ | Cost in USD | -| **timestamp** | `string` | ✅ | | -| **metadata** | `Record` | optional | | - - ---- - -## BillingPeriod - -### Allowed Values - -* `hourly` -* `daily` -* `weekly` -* `monthly` -* `quarterly` -* `yearly` -* `custom` - - ---- - -## BudgetLimit - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | ✅ | | -| **scope** | `string` | optional | Scope identifier (userId, agentId, etc.) | -| **maxCost** | `number` | ✅ | Maximum cost limit | -| **currency** | `string` | optional | | -| **period** | `Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>` | ✅ | | -| **customPeriodDays** | `integer` | optional | Custom period in days | -| **softLimit** | `number` | optional | Soft limit for warnings | -| **warnThresholds** | `number[]` | optional | Warning thresholds (e.g., [0.5, 0.8, 0.95]) | -| **enforced** | `boolean` | optional | Block requests when exceeded | -| **gracePeriodSeconds** | `integer` | optional | Grace period after limit exceeded | -| **allowRollover** | `boolean` | optional | Allow unused budget to rollover | -| **maxRolloverPercentage** | `number` | optional | Max rollover as % of limit | -| **name** | `string` | optional | Budget name | -| **description** | `string` | optional | | -| **active** | `boolean` | optional | | -| **tags** | `string[]` | optional | | - - ---- - -## BudgetStatus - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **budgetId** | `string` | ✅ | | -| **type** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | ✅ | | -| **scope** | `string` | optional | | -| **periodStart** | `string` | ✅ | ISO 8601 timestamp | -| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | -| **currentCost** | `number` | optional | | -| **maxCost** | `number` | ✅ | | -| **currency** | `string` | optional | | -| **percentageUsed** | `number` | ✅ | Usage as percentage (can exceed 1.0 if over budget) | -| **remainingCost** | `number` | ✅ | Remaining budget (can be negative if exceeded) | -| **isExceeded** | `boolean` | optional | | -| **isWarning** | `boolean` | optional | | -| **projectedCost** | `number` | optional | Projected cost for period | -| **projectedOverage** | `number` | optional | Projected overage | -| **lastUpdated** | `string` | ✅ | ISO 8601 timestamp | - - ---- - -## BudgetType - -### Allowed Values - -* `global` -* `user` -* `agent` -* `object` -* `project` -* `department` - - ---- - -## CostAlert - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **type** | `Enum<'threshold_warning' \| 'threshold_critical' \| 'limit_exceeded' \| 'anomaly_detected' \| 'projection_exceeded'>` | ✅ | | -| **severity** | `Enum<'info' \| 'warning' \| 'critical'>` | ✅ | | -| **budgetId** | `string` | optional | | -| **budgetType** | `Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>` | optional | | -| **scope** | `string` | optional | | -| **message** | `string` | ✅ | Alert message | -| **currentCost** | `number` | ✅ | | -| **maxCost** | `number` | optional | | -| **threshold** | `number` | optional | | -| **currency** | `string` | optional | | -| **recommendations** | `string[]` | optional | | -| **acknowledged** | `boolean` | optional | | -| **acknowledgedBy** | `string` | optional | | -| **acknowledgedAt** | `string` | optional | | -| **resolved** | `boolean` | optional | | -| **metadata** | `Record` | optional | | - - ---- - -## CostAlertType - -### Allowed Values - -* `threshold_warning` -* `threshold_critical` -* `limit_exceeded` -* `anomaly_detected` -* `projection_exceeded` - - ---- - -## CostAnalytics - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **periodStart** | `string` | ✅ | ISO 8601 timestamp | -| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | -| **totalCost** | `number` | ✅ | | -| **totalRequests** | `integer` | ✅ | | -| **totalTokens** | `integer` | optional | | -| **currency** | `string` | optional | | -| **averageCostPerRequest** | `number` | ✅ | | -| **averageCostPerToken** | `number` | optional | | -| **averageRequestsPerDay** | `number` | ✅ | | -| **costTrend** | `Enum<'increasing' \| 'decreasing' \| 'stable'>` | optional | | -| **trendPercentage** | `number` | optional | % change vs previous period | -| **byModel** | `Object[]` | optional | | -| **byProvider** | `Object[]` | optional | | -| **byUser** | `Object[]` | optional | | -| **byAgent** | `Object[]` | optional | | -| **byOperation** | `Object[]` | optional | | -| **byDate** | `Object[]` | optional | | -| **topModels** | `Object[]` | optional | | -| **topUsers** | `Object[]` | optional | | -| **topAgents** | `Object[]` | optional | | -| **tokensPerDollar** | `number` | optional | | -| **requestsPerDollar** | `number` | optional | | - - ---- - -## CostBreakdownDimension - -### Allowed Values - -* `model` -* `provider` -* `user` -* `agent` -* `object` -* `operation` -* `date` -* `hour` -* `tag` - - ---- - -## CostBreakdownEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **dimension** | `Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>` | ✅ | | -| **value** | `string` | ✅ | Dimension value (e.g., model ID, user ID) | -| **totalCost** | `number` | ✅ | | -| **requestCount** | `integer` | ✅ | | -| **totalTokens** | `integer` | optional | | -| **percentageOfTotal** | `number` | ✅ | | -| **periodStart** | `string` | optional | | -| **periodEnd** | `string` | optional | | - - ---- - -## CostEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique cost entry ID | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **modelId** | `string` | ✅ | AI model used | -| **provider** | `string` | ✅ | AI provider (e.g., "openai", "anthropic") | -| **operation** | `string` | ✅ | Operation type (e.g., "chat_completion", "embedding") | -| **tokens** | `Object` | optional | Standardized token usage | -| **requestCount** | `integer` | optional | | -| **promptCost** | `number` | optional | Cost of prompt tokens | -| **completionCost** | `number` | optional | Cost of completion tokens | -| **totalCost** | `number` | ✅ | Total cost in base currency | -| **currency** | `string` | optional | | -| **sessionId** | `string` | optional | Conversation session ID | -| **userId** | `string` | optional | User who triggered the request | -| **agentId** | `string` | optional | AI agent ID | -| **object** | `string` | optional | Related object (e.g., "case", "project") | -| **recordId** | `string` | optional | Related record ID | -| **tags** | `string[]` | optional | | -| **metadata** | `Record` | optional | | - - ---- - -## CostMetricType - -### Allowed Values - -* `token` -* `request` -* `character` -* `second` -* `image` -* `embedding` - - ---- - -## CostOptimizationRecommendation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **type** | `Enum<'switch_model' \| 'reduce_tokens' \| 'batch_requests' \| 'cache_results' \| 'adjust_parameters' \| 'limit_usage'>` | ✅ | | -| **title** | `string` | ✅ | | -| **description** | `string` | ✅ | | -| **estimatedSavings** | `number` | optional | | -| **savingsPercentage** | `number` | optional | | -| **priority** | `Enum<'low' \| 'medium' \| 'high'>` | ✅ | | -| **effort** | `Enum<'low' \| 'medium' \| 'high'>` | ✅ | | -| **actionable** | `boolean` | optional | | -| **actionSteps** | `string[]` | optional | | -| **targetModel** | `string` | optional | | -| **alternativeModel** | `string` | optional | | -| **affectedUsers** | `string[]` | optional | | -| **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'implemented'>` | optional | | -| **implementedAt** | `string` | optional | | - - ---- - -## CostQueryFilters - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **startDate** | `string` | optional | ISO 8601 timestamp | -| **endDate** | `string` | optional | ISO 8601 timestamp | -| **modelIds** | `string[]` | optional | | -| **providers** | `string[]` | optional | | -| **userIds** | `string[]` | optional | | -| **agentIds** | `string[]` | optional | | -| **operations** | `string[]` | optional | | -| **sessionIds** | `string[]` | optional | | -| **minCost** | `number` | optional | | -| **maxCost** | `number` | optional | | -| **tags** | `string[]` | optional | | -| **groupBy** | `Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>[]` | optional | | -| **orderBy** | `Enum<'timestamp' \| 'cost' \| 'tokens'>` | optional | | -| **orderDirection** | `Enum<'asc' \| 'desc'>` | optional | | -| **limit** | `integer` | optional | | -| **offset** | `integer` | optional | | - - ---- - -## CostReport - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **generatedAt** | `string` | ✅ | ISO 8601 timestamp | -| **periodStart** | `string` | ✅ | ISO 8601 timestamp | -| **periodEnd** | `string` | ✅ | ISO 8601 timestamp | -| **period** | `Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>` | ✅ | | -| **analytics** | `Object` | ✅ | | -| **budgets** | `Object[]` | optional | | -| **alerts** | `Object[]` | optional | | -| **activeAlertCount** | `integer` | optional | | -| **recommendations** | `Object[]` | optional | | -| **previousPeriodCost** | `number` | optional | | -| **costChange** | `number` | optional | Change vs previous period | -| **costChangePercentage** | `number` | optional | | -| **forecastedCost** | `number` | optional | | -| **forecastedBudgetStatus** | `Enum<'under' \| 'at' \| 'over'>` | optional | | -| **format** | `Enum<'summary' \| 'detailed' \| 'executive'>` | optional | | -| **currency** | `string` | optional | | - - ---- - -## TokenUsage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **prompt** | `integer` | ✅ | Input tokens | -| **completion** | `integer` | ✅ | Output tokens | -| **total** | `integer` | ✅ | Total tokens | - - ---- - diff --git a/content/docs/references/ai/devops-agent.mdx b/content/docs/references/ai/devops-agent.mdx deleted file mode 100644 index 353b69441..000000000 --- a/content/docs/references/ai/devops-agent.mdx +++ /dev/null @@ -1,344 +0,0 @@ ---- -title: Devops Agent -description: Devops Agent protocol schemas ---- - -DevOps Agent Protocol - -Defines autonomous DevOps agents that can self-iterate on enterprise - -management software development using the ObjectStack specification. - -This agent integrates with GitHub for version control and Vercel for - -deployment, enabling fully automated development, testing, and release cycles. - -Architecture: - -- Self-iterating development based on ObjectStack specifications - -- Automated code generation following best practices - -- Continuous integration and deployment - -- Version management and release automation - -- Monitoring and rollback capabilities - -Use Cases: - -- Automated feature development from specifications - -- Self-healing code based on test failures - -- Automated dependency updates - -- Continuous optimization and refactoring - -- Automated documentation generation - -@example - -```typescript - -import { DevOpsAgent } from '@objectstack/spec/ai'; - -const agent: DevOpsAgent = { - -name: 'devops_automation_agent', - -label: 'DevOps Automation Agent', - -role: 'Senior Full-Stack DevOps Engineer', - -instructions: '...', - -developmentConfig: { - -specificationSource: 'packages/spec', - -codeGeneration: { - -enabled: true, - -targets: ['frontend', 'backend', 'api'], - -}, - -}, - -integrations: { - -github: { - -connector: 'github_production', - -repository: { - -owner: 'objectstack-ai', - -name: 'app', - -}, - -}, - -vercel: { - -connector: 'vercel_production', - -project: 'objectstack-app', - -}, - -}, - -}; - -``` - - -**Source:** `packages/spec/src/ai/devops-agent.zod.ts` - - -## TypeScript Usage - -```typescript -import { CICDPipelineConfig, CodeGenerationConfig, CodeGenerationTarget, DeploymentStrategy, DevOpsAgent, DevOpsTool, DevelopmentConfig, GitHubIntegration, IntegrationConfig, MonitoringConfig, PipelineStage, TestingConfig, VercelIntegration, VersionManagement } from '@objectstack/spec/ai'; -import type { CICDPipelineConfig, CodeGenerationConfig, CodeGenerationTarget, DeploymentStrategy, DevOpsAgent, DevOpsTool, DevelopmentConfig, GitHubIntegration, IntegrationConfig, MonitoringConfig, PipelineStage, TestingConfig, VercelIntegration, VersionManagement } from '@objectstack/spec/ai'; - -// Validate data -const result = CICDPipelineConfig.parse(data); -``` - ---- - -## CICDPipelineConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Pipeline name | -| **trigger** | `Enum<'push' \| 'pull_request' \| 'release' \| 'schedule' \| 'manual'>` | ✅ | Pipeline trigger | -| **branches** | `string[]` | optional | Branches to run pipeline on | -| **stages** | `Object[]` | ✅ | Pipeline stages | -| **notifications** | `Object` | optional | Pipeline notifications | - - ---- - -## CodeGenerationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable code generation | -| **targets** | `Enum<'frontend' \| 'backend' \| 'api' \| 'database' \| 'tests' \| 'documentation' \| 'infrastructure'>[]` | ✅ | Code generation targets | -| **templateRepo** | `string` | optional | Template repository for scaffolding | -| **styleGuide** | `string` | optional | Code style guide to follow | -| **includeTests** | `boolean` | optional | Generate tests with code | -| **includeDocumentation** | `boolean` | optional | Generate documentation | -| **validationMode** | `Enum<'strict' \| 'moderate' \| 'permissive'>` | optional | Code validation strictness | - - ---- - -## CodeGenerationTarget - -Code generation target - -### Allowed Values - -* `frontend` -* `backend` -* `api` -* `database` -* `tests` -* `documentation` -* `infrastructure` - - ---- - -## DeploymentStrategy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'rolling' \| 'blue_green' \| 'canary' \| 'recreate'>` | optional | Deployment strategy | -| **canaryPercentage** | `number` | optional | Canary deployment percentage | -| **healthCheckUrl** | `string` | optional | Health check endpoint | -| **healthCheckTimeout** | `integer` | optional | Health check timeout in seconds | -| **autoRollback** | `boolean` | optional | Automatically rollback on failure | -| **smokeTests** | `string[]` | optional | Smoke test commands to run post-deployment | - - ---- - -## DevOpsAgent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Agent unique identifier | -| **label** | `string` | ✅ | Agent display name | -| **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 | -| **tools** | `Object[]` | optional | Available tools | -| **knowledge** | `Object` | optional | RAG access | -| **active** | `boolean` | optional | | -| **access** | `string[]` | optional | Who can chat with this agent | -| **tenantId** | `string` | optional | Tenant/Organization ID | -| **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | optional | | -| **developmentConfig** | `Object` | ✅ | Development configuration | -| **pipelines** | `Object[]` | optional | CI/CD pipelines | -| **versionManagement** | `Object` | optional | Version management configuration | -| **deploymentStrategy** | `Object` | optional | Deployment strategy | -| **monitoring** | `Object` | optional | Monitoring configuration | -| **integrations** | `Object` | ✅ | Integration configurations | -| **selfIteration** | `Object` | optional | Self-iteration configuration | - - ---- - -## DevOpsTool - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'action' \| 'flow' \| 'query' \| 'vector_search' \| 'git_operation' \| 'code_generation' \| 'test_execution' \| 'deployment' \| 'monitoring'>` | ✅ | | -| **name** | `string` | ✅ | Reference name (Action Name, Flow Name) | -| **description** | `string` | optional | Override description for the LLM | - - ---- - -## DevelopmentConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **specificationSource** | `string` | ✅ | Path to ObjectStack specification | -| **codeGeneration** | `Object` | ✅ | Code generation settings | -| **testing** | `Object` | optional | Testing configuration | -| **linting** | `Object` | optional | Code linting configuration | -| **formatting** | `Object` | optional | Code formatting configuration | - - ---- - -## GitHubIntegration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **connector** | `string` | ✅ | GitHub connector name | -| **repository** | `Object` | ✅ | Repository configuration | -| **featureBranch** | `string` | optional | Default feature branch | -| **pullRequest** | `Object` | optional | Pull request settings | - - ---- - -## IntegrationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **github** | `Object` | ✅ | GitHub integration configuration | -| **vercel** | `Object` | ✅ | Vercel integration configuration | -| **additional** | `Record` | optional | Additional integration configurations | - - ---- - -## MonitoringConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable monitoring | -| **metrics** | `Enum<'performance' \| 'errors' \| 'usage' \| 'availability' \| 'latency'>[]` | optional | Metrics to monitor | -| **alerts** | `Object[]` | optional | Alert configurations | -| **integrations** | `string[]` | optional | Monitoring service integrations | - - ---- - -## PipelineStage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Pipeline stage name | -| **type** | `Enum<'build' \| 'test' \| 'lint' \| 'security_scan' \| 'deploy' \| 'smoke_test' \| 'rollback'>` | ✅ | Stage type | -| **order** | `integer` | ✅ | Execution order | -| **parallel** | `boolean` | optional | Can run in parallel with other stages | -| **commands** | `string[]` | ✅ | Commands to execute | -| **env** | `Record` | optional | Stage-specific environment variables | -| **timeout** | `integer` | optional | Stage timeout in seconds | -| **retryOnFailure** | `boolean` | optional | Retry stage on failure | -| **maxRetries** | `integer` | optional | Maximum retry attempts | - - ---- - -## TestingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable automated testing | -| **testTypes** | `Enum<'unit' \| 'integration' \| 'e2e' \| 'performance' \| 'security' \| 'accessibility'>[]` | optional | Types of tests to run | -| **coverageThreshold** | `number` | optional | Minimum test coverage percentage | -| **framework** | `string` | optional | Testing framework (e.g., vitest, jest, playwright) | -| **preCommitTests** | `boolean` | optional | Run tests before committing | -| **autoFix** | `boolean` | optional | Attempt to auto-fix failing tests | - - ---- - -## VercelIntegration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **connector** | `string` | ✅ | Vercel connector name | -| **project** | `string` | ✅ | Vercel project name | -| **environments** | `Object` | optional | Environment mapping | -| **deployment** | `Object` | optional | Deployment settings | - - ---- - -## VersionManagement - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **scheme** | `Enum<'semver' \| 'calver' \| 'custom'>` | optional | Versioning scheme | -| **autoIncrement** | `Enum<'major' \| 'minor' \| 'patch' \| 'none'>` | optional | Auto-increment strategy | -| **prefix** | `string` | optional | Version tag prefix | -| **generateChangelog** | `boolean` | optional | Generate changelog automatically | -| **changelogFormat** | `Enum<'conventional' \| 'keepachangelog' \| 'custom'>` | optional | Changelog format | -| **tagReleases** | `boolean` | optional | Create Git tags for releases | - - ---- - diff --git a/content/docs/references/ai/feedback-loop.mdx b/content/docs/references/ai/feedback-loop.mdx deleted file mode 100644 index 5b537e7f5..000000000 --- a/content/docs/references/ai/feedback-loop.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Feedback Loop -description: Feedback Loop protocol schemas ---- - - -**Source:** `packages/spec/src/ai/feedback-loop.zod.ts` - - -## TypeScript Usage - -```typescript -import { FeedbackLoop, Issue, MetadataSource, Resolution } from '@objectstack/spec/ai'; -import type { FeedbackLoop, Issue, MetadataSource, Resolution } from '@objectstack/spec/ai'; - -// Validate data -const result = FeedbackLoop.parse(data); -``` - ---- - -## FeedbackLoop - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **issue** | `Object` | ✅ | | -| **analysis** | `string` | optional | AI analysis of the root cause | -| **resolutions** | `Object[]` | optional | | -| **status** | `Enum<'open' \| 'analyzing' \| 'resolved' \| 'ignored'>` | optional | | - - ---- - -## Issue - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **severity** | `Enum<'critical' \| 'error' \| 'warning' \| 'info'>` | ✅ | | -| **message** | `string` | ✅ | | -| **stackTrace** | `string` | optional | | -| **timestamp** | `string` | ✅ | | -| **userId** | `string` | optional | | -| **context** | `Record` | optional | | -| **source** | `Object` | optional | | - - ---- - -## MetadataSource - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **file** | `string` | optional | | -| **line** | `number` | optional | | -| **column** | `number` | optional | | -| **package** | `string` | optional | | -| **object** | `string` | optional | | -| **field** | `string` | optional | | -| **component** | `string` | optional | | - - ---- - -## Resolution - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **issueId** | `string` | ✅ | | -| **reasoning** | `string` | ✅ | Explanation of why this fix is needed | -| **confidence** | `number` | ✅ | | -| **fix** | `Object \| Object` | ✅ | | - - ---- - diff --git a/content/docs/references/ai/index.mdx b/content/docs/references/ai/index.mdx index eeaf09ebb..b633a74c3 100644 --- a/content/docs/references/ai/index.mdx +++ b/content/docs/references/ai/index.mdx @@ -12,6 +12,7 @@ This section contains all protocol schemas for the ai layer of ObjectStack. + diff --git a/content/docs/references/ai/meta.json b/content/docs/references/ai/meta.json deleted file mode 100644 index cd6ee502e..000000000 --- a/content/docs/references/ai/meta.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "title": "AI Protocol", - "pages": [ - "agent", - "agent-action", - "conversation", - "cost", - "devops-agent", - "feedback-loop", - "model-registry", - "nlq", - "orchestration", - "plugin-development", - "predictive", - "rag-pipeline", - "runtime-ops" - ] -} \ No newline at end of file diff --git a/content/docs/references/ai/model-registry.mdx b/content/docs/references/ai/model-registry.mdx deleted file mode 100644 index eb5106426..000000000 --- a/content/docs/references/ai/model-registry.mdx +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Model Registry -description: Model Registry protocol schemas ---- - -AI Model Registry Protocol - -Centralized registry for managing AI models, prompt templates, and model versioning. - -Enables AI-powered ObjectStack applications to discover and use LLMs consistently. - - -**Source:** `packages/spec/src/ai/model-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; -import type { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; - -// Validate data -const result = ModelCapability.parse(data); -``` - ---- - -## ModelCapability - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **textGeneration** | `boolean` | optional | Supports text generation | -| **textEmbedding** | `boolean` | optional | Supports text embedding | -| **imageGeneration** | `boolean` | optional | Supports image generation | -| **imageUnderstanding** | `boolean` | optional | Supports image understanding | -| **functionCalling** | `boolean` | optional | Supports function calling | -| **codeGeneration** | `boolean` | optional | Supports code generation | -| **reasoning** | `boolean` | optional | Supports advanced reasoning | - - ---- - -## ModelConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique model identifier | -| **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 | | -| **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) | -| **region** | `string` | optional | Deployment region (e.g., "us-east-1") | -| **description** | `string` | optional | | -| **tags** | `string[]` | optional | Tags for categorization | -| **deprecated** | `boolean` | optional | | -| **recommendedFor** | `string[]` | optional | Use case recommendations | - - ---- - -## ModelLimits - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxTokens** | `integer` | ✅ | Maximum tokens per request | -| **contextWindow** | `integer` | ✅ | Context window size | -| **maxOutputTokens** | `integer` | optional | Maximum output tokens | -| **rateLimit** | `Object` | optional | | - - ---- - -## ModelPricing - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **currency** | `string` | optional | | -| **inputCostPer1kTokens** | `number` | optional | Cost per 1K input tokens | -| **outputCostPer1kTokens** | `number` | optional | Cost per 1K output tokens | -| **embeddingCostPer1kTokens** | `number` | optional | Cost per 1K embedding tokens | - - ---- - -## ModelProvider - -### Allowed Values - -* `openai` -* `azure_openai` -* `anthropic` -* `google` -* `cohere` -* `huggingface` -* `local` -* `custom` - - ---- - -## ModelRegistry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Registry name | -| **models** | `Record` | ✅ | Model entries by ID | -| **promptTemplates** | `Record` | optional | Prompt templates by name | -| **defaultModel** | `string` | optional | Default model ID | -| **enableAutoFallback** | `boolean` | optional | Auto-fallback on errors | - - ---- - -## ModelRegistryEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **model** | `Object` | ✅ | | -| **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>` | optional | | -| **priority** | `integer` | optional | Priority for model selection | -| **fallbackModels** | `string[]` | optional | Fallback model IDs | -| **healthCheck** | `Object` | optional | | - - ---- - -## ModelSelectionCriteria - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **capabilities** | `string[]` | optional | Required capabilities | -| **maxCostPer1kTokens** | `number` | optional | Maximum acceptable cost | -| **minContextWindow** | `number` | optional | Minimum context window size | -| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | optional | | -| **tags** | `string[]` | optional | | -| **excludeDeprecated** | `boolean` | optional | | - - ---- - -## PromptTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique template identifier | -| **name** | `string` | ✅ | Template name (snake_case) | -| **label** | `string` | ✅ | Display name | -| **system** | `string` | optional | System prompt | -| **user** | `string` | ✅ | User prompt template with variables | -| **assistant** | `string` | optional | Assistant message prefix | -| **variables** | `Object[]` | optional | Template variables | -| **modelId** | `string` | optional | Recommended model ID | -| **temperature** | `number` | optional | | -| **maxTokens** | `number` | optional | | -| **topP** | `number` | optional | | -| **frequencyPenalty** | `number` | optional | | -| **presencePenalty** | `number` | optional | | -| **stopSequences** | `string[]` | optional | | -| **version** | `string` | optional | | -| **description** | `string` | optional | | -| **category** | `string` | optional | Template category (e.g., "code_generation", "support") | -| **tags** | `string[]` | optional | | -| **examples** | `Object[]` | optional | | - - ---- - -## PromptVariable - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Variable name (e.g., "user_name", "context") | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>` | optional | | -| **required** | `boolean` | optional | | -| **defaultValue** | `any` | optional | | -| **description** | `string` | optional | | -| **validation** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/ai/nlq.mdx b/content/docs/references/ai/nlq.mdx deleted file mode 100644 index 38f15d3a3..000000000 --- a/content/docs/references/ai/nlq.mdx +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: Nlq -description: Nlq protocol schemas ---- - -Natural Language Query (NLQ) Protocol - -Transforms natural language queries into ObjectQL AST (Abstract Syntax Tree). - -Enables business users to query data using natural language instead of writing code. - - -**Source:** `packages/spec/src/ai/nlq.zod.ts` - - -## TypeScript Usage - -```typescript -import { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai'; -import type { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai'; - -// Validate data -const result = Entity.parse(data); -``` - ---- - -## Entity - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'object' \| 'field' \| 'value' \| 'operator' \| 'function' \| 'timeframe'>` | ✅ | | -| **text** | `string` | ✅ | Original text from query | -| **value** | `any` | optional | Normalized value | -| **confidence** | `number` | ✅ | Confidence score | -| **span** | `any[]` | optional | Character span in query | - - ---- - -## FieldSynonymConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **field** | `string` | ✅ | Field name | -| **synonyms** | `string[]` | ✅ | Natural language synonyms | -| **examples** | `string[]` | optional | Example queries using synonyms | - - ---- - -## NLQAnalytics - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **totalQueries** | `integer` | ✅ | | -| **successfulQueries** | `integer` | ✅ | | -| **failedQueries** | `integer` | ✅ | | -| **averageConfidence** | `number` | ✅ | | -| **intentDistribution** | `Record` | ✅ | Count by intent type | -| **topQueries** | `Object[]` | ✅ | | -| **averageParseTime** | `number` | ✅ | Average parse time in milliseconds | -| **averageExecutionTime** | `number` | optional | | -| **lowConfidenceQueries** | `Object[]` | ✅ | | -| **startDate** | `string` | ✅ | ISO timestamp | -| **endDate** | `string` | ✅ | ISO timestamp | - - ---- - -## NLQFieldMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **naturalLanguage** | `string` | ✅ | NL field name (e.g., "customer name") | -| **objectField** | `string` | ✅ | Actual field name (e.g., "account.name") | -| **object** | `string` | ✅ | Object name | -| **field** | `string` | ✅ | Field name | -| **confidence** | `number` | ✅ | | - - ---- - -## NLQModelConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelId** | `string` | ✅ | Model from registry | -| **systemPrompt** | `string` | optional | System prompt override | -| **includeSchema** | `boolean` | optional | Include object schema in prompt | -| **includeExamples** | `boolean` | optional | Include examples in prompt | -| **enableIntentDetection** | `boolean` | optional | | -| **intentThreshold** | `number` | optional | | -| **enableEntityRecognition** | `boolean` | optional | | -| **entityRecognitionModel** | `string` | optional | | -| **enableFuzzyMatching** | `boolean` | optional | Fuzzy match field names | -| **fuzzyMatchThreshold** | `number` | optional | | -| **enableTimeframeDetection** | `boolean` | optional | | -| **defaultTimeframe** | `string` | optional | Default timeframe if not specified | -| **enableCaching** | `boolean` | optional | | -| **cacheTTL** | `integer` | optional | Cache TTL in seconds | - - ---- - -## NLQParseResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **originalQuery** | `string` | ✅ | | -| **intent** | `Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>` | ✅ | | -| **intentConfidence** | `number` | ✅ | | -| **entities** | `Object[]` | ✅ | | -| **targetObject** | `string` | optional | Primary object to query | -| **fields** | `Object[]` | optional | | -| **timeframe** | `Object` | optional | | -| **ast** | `Record` | ✅ | Generated ObjectQL AST | -| **confidence** | `number` | ✅ | Overall confidence | -| **ambiguities** | `Object[]` | optional | Detected ambiguities requiring clarification | -| **alternatives** | `Object[]` | optional | | - - ---- - -## NLQRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | Natural language query | -| **context** | `Object` | optional | | -| **includeAlternatives** | `boolean` | optional | Include alternative interpretations | -| **maxAlternatives** | `integer` | optional | | -| **minConfidence** | `number` | optional | Minimum confidence threshold | -| **executeQuery** | `boolean` | optional | Execute query and return results | -| **maxResults** | `integer` | optional | Maximum results to return | - - ---- - -## NLQResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **parseResult** | `Object` | ✅ | | -| **results** | `Record[]` | optional | Query results | -| **totalCount** | `integer` | optional | | -| **executionTime** | `number` | optional | Execution time in milliseconds | -| **needsClarification** | `boolean` | ✅ | Whether query needs clarification | -| **tokens** | `Object` | optional | Token usage for this query | -| **cost** | `number` | optional | Cost for this query in USD | -| **suggestions** | `string[]` | optional | Query refinement suggestions | - - ---- - -## NLQTrainingExample - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | Natural language query | -| **context** | `Object` | optional | | -| **expectedIntent** | `Enum<'select' \| 'aggregate' \| 'filter' \| 'sort' \| 'compare' \| 'trend' \| 'insight' \| 'create' \| 'update' \| 'delete'>` | ✅ | | -| **expectedObject** | `string` | optional | | -| **expectedAST** | `Record` | ✅ | Expected ObjectQL AST | -| **category** | `string` | optional | Example category | -| **tags** | `string[]` | optional | | -| **notes** | `string` | optional | | - - ---- - -## QueryContext - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | optional | | -| **userRole** | `string` | optional | | -| **currentObject** | `string` | optional | Current object being viewed | -| **currentRecordId** | `string` | optional | Current record ID | -| **conversationHistory** | `Object[]` | optional | | -| **defaultLimit** | `integer` | optional | | -| **timezone** | `string` | optional | | -| **locale** | `string` | optional | | - - ---- - -## QueryIntent - -### Allowed Values - -* `select` -* `aggregate` -* `filter` -* `sort` -* `compare` -* `trend` -* `insight` -* `create` -* `update` -* `delete` - - ---- - -## QueryTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | Template name (snake_case) | -| **label** | `string` | ✅ | | -| **pattern** | `string` | ✅ | Query pattern with placeholders | -| **variables** | `Object[]` | ✅ | | -| **astTemplate** | `Record` | ✅ | AST template with variable placeholders | -| **category** | `string` | optional | | -| **examples** | `string[]` | optional | | -| **tags** | `string[]` | optional | | - - ---- - -## Timeframe - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'absolute' \| 'relative'>` | ✅ | | -| **start** | `string` | optional | Start date (ISO format) | -| **end** | `string` | optional | End date (ISO format) | -| **relative** | `Object` | optional | | -| **text** | `string` | ✅ | Original timeframe text | - - ---- - diff --git a/content/docs/references/ai/orchestration.mdx b/content/docs/references/ai/orchestration.mdx deleted file mode 100644 index bafc43219..000000000 --- a/content/docs/references/ai/orchestration.mdx +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Orchestration -description: Orchestration protocol schemas ---- - -AI Agentic Orchestration Protocol - -Defines intelligent orchestration flows where AI Agents leverage cognitive skills - -to automate business processes with dynamic reasoning, planning, and execution. - -Distinction from Standard Workflows: - -- Standard Workflow: Deterministic (If X then Y). defined in src/data/workflow.zod.ts - -- AI Orchestration: Probabilistic & Agentic (Goal -> Plan -> Execute). - -Use Cases: - -- Complex Support Triage (Analyze sentiment + intent -> Draft response -> Route) - -- Intelligent Document Processing (OCR -> Extract Entities -> Validate -> Entry) - -- Research Agent (Search Web -> Summarize -> Generate Report) - - -**Source:** `packages/spec/src/ai/orchestration.zod.ts` - - -## TypeScript Usage - -```typescript -import { AIOrchestration, AIOrchestrationExecutionResult, AIOrchestrationTrigger, AITask, AITaskType, BatchAIOrchestrationExecution, PostProcessingAction, WorkflowFieldCondition, WorkflowSchedule } from '@objectstack/spec/ai'; -import type { AIOrchestration, AIOrchestrationExecutionResult, AIOrchestrationTrigger, AITask, AITaskType, BatchAIOrchestrationExecution, PostProcessingAction, WorkflowFieldCondition, WorkflowSchedule } from '@objectstack/spec/ai'; - -// Validate data -const result = AIOrchestration.parse(data); -``` - ---- - -## AIOrchestration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Orchestration unique identifier (snake_case) | -| **label** | `string` | ✅ | Display name | -| **description** | `string` | optional | | -| **objectName** | `string` | ✅ | Target object for this orchestration | -| **trigger** | `Enum<'record_created' \| 'record_updated' \| 'field_changed' \| 'scheduled' \| 'manual' \| 'webhook' \| 'batch'>` | ✅ | | -| **fieldConditions** | `Object[]` | optional | Fields to monitor (for field_changed trigger) | -| **schedule** | `Object` | optional | Schedule configuration (for scheduled trigger) | -| **webhookConfig** | `Object` | optional | Webhook configuration (for webhook trigger) | -| **entryCriteria** | `string` | optional | Formula condition - workflow only runs if TRUE | -| **aiTasks** | `Object[]` | ✅ | AI tasks to execute in sequence | -| **postActions** | `Object[]` | optional | Actions after AI tasks complete | -| **executionMode** | `Enum<'sequential' \| 'parallel'>` | optional | How to execute multiple AI tasks | -| **stopOnError** | `boolean` | optional | Stop workflow if any task fails | -| **timeout** | `number` | optional | Maximum execution time in seconds | -| **priority** | `Enum<'low' \| 'normal' \| 'high' \| 'critical'>` | optional | | -| **enableLogging** | `boolean` | optional | | -| **enableMetrics** | `boolean` | optional | | -| **notifyOnFailure** | `string[]` | optional | User IDs to notify on failure | -| **active** | `boolean` | optional | | -| **version** | `string` | optional | | -| **tags** | `string[]` | optional | | -| **category** | `string` | optional | Workflow category (e.g., "support", "sales", "hr") | -| **owner** | `string` | optional | User ID of workflow owner | -| **createdAt** | `string` | optional | ISO timestamp | -| **updatedAt** | `string` | optional | ISO timestamp | - - ---- - -## AIOrchestrationExecutionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **workflowName** | `string` | ✅ | | -| **recordId** | `string` | ✅ | | -| **status** | `Enum<'success' \| 'partial_success' \| 'failed' \| 'skipped'>` | ✅ | | -| **executionTime** | `number` | ✅ | Execution time in milliseconds | -| **tasksExecuted** | `integer` | ✅ | Number of tasks executed | -| **tasksSucceeded** | `integer` | ✅ | Number of tasks succeeded | -| **tasksFailed** | `integer` | ✅ | Number of tasks failed | -| **taskResults** | `Object[]` | optional | | -| **tokens** | `Object` | optional | Total token usage for this execution | -| **cost** | `number` | optional | Total cost for this execution in USD | -| **error** | `string` | optional | | -| **startedAt** | `string` | ✅ | ISO timestamp | -| **completedAt** | `string` | optional | ISO timestamp | - - ---- - -## AIOrchestrationTrigger - -### Allowed Values - -* `record_created` -* `record_updated` -* `field_changed` -* `scheduled` -* `manual` -* `webhook` -* `batch` - - ---- - -## AITask - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Optional task ID for referencing | -| **name** | `string` | ✅ | Human-readable task name | -| **type** | `Enum<'classify' \| 'extract' \| 'summarize' \| 'generate' \| 'predict' \| 'translate' \| 'sentiment' \| 'entity_recognition' \| 'anomaly_detection' \| 'recommendation'>` | ✅ | | -| **model** | `string` | optional | Model ID from registry (uses default if not specified) | -| **promptTemplate** | `string` | optional | Prompt template ID for this task | -| **inputFields** | `string[]` | ✅ | Source fields to process (e.g., ["description", "comments"]) | -| **inputSchema** | `Record` | optional | Validation schema for inputs | -| **inputContext** | `Record` | optional | Additional context for the AI model | -| **outputField** | `string` | ✅ | Target field to store the result | -| **outputSchema** | `Record` | optional | Validation schema for output | -| **outputFormat** | `Enum<'text' \| 'json' \| 'number' \| 'boolean' \| 'array'>` | optional | | -| **classes** | `string[]` | optional | Valid classes for classification tasks | -| **multiClass** | `boolean` | optional | Allow multiple classes to be selected | -| **extractionSchema** | `Record` | optional | JSON schema for structured extraction | -| **maxLength** | `number` | optional | Maximum length for generated content | -| **temperature** | `number` | optional | Model temperature override | -| **fallbackValue** | `any` | optional | Fallback value if AI task fails | -| **retryAttempts** | `integer` | optional | | -| **condition** | `string` | optional | Formula condition - task only runs if TRUE | -| **description** | `string` | optional | | -| **active** | `boolean` | optional | | - - ---- - -## AITaskType - -### Allowed Values - -* `classify` -* `extract` -* `summarize` -* `generate` -* `predict` -* `translate` -* `sentiment` -* `entity_recognition` -* `anomaly_detection` -* `recommendation` - - ---- - -## BatchAIOrchestrationExecution - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **workflowName** | `string` | ✅ | Orchestration to execute | -| **recordIds** | `string[]` | ✅ | Records to process | -| **batchSize** | `integer` | optional | | -| **parallelism** | `integer` | optional | | -| **priority** | `Enum<'low' \| 'normal' \| 'high'>` | optional | | - - ---- - -## PostProcessingAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'field_update' \| 'send_email' \| 'create_record' \| 'update_related' \| 'trigger_flow' \| 'webhook'>` | ✅ | | -| **name** | `string` | ✅ | Action name | -| **config** | `Record` | ✅ | Action-specific configuration | -| **condition** | `string` | optional | Execute only if condition is TRUE | - - ---- - -## WorkflowFieldCondition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name to monitor | -| **operator** | `Enum<'changed' \| 'changed_to' \| 'changed_from' \| 'is' \| 'is_not'>` | optional | | -| **value** | `any` | optional | Value to compare against (for changed_to/changed_from/is/is_not) | - - ---- - -## WorkflowSchedule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'cron' \| 'interval' \| 'daily' \| 'weekly' \| 'monthly'>` | optional | | -| **cron** | `string` | optional | Cron expression (required if type is "cron") | -| **interval** | `number` | optional | Interval in minutes (required if type is "interval") | -| **time** | `string` | optional | Time of day for daily schedules (HH:MM format) | -| **dayOfWeek** | `integer` | optional | Day of week for weekly (0=Sunday) | -| **dayOfMonth** | `integer` | optional | Day of month for monthly | -| **timezone** | `string` | optional | | - - ---- - diff --git a/content/docs/references/ai/plugin-development.mdx b/content/docs/references/ai/plugin-development.mdx deleted file mode 100644 index f74fc1ec3..000000000 --- a/content/docs/references/ai/plugin-development.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Plugin Development -description: Plugin Development protocol schemas ---- - -# AI-Driven Plugin Development Protocol - -Defines protocols for AI-powered plugin development including: - -- Natural language to code generation - -- Intelligent code scaffolding - -- Automated testing and validation - -- AI-powered code review and optimization - -- Plugin composition and recommendation - - -**Source:** `packages/spec/src/ai/plugin-development.zod.ts` - - -## TypeScript Usage - -```typescript -import { AICodeReviewResult, CodeGenerationRequest, GeneratedCode, PluginCompositionRequest, PluginCompositionResult, PluginRecommendation, PluginRecommendationRequest, PluginScaffoldingTemplate } from '@objectstack/spec/ai'; -import type { AICodeReviewResult, CodeGenerationRequest, GeneratedCode, PluginCompositionRequest, PluginCompositionResult, PluginRecommendation, PluginRecommendationRequest, PluginScaffoldingTemplate } from '@objectstack/spec/ai'; - -// Validate data -const result = AICodeReviewResult.parse(data); -``` - ---- - -## AICodeReviewResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **assessment** | `Enum<'excellent' \| 'good' \| 'acceptable' \| 'needs-improvement' \| 'poor'>` | ✅ | | -| **score** | `number` | ✅ | | -| **issues** | `Object[]` | ✅ | | -| **highlights** | `Object[]` | optional | | -| **metrics** | `Object` | optional | | -| **recommendations** | `Object[]` | ✅ | | -| **security** | `Object` | optional | | - - ---- - -## CodeGenerationRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **description** | `string` | ✅ | What the plugin should do | -| **pluginType** | `Enum<'driver' \| 'app' \| 'widget' \| 'integration' \| 'automation' \| 'analytics' \| 'ai-agent' \| 'custom'>` | ✅ | | -| **outputFormat** | `Enum<'source-code' \| 'low-code-schema' \| 'dsl'>` | optional | Format of the generated output | -| **language** | `Enum<'typescript' \| 'javascript' \| 'python'>` | optional | | -| **framework** | `Object` | optional | | -| **capabilities** | `string[]` | optional | Protocol IDs to implement | -| **dependencies** | `string[]` | optional | Required plugin IDs | -| **examples** | `Object[]` | optional | | -| **style** | `Object` | optional | | -| **schemaOptions** | `Object` | optional | | -| **context** | `Object` | optional | | -| **options** | `Object` | optional | | - - ---- - -## GeneratedCode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **outputFormat** | `Enum<'source-code' \| 'low-code-schema' \| 'dsl'>` | ✅ | | -| **code** | `string` | optional | | -| **language** | `string` | optional | | -| **schemas** | `Object[]` | optional | Generated low-code schema files | -| **files** | `Object[]` | ✅ | | -| **tests** | `Object[]` | optional | | -| **documentation** | `Object` | optional | | -| **package** | `Object` | optional | | -| **quality** | `Object` | optional | | -| **confidence** | `number` | ✅ | AI confidence in generated code | -| **suggestions** | `string[]` | optional | | -| **warnings** | `string[]` | optional | | - - ---- - -## PluginCompositionRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **goal** | `string` | ✅ | What should the composed plugins achieve | -| **availablePlugins** | `Object[]` | ✅ | | -| **constraints** | `Object` | optional | | -| **optimize** | `Enum<'performance' \| 'reliability' \| 'simplicity' \| 'cost' \| 'security'>` | optional | | - - ---- - -## PluginCompositionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **plugins** | `Object[]` | ✅ | | -| **integration** | `Object` | ✅ | | -| **dataFlow** | `Object[]` | ✅ | | -| **performance** | `Object` | optional | | -| **confidence** | `number` | ✅ | | -| **alternatives** | `Object[]` | optional | | -| **warnings** | `string[]` | optional | | - - ---- - -## PluginRecommendation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **recommendations** | `Object[]` | ✅ | | -| **combinations** | `Object[]` | optional | | -| **learningPath** | `Object[]` | optional | | - - ---- - -## PluginRecommendationRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **context** | `Object` | ✅ | | -| **criteria** | `Object` | optional | | - - ---- - -## PluginScaffoldingTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **description** | `string` | ✅ | | -| **pluginType** | `string` | ✅ | | -| **structure** | `Object[]` | ✅ | | -| **variables** | `Object[]` | ✅ | | -| **scripts** | `Object[]` | optional | | - - ---- - diff --git a/content/docs/references/ai/predictive.mdx b/content/docs/references/ai/predictive.mdx deleted file mode 100644 index 8821c0d36..000000000 --- a/content/docs/references/ai/predictive.mdx +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Predictive -description: Predictive protocol schemas ---- - -Predictive Analytics Protocol - -Defines predictive models and machine learning configurations for - -data-driven decision making and forecasting in ObjectStack applications. - -Use Cases: - -- Lead scoring and conversion prediction - -- Customer churn prediction - -- Sales forecasting - -- Demand forecasting - -- Anomaly detection in operational data - -- Customer segmentation and clustering - -- Price optimization - -- Recommendation systems - - -**Source:** `packages/spec/src/ai/predictive.zod.ts` - - -## TypeScript Usage - -```typescript -import { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai'; -import type { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai'; - -// Validate data -const result = EvaluationMetrics.parse(data); -``` - ---- - -## EvaluationMetrics - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **accuracy** | `number` | optional | | -| **precision** | `number` | optional | | -| **recall** | `number` | optional | | -| **f1Score** | `number` | optional | | -| **auc** | `number` | optional | Area Under ROC Curve | -| **mse** | `number` | optional | Mean Squared Error | -| **rmse** | `number` | optional | Root Mean Squared Error | -| **mae** | `number` | optional | Mean Absolute Error | -| **r2Score** | `number` | optional | R-squared score | -| **silhouetteScore** | `number` | optional | | -| **daviesBouldinIndex** | `number` | optional | | -| **mape** | `number` | optional | Mean Absolute Percentage Error | -| **smape** | `number` | optional | Symmetric MAPE | -| **custom** | `Record` | optional | | - - ---- - -## Hyperparameters - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **learningRate** | `number` | optional | Learning rate for training | -| **epochs** | `integer` | optional | Number of training epochs | -| **batchSize** | `integer` | optional | Training batch size | -| **maxDepth** | `integer` | optional | Maximum tree depth | -| **numTrees** | `integer` | optional | Number of trees in ensemble | -| **minSamplesSplit** | `integer` | optional | Minimum samples to split node | -| **minSamplesLeaf** | `integer` | optional | Minimum samples in leaf node | -| **hiddenLayers** | `integer[]` | optional | Hidden layer sizes | -| **activation** | `string` | optional | Activation function | -| **dropout** | `number` | optional | Dropout rate | -| **l1Regularization** | `number` | optional | L1 regularization strength | -| **l2Regularization** | `number` | optional | L2 regularization strength | -| **numClusters** | `integer` | optional | Number of clusters (k-means, etc.) | -| **seasonalPeriod** | `integer` | optional | Seasonal period for time series | -| **forecastHorizon** | `integer` | optional | Number of periods to forecast | -| **custom** | `Record` | optional | Algorithm-specific parameters | - - ---- - -## ModelDrift - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelName** | `string` | ✅ | | -| **driftType** | `Enum<'feature_drift' \| 'prediction_drift' \| 'performance_drift'>` | ✅ | | -| **severity** | `Enum<'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | | -| **detectedAt** | `string` | ✅ | ISO timestamp | -| **metrics** | `Object` | ✅ | | -| **recommendation** | `string` | optional | | -| **autoRetrainTriggered** | `boolean` | optional | | - - ---- - -## ModelFeature - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Feature name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **field** | `string` | ✅ | Source field name | -| **object** | `string` | optional | Source object (if different from target) | -| **dataType** | `Enum<'numeric' \| 'categorical' \| 'text' \| 'datetime' \| 'boolean'>` | ✅ | Feature data type | -| **transformation** | `Enum<'none' \| 'normalize' \| 'standardize' \| 'one_hot_encode' \| 'label_encode' \| 'log_transform' \| 'binning' \| 'embedding'>` | optional | | -| **required** | `boolean` | optional | | -| **defaultValue** | `any` | optional | | -| **description** | `string` | optional | | -| **importance** | `number` | optional | Feature importance score (0-1) | - - ---- - -## PredictionRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelName** | `string` | ✅ | Model to use for prediction | -| **recordIds** | `string[]` | optional | Specific records to predict (if not provided, uses all) | -| **inputData** | `Record` | optional | Direct input data (alternative to recordIds) | -| **returnConfidence** | `boolean` | optional | | -| **returnExplanation** | `boolean` | optional | | - - ---- - -## PredictionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **modelName** | `string` | ✅ | | -| **modelVersion** | `string` | ✅ | | -| **recordId** | `string` | optional | | -| **prediction** | `any` | optional | The predicted value | -| **confidence** | `number` | optional | Confidence score (0-1) | -| **probabilities** | `Record` | optional | Class probabilities (for classification) | -| **explanation** | `Object` | optional | | -| **tokens** | `Object` | optional | Token usage for this prediction (if AI-powered) | -| **cost** | `number` | optional | Cost for this prediction in USD | -| **metadata** | `Object` | optional | | - - ---- - -## PredictiveModel - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Model unique identifier (snake_case) | -| **label** | `string` | ✅ | Model display name | -| **description** | `string` | optional | | -| **type** | `Enum<'classification' \| 'regression' \| 'clustering' \| 'forecasting' \| 'anomaly_detection' \| 'recommendation' \| 'ranking'>` | ✅ | | -| **algorithm** | `string` | optional | Specific algorithm (e.g., "random_forest", "xgboost", "lstm") | -| **objectName** | `string` | ✅ | Target object for predictions | -| **target** | `string` | ✅ | Target field to predict | -| **targetType** | `Enum<'numeric' \| 'categorical' \| 'binary'>` | optional | Target field type | -| **features** | `Object[]` | ✅ | Input features for the model | -| **hyperparameters** | `Object` | optional | | -| **training** | `Object` | optional | | -| **metrics** | `Object` | optional | Evaluation metrics from last training | -| **deploymentStatus** | `Enum<'draft' \| 'training' \| 'trained' \| 'deployed' \| 'deprecated'>` | optional | | -| **version** | `string` | optional | | -| **predictionField** | `string` | optional | Field to store predictions | -| **confidenceField** | `string` | optional | Field to store confidence scores | -| **updateTrigger** | `Enum<'on_create' \| 'on_update' \| 'manual' \| 'scheduled'>` | optional | | -| **autoRetrain** | `boolean` | optional | | -| **retrainSchedule** | `string` | optional | Cron expression for auto-retraining | -| **retrainThreshold** | `number` | optional | Performance threshold to trigger retraining | -| **enableExplainability** | `boolean` | optional | Generate feature importance & explanations | -| **enableMonitoring** | `boolean` | optional | | -| **alertOnDrift** | `boolean` | optional | Alert when model drift is detected | -| **active** | `boolean` | optional | | -| **owner** | `string` | optional | User ID of model owner | -| **permissions** | `string[]` | optional | User/group IDs with access | -| **tags** | `string[]` | optional | | -| **category** | `string` | optional | Model category (e.g., "sales", "marketing", "operations") | -| **lastTrainedAt** | `string` | optional | ISO timestamp | -| **createdAt** | `string` | optional | ISO timestamp | -| **updatedAt** | `string` | optional | ISO timestamp | - - ---- - -## PredictiveModelType - -### Allowed Values - -* `classification` -* `regression` -* `clustering` -* `forecasting` -* `anomaly_detection` -* `recommendation` -* `ranking` - - ---- - -## TrainingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trainingDataRatio** | `number` | optional | Proportion of data for training | -| **validationDataRatio** | `number` | optional | Proportion for validation | -| **testDataRatio** | `number` | optional | Proportion for testing | -| **dataFilter** | `string` | optional | Formula to filter training data | -| **minRecords** | `integer` | optional | Minimum records required | -| **maxRecords** | `integer` | optional | Maximum records to use | -| **strategy** | `Enum<'full' \| 'incremental' \| 'online' \| 'transfer_learning'>` | optional | | -| **crossValidation** | `boolean` | optional | | -| **folds** | `integer` | optional | Cross-validation folds | -| **earlyStoppingEnabled** | `boolean` | optional | | -| **earlyStoppingPatience** | `integer` | optional | Epochs without improvement before stopping | -| **maxTrainingTime** | `number` | optional | Maximum training time in seconds | -| **gpuEnabled** | `boolean` | optional | | -| **randomSeed** | `integer` | optional | Random seed for reproducibility | - - ---- - diff --git a/content/docs/references/ai/rag-pipeline.mdx b/content/docs/references/ai/rag-pipeline.mdx deleted file mode 100644 index 3afcb8ce2..000000000 --- a/content/docs/references/ai/rag-pipeline.mdx +++ /dev/null @@ -1,427 +0,0 @@ ---- -title: Rag Pipeline -description: Rag Pipeline protocol schemas ---- - -RAG (Retrieval-Augmented Generation) Pipeline Protocol - -Defines schemas for building context-aware AI assistants using RAG techniques. - -Enables vector search, document chunking, embeddings, and retrieval configuration. - - -**Source:** `packages/spec/src/ai/rag-pipeline.zod.ts` - - -## TypeScript Usage - -```typescript -import { ChunkingStrategy, DocumentChunk, DocumentLoaderConfig, DocumentMetadata, EmbeddingModel, FilterExpression, FilterGroup, MetadataFilter, RAGPipelineConfig, RAGPipelineStatus, RAGQueryRequest, RAGQueryResponse, RerankingConfig, RetrievalStrategy, VectorStoreConfig, VectorStoreProvider } from '@objectstack/spec/ai'; -import type { ChunkingStrategy, DocumentChunk, DocumentLoaderConfig, DocumentMetadata, EmbeddingModel, FilterExpression, FilterGroup, MetadataFilter, RAGPipelineConfig, RAGPipelineStatus, RAGQueryRequest, RAGQueryResponse, RerankingConfig, RetrievalStrategy, VectorStoreConfig, VectorStoreProvider } from '@objectstack/spec/ai'; - -// Validate data -const result = ChunkingStrategy.parse(data); -``` - ---- - -## ChunkingStrategy - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `fixed` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **chunkSize** | `integer` | ✅ | Fixed chunk size in tokens/chars | -| **chunkOverlap** | `integer` | optional | Overlap between chunks | -| **unit** | `Enum<'tokens' \| 'characters'>` | optional | | - ---- - -#### Option 2 - -**Type:** `semantic` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **model** | `string` | optional | Model for semantic chunking | -| **minChunkSize** | `integer` | optional | | -| **maxChunkSize** | `integer` | optional | | - ---- - -#### Option 3 - -**Type:** `recursive` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **separators** | `string[]` | optional | | -| **chunkSize** | `integer` | ✅ | | -| **chunkOverlap** | `integer` | optional | | - ---- - -#### Option 4 - -**Type:** `markdown` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **maxChunkSize** | `integer` | optional | | -| **respectHeaders** | `boolean` | optional | Keep headers with content | -| **respectCodeBlocks** | `boolean` | optional | Keep code blocks intact | - ---- - - ---- - -## DocumentChunk - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique chunk identifier | -| **content** | `string` | ✅ | Chunk text content | -| **embedding** | `number[]` | optional | Embedding vector | -| **metadata** | `Object` | ✅ | | -| **chunkIndex** | `integer` | ✅ | Chunk position in document | -| **tokens** | `integer` | optional | Token count | - - ---- - -## DocumentLoaderConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'file' \| 'directory' \| 'url' \| 'api' \| 'database' \| 'custom'>` | ✅ | | -| **source** | `string` | ✅ | Source path, URL, or identifier | -| **fileTypes** | `string[]` | optional | Accepted file extensions (e.g., [".pdf", ".md"]) | -| **recursive** | `boolean` | optional | Process directories recursively | -| **maxFileSize** | `integer` | optional | Maximum file size in bytes | -| **excludePatterns** | `string[]` | optional | Patterns to exclude | -| **extractImages** | `boolean` | optional | Extract text from images (OCR) | -| **extractTables** | `boolean` | optional | Extract and format tables | -| **loaderConfig** | `Record` | optional | Custom loader-specific config | - - ---- - -## DocumentMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Document source (file path, URL, etc.) | -| **sourceType** | `Enum<'file' \| 'url' \| 'api' \| 'database' \| 'custom'>` | optional | | -| **title** | `string` | optional | | -| **author** | `string` | optional | Document author | -| **createdAt** | `string` | optional | ISO timestamp | -| **updatedAt** | `string` | optional | ISO timestamp | -| **tags** | `string[]` | optional | | -| **category** | `string` | optional | | -| **language** | `string` | optional | Document language (ISO 639-1 code) | -| **custom** | `Record` | optional | Custom metadata fields | - - ---- - -## EmbeddingModel - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'openai' \| 'cohere' \| 'huggingface' \| 'azure_openai' \| 'local' \| 'custom'>` | ✅ | | -| **model** | `string` | ✅ | Model name (e.g., "text-embedding-3-large") | -| **dimensions** | `integer` | ✅ | Embedding vector dimensions | -| **maxTokens** | `integer` | optional | Maximum tokens per embedding | -| **batchSize** | `integer` | optional | Batch size for embedding | -| **endpoint** | `string` | optional | Custom endpoint URL | -| **apiKey** | `string` | optional | API key | -| **secretRef** | `string` | optional | Reference to stored secret | - - ---- - -## FilterExpression - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Metadata field to filter | -| **operator** | `Enum<'eq' \| 'neq' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains'>` | optional | | -| **value** | `string \| number \| boolean \| string \| number[]` | ✅ | Filter value | - - ---- - -## FilterGroup - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **logic** | `Enum<'and' \| 'or'>` | optional | | -| **filters** | `Object \| any[]` | ✅ | | - - ---- - -## MetadataFilter - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Metadata field to filter | -| **operator** | `Enum<'eq' \| 'neq' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains'>` | optional | | -| **value** | `string \| number \| boolean \| string \| number[]` | ✅ | Filter value | - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **logic** | `Enum<'and' \| 'or'>` | optional | | -| **filters** | `Object \| any[]` | ✅ | | - ---- - -#### Option 3 - -Type: `Record` - ---- - - ---- - -## RAGPipelineConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Pipeline name (snake_case) | -| **label** | `string` | ✅ | Display name | -| **description** | `string` | optional | | -| **embedding** | `Object` | ✅ | | -| **vectorStore** | `Object` | ✅ | | -| **chunking** | `Object \| Object \| Object \| Object` | ✅ | | -| **retrieval** | `Object \| Object \| Object \| Object` | ✅ | | -| **reranking** | `Object` | optional | | -| **loaders** | `Object[]` | optional | Document loaders | -| **maxContextTokens** | `integer` | optional | Maximum tokens in context | -| **contextWindow** | `integer` | optional | LLM context window size | -| **metadataFilters** | `Object \| Object \| Record` | optional | Global filters for retrieval | -| **enableCache** | `boolean` | optional | | -| **cacheTTL** | `integer` | optional | Cache TTL in seconds | -| **cacheInvalidationStrategy** | `Enum<'time_based' \| 'manual' \| 'on_update'>` | optional | | - - ---- - -## RAGPipelineStatus - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **status** | `Enum<'active' \| 'indexing' \| 'error' \| 'disabled'>` | ✅ | | -| **documentsIndexed** | `integer` | ✅ | | -| **lastIndexed** | `string` | optional | ISO timestamp | -| **errorMessage** | `string` | optional | | -| **health** | `Object` | optional | | - - ---- - -## RAGQueryRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | User query | -| **pipelineName** | `string` | ✅ | Pipeline to use | -| **topK** | `integer` | optional | | -| **metadataFilters** | `Record` | optional | | -| **conversationHistory** | `Object[]` | optional | | -| **includeMetadata** | `boolean` | optional | | -| **includeSources** | `boolean` | optional | | - - ---- - -## RAGQueryResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | | -| **results** | `Object[]` | ✅ | | -| **context** | `string` | ✅ | Assembled context for LLM | -| **tokens** | `Object` | optional | Token usage for this query | -| **cost** | `number` | optional | Cost for this query in USD | -| **retrievalTime** | `number` | optional | Retrieval time in milliseconds | - - ---- - -## RerankingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **model** | `string` | optional | Reranking model name | -| **provider** | `Enum<'cohere' \| 'huggingface' \| 'custom'>` | optional | | -| **topK** | `integer` | optional | Final number of results after reranking | - - ---- - -## RetrievalStrategy - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `similarity` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **topK** | `integer` | optional | Number of results to retrieve | -| **scoreThreshold** | `number` | optional | Minimum similarity score | - ---- - -#### Option 2 - -**Type:** `mmr` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **topK** | `integer` | optional | | -| **fetchK** | `integer` | optional | Initial fetch size | -| **lambda** | `number` | optional | Diversity vs relevance (0=diverse, 1=relevant) | - ---- - -#### Option 3 - -**Type:** `hybrid` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **topK** | `integer` | optional | | -| **vectorWeight** | `number` | optional | Weight for vector search | -| **keywordWeight** | `number` | optional | Weight for keyword search | - ---- - -#### Option 4 - -**Type:** `parent_document` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **topK** | `integer` | optional | | -| **retrieveParent** | `boolean` | optional | Retrieve full parent document | - ---- - - ---- - -## VectorStoreConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'pinecone' \| 'weaviate' \| 'qdrant' \| 'milvus' \| 'chroma' \| 'pgvector' \| 'redis' \| 'opensearch' \| 'elasticsearch' \| 'custom'>` | ✅ | | -| **indexName** | `string` | ✅ | Index/collection name | -| **namespace** | `string` | optional | Namespace for multi-tenancy | -| **host** | `string` | optional | Vector store host | -| **port** | `integer` | optional | Vector store port | -| **secretRef** | `string` | optional | Reference to stored secret | -| **apiKey** | `string` | optional | API key or reference to secret | -| **dimensions** | `integer` | ✅ | Vector dimensions | -| **metric** | `Enum<'cosine' \| 'euclidean' \| 'dotproduct'>` | optional | | -| **batchSize** | `integer` | optional | | -| **connectionPoolSize** | `integer` | optional | | -| **timeout** | `integer` | optional | Timeout in milliseconds | - - ---- - -## VectorStoreProvider - -### Allowed Values - -* `pinecone` -* `weaviate` -* `qdrant` -* `milvus` -* `chroma` -* `pgvector` -* `redis` -* `opensearch` -* `elasticsearch` -* `custom` - - ---- - diff --git a/content/docs/references/ai/runtime-ops.mdx b/content/docs/references/ai/runtime-ops.mdx deleted file mode 100644 index 126d3809f..000000000 --- a/content/docs/references/ai/runtime-ops.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Runtime Ops -description: Runtime Ops protocol schemas ---- - -# Runtime AI Operations (AIOps) Protocol - -Defines protocols for AI-powered runtime operations including: - -- Self-healing and automatic recovery - -- Intelligent auto-scaling - -- Anomaly detection and prediction - -- Performance optimization - -- Root cause analysis - - -**Source:** `packages/spec/src/ai/runtime-ops.zod.ts` - - -## TypeScript Usage - -```typescript -import { AIOpsAgentConfig, AnomalyDetectionConfig, AutoScalingPolicy, PerformanceOptimization, RootCauseAnalysisRequest, RootCauseAnalysisResult, SelfHealingAction, SelfHealingConfig } from '@objectstack/spec/ai'; -import type { AIOpsAgentConfig, AnomalyDetectionConfig, AutoScalingPolicy, PerformanceOptimization, RootCauseAnalysisRequest, RootCauseAnalysisResult, SelfHealingAction, SelfHealingConfig } from '@objectstack/spec/ai'; - -// Validate data -const result = AIOpsAgentConfig.parse(data); -``` - ---- - -## AIOpsAgentConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **agentId** | `string` | ✅ | | -| **pluginId** | `string` | ✅ | | -| **selfHealing** | `Object` | optional | | -| **autoScaling** | `Object[]` | optional | | -| **monitoring** | `Object` | optional | | -| **optimization** | `Object` | optional | | -| **incidentResponse** | `Object` | optional | | - - ---- - -## AnomalyDetectionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **metrics** | `Enum<'cpu-usage' \| 'memory-usage' \| 'response-time' \| 'error-rate' \| 'throughput' \| 'latency' \| 'connection-count' \| 'queue-depth'>[]` | ✅ | | -| **algorithm** | `Enum<'statistical' \| 'machine-learning' \| 'heuristic' \| 'hybrid'>` | optional | | -| **sensitivity** | `Enum<'low' \| 'medium' \| 'high'>` | optional | How aggressively to detect anomalies | -| **timeWindow** | `integer` | optional | Historical data window for anomaly detection | -| **confidenceThreshold** | `number` | optional | Minimum confidence to flag as anomaly | -| **alertOnDetection** | `boolean` | optional | | - - ---- - -## AutoScalingPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **metric** | `Enum<'cpu-usage' \| 'memory-usage' \| 'request-rate' \| 'response-time' \| 'queue-depth' \| 'custom'>` | ✅ | | -| **customMetric** | `string` | optional | | -| **targetValue** | `number` | ✅ | Desired metric value (e.g., 70 for 70% CPU) | -| **bounds** | `Object` | ✅ | | -| **scaleUp** | `Object` | ✅ | | -| **scaleDown** | `Object` | ✅ | | -| **predictive** | `Object` | optional | | - - ---- - -## PerformanceOptimization - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **pluginId** | `string` | ✅ | | -| **type** | `Enum<'caching' \| 'query-optimization' \| 'resource-allocation' \| 'code-refactoring' \| 'architecture-change' \| 'configuration-tuning'>` | ✅ | | -| **description** | `string` | ✅ | | -| **expectedImpact** | `Object` | ✅ | | -| **difficulty** | `Enum<'trivial' \| 'easy' \| 'moderate' \| 'complex' \| 'very-complex'>` | ✅ | | -| **steps** | `string[]` | ✅ | | -| **risks** | `string[]` | optional | | -| **confidence** | `number` | ✅ | | -| **priority** | `Enum<'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | | - - ---- - -## RootCauseAnalysisRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **incidentId** | `string` | ✅ | | -| **pluginId** | `string` | ✅ | | -| **symptoms** | `Object[]` | ✅ | | -| **timeRange** | `Object` | ✅ | | -| **analyzeLogs** | `boolean` | optional | | -| **analyzeMetrics** | `boolean` | optional | | -| **analyzeDependencies** | `boolean` | optional | | -| **context** | `Record` | optional | | - - ---- - -## RootCauseAnalysisResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **analysisId** | `string` | ✅ | | -| **incidentId** | `string` | ✅ | | -| **rootCauses** | `Object[]` | ✅ | | -| **contributingFactors** | `Object[]` | optional | | -| **timeline** | `Object[]` | optional | | -| **remediation** | `Object` | optional | | -| **overallConfidence** | `number` | ✅ | | -| **timestamp** | `string` | ✅ | | - - ---- - -## SelfHealingAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **type** | `Enum<'restart' \| 'scale' \| 'rollback' \| 'clear-cache' \| 'adjust-config' \| 'execute-script' \| 'notify'>` | ✅ | | -| **trigger** | `Object` | ✅ | | -| **parameters** | `Record` | optional | | -| **maxAttempts** | `integer` | optional | | -| **cooldown** | `integer` | optional | | -| **timeout** | `integer` | optional | | -| **requireApproval** | `boolean` | optional | | -| **priority** | `integer` | optional | Action priority (lower number = higher priority) | - - ---- - -## SelfHealingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **strategy** | `Enum<'conservative' \| 'moderate' \| 'aggressive'>` | optional | | -| **actions** | `Object[]` | ✅ | | -| **anomalyDetection** | `Object` | optional | | -| **maxConcurrentHealing** | `integer` | optional | Maximum number of simultaneous healing attempts | -| **learning** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/api/.!52095!websocket.mdx b/content/docs/references/api/.!52095!websocket.mdx deleted file mode 100644 index f5ef980ce..000000000 --- a/content/docs/references/api/.!52095!websocket.mdx +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: Websocket -description: Websocket protocol schemas ---- - -WebSocket Event Protocol - -Defines the schema for WebSocket-based real-time communication in ObjectStack. - -Supports event subscriptions, filtering, presence tracking, and collaborative editing. - -Industry alignment: Firebase Realtime Database, Socket.IO, Pusher - - -**Source:** `packages/spec/src/api/websocket.zod.ts` - - -## TypeScript Usage - -```typescript -import { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api'; -import type { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api'; - -// Validate data -const result = AckMessage.parse(data); -``` - ---- - -## AckMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **ackMessageId** | `string` | ✅ | ID of the message being acknowledged | -| **success** | `boolean` | ✅ | Whether the operation was successful | -| **error** | `string` | optional | Error message if operation failed | - - ---- - -## CursorMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **cursor** | `Object` | ✅ | Cursor position | - - ---- - -## CursorPosition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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) | -| **color** | `string` | optional | Cursor color for visual representation | -| **userName** | `string` | optional | Display name of user | -| **lastUpdate** | `string` | ✅ | ISO 8601 datetime of last cursor update | - - ---- - -## DocumentState - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **documentId** | `string` | ✅ | Document identifier | -| **version** | `integer` | ✅ | Current document version | -| **content** | `string` | ✅ | Current document content | -| **lastModified** | `string` | ✅ | ISO 8601 datetime of last modification | -| **activeSessions** | `string[]` | ✅ | Active editing session IDs | -| **checksum** | `string` | optional | Content checksum for integrity verification | - - ---- - -## EditMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **operation** | `Object` | ✅ | Edit operation | - - ---- - -## EditOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operationId** | `string` | ✅ | Unique operation identifier | -| **documentId** | `string` | ✅ | Document identifier | -| **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) | -| **content** | `string` | optional | Content to insert/replace | -| **version** | `integer` | ✅ | Document version before this operation | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when operation was created | -| **baseOperationId** | `string` | optional | Previous operation ID this builds upon (for OT) | - - ---- - -## EditOperationType - -### Allowed Values - -* `insert` -* `delete` -* `replace` - - ---- - -## ErrorMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **code** | `string` | ✅ | Error code | -| **message** | `string` | ✅ | Error message | -| **details** | `any` | optional | Additional error details | - - ---- - -## EventFilter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **conditions** | `Object[]` | optional | Array of filter conditions | -| **and** | `any[]` | optional | AND logical combination of filters | -| **or** | `any[]` | optional | OR logical combination of filters | -| **not** | `any` | optional | NOT logical negation of filter | - - ---- - -## EventFilterCondition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field path to filter on (supports dot notation, e.g., "user.email") | -| **operator** | `Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'exists' \| 'regex'>` | ✅ | Comparison operator | -| **value** | `any` | optional | Value to compare against (not needed for "exists" operator) | - - ---- - -## EventMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscriptionId** | `string` | ✅ | Subscription ID this event belongs to | -| **eventName** | `string` | ✅ | Event name | -| **object** | `string` | optional | Object name the event relates to | -| **payload** | `any` | optional | Event payload data | -| **userId** | `string` | optional | User who triggered the event | - - ---- - -## EventPattern - -Event pattern (supports wildcards like "record.*" or "*.created") - - ---- - -## EventSubscription - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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** | `Object` | optional | Advanced filter conditions for event payloads | -| **channels** | `string[]` | optional | Channel names for scoped subscriptions | - - ---- - -## FilterOperator - -### Allowed Values - -* `eq` -* `ne` -* `gt` -* `gte` -* `lt` -* `lte` -* `in` -* `nin` -* `contains` -* `startsWith` -* `endsWith` -* `exists` -* `regex` - - ---- - -## PingMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | - - ---- - -## PongMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- \ No newline at end of file diff --git a/content/docs/references/api/analytics.mdx b/content/docs/references/api/analytics.mdx deleted file mode 100644 index 20681e097..000000000 --- a/content/docs/references/api/analytics.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Analytics -description: Analytics protocol schemas ---- - -Analytics API Protocol - -Defines the HTTP interface for the Semantic Layer. - -Provides endpoints for executing analytical queries and discovering metadata. - - -**Source:** `packages/spec/src/api/analytics.zod.ts` - - -## TypeScript Usage - -```typescript -import { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsResultResponse, AnalyticsSqlResponse, GetAnalyticsMetaRequest } from '@objectstack/spec/api'; -import type { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsResultResponse, AnalyticsSqlResponse, GetAnalyticsMetaRequest } from '@objectstack/spec/api'; - -// Validate data -const result = AnalyticsEndpoint.parse(data); -``` - ---- - -## AnalyticsEndpoint - -### Allowed Values - -* `/api/v1/analytics/query` -* `/api/v1/analytics/meta` -* `/api/v1/analytics/sql` - - ---- - -## AnalyticsMetadataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## AnalyticsQueryRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `Object` | ✅ | The analytic query definition | -| **cube** | `string` | ✅ | Target cube name | -| **format** | `Enum<'json' \| 'csv' \| 'xlsx'>` | optional | Response format | - - ---- - -## AnalyticsResultResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## AnalyticsSqlResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## GetAnalyticsMetaRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **cube** | `string` | optional | Optional cube name to filter | - - ---- - diff --git a/content/docs/references/api/auth.mdx b/content/docs/references/api/auth.mdx deleted file mode 100644 index 636939c63..000000000 --- a/content/docs/references/api/auth.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Auth -description: Auth protocol schemas ---- - -Authentication Service Protocol - -Defines the standard API contracts for Identity, Session Management, - -and Access Control. - - -**Source:** `packages/spec/src/api/auth.zod.ts` - - -## TypeScript Usage - -```typescript -import { AuthProvider, LoginRequest, LoginType, RefreshTokenRequest, RegisterRequest, SessionResponse, SessionUser, UserProfileResponse } from '@objectstack/spec/api'; -import type { AuthProvider, LoginRequest, LoginType, RefreshTokenRequest, RegisterRequest, SessionResponse, SessionUser, UserProfileResponse } from '@objectstack/spec/api'; - -// Validate data -const result = AuthProvider.parse(data); -``` - ---- - -## AuthProvider - -### Allowed Values - -* `local` -* `google` -* `github` -* `microsoft` -* `ldap` -* `saml` - - ---- - -## LoginRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'email' \| 'username' \| 'phone' \| 'magic-link' \| 'social'>` | optional | Login method | -| **email** | `string` | optional | Required for email/magic-link | -| **username** | `string` | optional | Required for username login | -| **password** | `string` | optional | Required for password login | -| **provider** | `string` | optional | Required for social (google, github) | -| **redirectTo** | `string` | optional | Redirect URL after successful login | - - ---- - -## LoginType - -### Allowed Values - -* `email` -* `username` -* `phone` -* `magic-link` -* `social` - - ---- - -## RefreshTokenRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **refreshToken** | `string` | ✅ | Refresh token | - - ---- - -## RegisterRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **email** | `string` | ✅ | | -| **password** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **image** | `string` | optional | | - - ---- - -## SessionResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## SessionUser - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | User ID | -| **email** | `string` | ✅ | Email address | -| **emailVerified** | `boolean` | optional | Is email verified? | -| **name** | `string` | ✅ | Display name | -| **image** | `string` | optional | Avatar URL | -| **username** | `string` | optional | Username (optional) | -| **roles** | `string[]` | optional | Assigned role IDs | -| **tenantId** | `string` | optional | Current tenant ID | -| **language** | `string` | optional | Preferred language | -| **timezone** | `string` | optional | Preferred timezone | -| **createdAt** | `string` | optional | | -| **updatedAt** | `string` | optional | | - - ---- - -## UserProfileResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - diff --git a/content/docs/references/api/batch.mdx b/content/docs/references/api/batch.mdx deleted file mode 100644 index 1f17e0a91..000000000 --- a/content/docs/references/api/batch.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Batch -description: Batch protocol schemas ---- - -Batch Operations API - -Provides efficient bulk data operations with transaction support. - -Implements P0/P1 requirements for ObjectStack kernel. - -Features: - -- Batch create/update/delete operations - -- Atomic transaction support (all-or-none) - -- Partial success handling - -- Detailed error reporting per record - -Industry alignment: Salesforce Bulk API, Microsoft Dynamics Bulk Operations - - -**Source:** `packages/spec/src/api/batch.zod.ts` - - -## TypeScript Usage - -```typescript -import { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api'; -import type { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api'; - -// Validate data -const result = BatchConfig.parse(data); -``` - ---- - -## BatchConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable batch operations | -| **maxRecordsPerBatch** | `integer` | optional | Maximum records per batch | -| **defaultOptions** | `Object` | optional | Default batch options | - - ---- - -## BatchOperationResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | -| **data** | `Record` | optional | Full record data (if returnRecords=true) | -| **index** | `number` | optional | Index of the record in the request array | - - ---- - -## BatchOperationType - -### Allowed Values - -* `create` -* `update` -* `upsert` -* `delete` - - ---- - -## BatchOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **atomic** | `boolean` | optional | If true, rollback entire batch on any failure (transaction mode) | -| **returnRecords** | `boolean` | optional | If true, return full record data in response | -| **continueOnError** | `boolean` | optional | If true (and atomic=false), continue processing remaining records after errors | -| **validateOnly** | `boolean` | optional | If true, validate records without persisting changes (dry-run mode) | - - ---- - -## BatchRecord - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Record ID (required for update/delete) | -| **data** | `Record` | optional | Record data (required for create/update/upsert) | -| **externalId** | `string` | optional | External ID for upsert matching | - - ---- - -## BatchUpdateRequest - -### Properties - -| 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 | - - ---- - -## BatchUpdateResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | 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 | - - ---- - -## DeleteManyRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **ids** | `string[]` | ✅ | Array of record IDs to delete (max 200) | -| **options** | `Object` | optional | Delete options | - - ---- - -## UpdateManyRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **records** | `Object[]` | ✅ | Array of records to update (max 200 per batch) | -| **options** | `Object` | optional | Update options | - - ---- - diff --git a/content/docs/references/api/connector.mdx b/content/docs/references/api/connector.mdx deleted file mode 100644 index c4073130a..000000000 --- a/content/docs/references/api/connector.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Connector -description: Connector protocol schemas ---- - - -**Source:** `packages/spec/src/api/connector.zod.ts` - - -## TypeScript Usage - -```typescript -import { RetryStrategy } from '@objectstack/spec/api'; -import type { RetryStrategy } from '@objectstack/spec/api'; - -// Validate data -const result = RetryStrategy.parse(data); -``` - ---- - -## RetryStrategy - -### Allowed Values - -* `no_retry` -* `retry_immediate` -* `retry_backoff` -* `retry_after` - - ---- - diff --git a/content/docs/references/api/contract.mdx b/content/docs/references/api/contract.mdx deleted file mode 100644 index 1f72c687d..000000000 --- a/content/docs/references/api/contract.mdx +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Contract -description: Contract protocol schemas ---- - -Standard Create Request - - -**Source:** `packages/spec/src/api/contract.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApiError, BaseResponse, BulkRequest, BulkResponse, CreateRequest, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api'; -import type { ApiError, BaseResponse, BulkRequest, BulkResponse, CreateRequest, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api'; - -// Validate data -const result = ApiError.parse(data); -``` - ---- - -## ApiError - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **code** | `string` | ✅ | Error code (e.g. validation_error) | -| **message** | `string` | ✅ | Readable error message | -| **category** | `string` | optional | Error category (e.g. validation, authorization) | -| **details** | `any` | optional | Additional error context (e.g. field validation errors) | -| **requestId** | `string` | optional | Request ID for tracking | - - ---- - -## BaseResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | - - ---- - -## BulkRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **records** | `Record[]` | ✅ | Array of records to process | -| **allOrNone** | `boolean` | optional | If true, rollback entire transaction on any failure | - - ---- - -## BulkResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | Results for each item in the batch | - - ---- - -## CreateRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `Record` | ✅ | Record data to insert | - - ---- - -## DeleteResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **id** | `string` | ✅ | ID of the deleted record | - - ---- - -## ExportRequest - - ---- - -## IdRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Record ID | - - ---- - -## ListRecordResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Record[]` | ✅ | Array of matching records | -| **pagination** | `Object` | ✅ | Pagination info | - - ---- - -## ModificationResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Record ID if processed | -| **success** | `boolean` | ✅ | | -| **errors** | `Object[]` | optional | | -| **index** | `number` | optional | Index in original request | -| **data** | `any` | optional | Result data (e.g. created record) | - - ---- - -## RecordData - -Key-value map of record data - - ---- - -## SingleRecordResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Record` | ✅ | The requested or modified record | - - ---- - -## UpdateRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `Record` | ✅ | Partial record data to update | - - ---- - diff --git a/content/docs/references/api/discovery.mdx b/content/docs/references/api/discovery.mdx deleted file mode 100644 index 3c05f0c8f..000000000 --- a/content/docs/references/api/discovery.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Discovery -description: Discovery protocol schemas ---- - -API Capabilities Schema - -Defines what features are enabled on this ObjectOS instance. - - -**Source:** `packages/spec/src/api/discovery.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApiCapabilities, ApiRoutes, Discovery } from '@objectstack/spec/api'; -import type { ApiCapabilities, ApiRoutes, Discovery } from '@objectstack/spec/api'; - -// Validate data -const result = ApiCapabilities.parse(data); -``` - ---- - -## ApiCapabilities - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **graphql** | `boolean` | optional | | -| **search** | `boolean` | optional | | -| **websockets** | `boolean` | optional | | -| **files** | `boolean` | optional | | -| **analytics** | `boolean` | optional | Is the Analytics/BI engine enabled? | -| **hub** | `boolean` | optional | Is Hub management enabled? | - - ---- - -## ApiRoutes - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `string` | ✅ | e.g. /api/data | -| **metadata** | `string` | ✅ | e.g. /api/meta | -| **ui** | `string` | optional | e.g. /api/ui | -| **auth** | `string` | ✅ | e.g. /api/auth | -| **automation** | `string` | optional | e.g. /api/automation | -| **storage** | `string` | optional | e.g. /api/storage | -| **analytics** | `string` | optional | e.g. /api/analytics | -| **hub** | `string` | optional | e.g. /api/hub | -| **graphql** | `string` | optional | e.g. /graphql | - - ---- - -## Discovery - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **version** | `string` | ✅ | | -| **environment** | `Enum<'production' \| 'sandbox' \| 'development'>` | ✅ | | -| **routes** | `Object` | ✅ | | -| **features** | `Object` | ✅ | | -| **locale** | `Object` | ✅ | | - - ---- - diff --git a/content/docs/references/api/documentation.mdx b/content/docs/references/api/documentation.mdx deleted file mode 100644 index d12e1da55..000000000 --- a/content/docs/references/api/documentation.mdx +++ /dev/null @@ -1,270 +0,0 @@ ---- -title: Documentation -description: Documentation protocol schemas ---- - -API Documentation & Testing Interface Protocol - -Provides schemas for generating interactive API documentation and testing - -interfaces similar to Swagger UI, GraphQL Playground, Postman, etc. - -Features: - -- OpenAPI/Swagger specification generation - -- Interactive API testing playground - -- API versioning and changelog - -- Code generation templates - -- Mock server configuration - -Architecture Alignment: - -- Swagger UI: Interactive API documentation - -- Postman: API testing collections - -- GraphQL Playground: GraphQL-specific testing - -- Redoc: Documentation rendering - -@example Documentation Config - -```typescript - -const docConfig: ApiDocumentationConfig = { - -enabled: true, - -title: 'ObjectStack API', - -version: '1.0.0', - -servers: [{ url: 'https://api.example.com', description: 'Production' }], - -ui: { - -type: 'swagger-ui', - -theme: 'light', - -enableTryItOut: true - -} - -} - -``` - - -**Source:** `packages/spec/src/api/documentation.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api'; -import type { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api'; - -// Validate data -const result = ApiChangelogEntry.parse(data); -``` - ---- - -## ApiChangelogEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **version** | `string` | ✅ | API version | -| **date** | `string` | ✅ | Release date | -| **changes** | `Object` | ✅ | Version changes | -| **migrationGuide** | `string` | optional | Migration guide URL or text | - - ---- - -## ApiDocumentationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable API documentation | -| **title** | `string` | optional | Documentation title | -| **version** | `string` | ✅ | API version | -| **description** | `string` | optional | API description | -| **servers** | `Object[]` | optional | API server URLs | -| **ui** | `Object` | optional | Testing UI configuration | -| **generateOpenApi** | `boolean` | optional | Generate OpenAPI 3.0 specification | -| **generateTestCollections** | `boolean` | optional | Generate API test collections | -| **testCollections** | `Object[]` | optional | Predefined test collections | -| **changelog** | `Object[]` | optional | API version changelog | -| **codeTemplates** | `Object[]` | optional | 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 | - - ---- - -## ApiTestCollection - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Collection name | -| **description** | `string` | optional | Collection description | -| **variables** | `Record` | optional | Shared variables | -| **requests** | `Object[]` | ✅ | Test requests in this collection | -| **folders** | `Object[]` | optional | Request folders for organization | - - ---- - -## ApiTestRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Test request name | -| **description** | `string` | optional | Request description | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method | -| **url** | `string` | ✅ | Request URL (can include variables) | -| **headers** | `Record` | optional | Request headers | -| **queryParams** | `Record` | optional | Query parameters | -| **body** | `any` | optional | Request body | -| **variables** | `Record` | optional | Template variables | -| **expectedResponse** | `Object` | optional | Expected response for validation | - - ---- - -## ApiTestingUiConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphql-playground' \| 'graphiql' \| 'postman' \| 'custom'>` | ✅ | Testing UI implementation | -| **path** | `string` | optional | URL path for documentation UI | -| **theme** | `Enum<'light' \| 'dark' \| 'auto'>` | optional | UI color theme | -| **enableTryItOut** | `boolean` | optional | Enable interactive API testing | -| **enableFilter** | `boolean` | optional | Enable endpoint filtering | -| **enableCors** | `boolean` | optional | Enable CORS for browser testing | -| **defaultModelsExpandDepth** | `integer` | optional | Default expand depth for schemas (-1 = fully expand) | -| **displayRequestDuration** | `boolean` | optional | Show request duration | -| **syntaxHighlighting** | `boolean` | optional | Enable syntax highlighting | -| **customCssUrl** | `string` | optional | Custom CSS stylesheet URL | -| **customJsUrl** | `string` | optional | Custom JavaScript URL | -| **layout** | `Object` | optional | Layout configuration | - - ---- - -## ApiTestingUiType - -### Allowed Values - -* `swagger-ui` -* `redoc` -* `rapidoc` -* `stoplight` -* `scalar` -* `graphql-playground` -* `graphiql` -* `postman` -* `custom` - - ---- - -## CodeGenerationTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **language** | `string` | ✅ | Target language/framework (e.g., typescript, python, curl) | -| **name** | `string` | ✅ | Template name | -| **template** | `string` | ✅ | Code template with placeholders | -| **variables** | `string[]` | optional | Required template variables | - - ---- - -## GeneratedApiDocumentation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **openApiSpec** | `Object` | optional | Generated OpenAPI specification | -| **testCollections** | `Object[]` | optional | Generated test collections | -| **markdown** | `string` | optional | Generated markdown documentation | -| **html** | `string` | optional | Generated HTML documentation | -| **generatedAt** | `string` | ✅ | Generation timestamp | -| **sourceApis** | `string[]` | ✅ | Source API IDs used for generation | - - ---- - -## OpenApiSecurityScheme - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'apiKey' \| 'http' \| 'oauth2' \| 'openIdConnect'>` | ✅ | Security type | -| **scheme** | `string` | optional | HTTP auth scheme (bearer, basic, etc.) | -| **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 | -| **openIdConnectUrl** | `string` | optional | OpenID Connect discovery URL | -| **description** | `string` | optional | Security scheme description | - - ---- - -## OpenApiServer - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | ✅ | Server base URL | -| **description** | `string` | optional | Server description | -| **variables** | `Record` | optional | URL template variables | - - ---- - -## OpenApiSpec - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **openapi** | `string` | optional | OpenAPI specification version | -| **info** | `Object` | ✅ | API metadata | -| **servers** | `Object[]` | optional | API servers | -| **paths** | `Record` | ✅ | API paths and operations | -| **components** | `Object` | optional | Reusable components | -| **security** | `Record[]` | optional | Global security requirements | -| **tags** | `Object[]` | optional | Tag definitions | -| **externalDocs** | `Object` | optional | External documentation | - - ---- - diff --git a/content/docs/references/api/endpoint.mdx b/content/docs/references/api/endpoint.mdx deleted file mode 100644 index c9c3b7290..000000000 --- a/content/docs/references/api/endpoint.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Endpoint -description: Endpoint protocol schemas ---- - -Rate Limit Strategy - -@deprecated Use RateLimitConfigSchema from shared/http.zod.ts instead - - -**Source:** `packages/spec/src/api/endpoint.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApiEndpoint, ApiMapping, RateLimit } from '@objectstack/spec/api'; -import type { ApiEndpoint, ApiMapping, RateLimit } from '@objectstack/spec/api'; - -// Validate data -const result = ApiEndpoint.parse(data); -``` - ---- - -## ApiEndpoint - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique endpoint ID | -| **path** | `string` | ✅ | URL Path (e.g. /api/v1/customers) | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP Method | -| **summary** | `string` | optional | | -| **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 | -| **authRequired** | `boolean` | optional | Require authentication | -| **rateLimit** | `Object` | optional | Rate limiting policy | -| **cacheTtl** | `number` | optional | Response cache TTL in seconds | - - ---- - -## ApiMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Source field/path | -| **target** | `string` | ✅ | Target field/path | -| **transform** | `string` | optional | Transformation function name | - - ---- - -## RateLimit - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable rate limiting | -| **windowMs** | `integer` | optional | Time window in milliseconds | -| **maxRequests** | `integer` | optional | Max requests per window | - - ---- - diff --git a/content/docs/references/api/errors.mdx b/content/docs/references/api/errors.mdx deleted file mode 100644 index 27ee57f44..000000000 --- a/content/docs/references/api/errors.mdx +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Errors -description: Errors protocol schemas ---- - -Standardized Error Codes Protocol - -Implements P0 requirement for ObjectStack kernel. - -Provides consistent, machine-readable error codes across the platform. - -Features: - -- Categorized error codes (validation, authentication, authorization, etc.) - -- HTTP status code mapping - -- Localization support - -- Retry guidance - -Industry alignment: Google Cloud Errors, AWS Error Codes, Stripe API Errors - - -**Source:** `packages/spec/src/api/errors.zod.ts` - - -## TypeScript Usage - -```typescript -import { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, StandardErrorCode } from '@objectstack/spec/api'; -import type { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, StandardErrorCode } from '@objectstack/spec/api'; - -// Validate data -const result = EnhancedApiError.parse(data); -``` - ---- - -## EnhancedApiError - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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'>` | ✅ | Machine-readable error code | -| **message** | `string` | ✅ | Human-readable error message | -| **category** | `Enum<'validation' \| 'authentication' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'server' \| 'external' \| 'maintenance'>` | optional | Error category | -| **httpStatus** | `number` | optional | HTTP status code | -| **retryable** | `boolean` | optional | Whether the request can be retried | -| **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 | -| **timestamp** | `string` | optional | When the error occurred | -| **requestId** | `string` | optional | Request ID for tracking | -| **traceId** | `string` | optional | Distributed trace ID | -| **documentation** | `string` | optional | URL to error documentation | -| **helpText** | `string` | optional | Suggested actions to resolve the error | - - ---- - -## ErrorCategory - -### Allowed Values - -* `validation` -* `authentication` -* `authorization` -* `not_found` -* `conflict` -* `rate_limit` -* `server` -* `external` -* `maintenance` - - ---- - -## ErrorResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Always false for error responses | -| **error** | `Object` | ✅ | Error details | -| **meta** | `Object` | optional | Response metadata | - - ---- - -## FieldError - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field path (supports dot notation) | -| **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'>` | ✅ | Error code for this field | -| **message** | `string` | ✅ | Human-readable error message | -| **value** | `any` | optional | The invalid value that was provided | -| **constraint** | `any` | optional | The constraint that was violated (e.g., max length) | - - ---- - -## StandardErrorCode - -### Allowed Values - -* `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` - - ---- - diff --git a/content/docs/references/api/graphql.mdx b/content/docs/references/api/graphql.mdx deleted file mode 100644 index ec910e0fa..000000000 --- a/content/docs/references/api/graphql.mdx +++ /dev/null @@ -1,397 +0,0 @@ ---- -title: Graphql -description: Graphql protocol schemas ---- - -GraphQL Protocol Support - -GraphQL is a query language for APIs and a runtime for executing those queries. - -It provides a complete and understandable description of the data in your API, - -gives clients the power to ask for exactly what they need, and enables powerful - -developer tools. - -## Overview - -GraphQL provides: - -- Type-safe schema definition - -- Precise data fetching (no over/under-fetching) - -- Introspection and documentation - -- Real-time subscriptions - -- Batched queries with DataLoader - -## Use Cases - -1. **Modern API Development** - -- Mobile and web applications - -- Microservices federation - -- Real-time dashboards - -2. **Data Aggregation** - -- Multi-source data integration - -- Complex nested queries - -- Efficient data loading - -3. **Developer Experience** - -- Self-documenting API - -- Type safety and validation - -- GraphQL playground - -@see https://graphql.org/ - -@see https://spec.graphql.org/ - -@example GraphQL Query - -```graphql - -query GetCustomer($id: ID!) { - -customer(id: $id) { - -id - -name - -email - -orders(limit: 10, status: "active") { - -id - -total - -items { - -product { - -name - -price - -} - -} - -} - -} - -} - -``` - -@example GraphQL Mutation - -```graphql - -mutation CreateOrder($input: CreateOrderInput!) { - -createOrder(input: $input) { - -id - -orderNumber - -status - -} - -} - -``` - - -**Source:** `packages/spec/src/api/graphql.zod.ts` - - -## TypeScript Usage - -```typescript -import { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api'; -import type { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api'; - -// Validate data -const result = GraphQLConfig.parse(data); -``` - ---- - -## GraphQLConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable GraphQL API | -| **path** | `string` | optional | GraphQL endpoint path | -| **playground** | `Object` | optional | GraphQL Playground configuration | -| **schema** | `Object` | optional | Schema generation configuration | -| **dataLoaders** | `Object[]` | optional | DataLoader configurations | -| **security** | `Object` | optional | Security configuration | - - ---- - -## GraphQLDataLoaderConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | - - ---- - -## GraphQLDirectiveConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | -| **repeatable** | `boolean` | optional | Can be applied multiple times | -| **implementation** | `Object` | optional | Directive implementation | - - ---- - -## GraphQLDirectiveLocation - -### Allowed Values - -* `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` - - ---- - -## GraphQLMutationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Mutation field name (camelCase recommended) | -| **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 | -| **authRequired** | `boolean` | optional | Require authentication | -| **permissions** | `string[]` | optional | Required permissions | -| **hooks** | `Object` | optional | Lifecycle hooks | - - ---- - -## GraphQLPersistedQuery - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable persisted queries | -| **mode** | `Enum<'optional' \| 'required'>` | optional | 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 | - - ---- - -## GraphQLQueryComplexity - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable query complexity limiting | -| **maxComplexity** | `integer` | optional | Maximum query complexity | -| **defaultFieldComplexity** | `integer` | optional | Default complexity per field | -| **fieldComplexity** | `Record` | optional | Per-field complexity configuration | -| **listMultiplier** | `number` | optional | Multiplier for list fields | -| **onComplexityExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | optional | Action when complexity exceeded | -| **errorMessage** | `string` | optional | Custom error message for complexity violations | - - ---- - -## GraphQLQueryConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Query field name (camelCase recommended) | -| **object** | `string` | ✅ | Source ObjectQL object name | -| **type** | `Enum<'get' \| 'list' \| 'search'>` | ✅ | Query type | -| **description** | `string` | optional | Query description | -| **args** | `Record` | optional | Query arguments | -| **filtering** | `Object` | optional | Filtering capabilities | -| **sorting** | `Object` | optional | Sorting capabilities | -| **pagination** | `Object` | optional | Pagination configuration | -| **fields** | `Object` | optional | Field selection configuration | -| **authRequired** | `boolean` | optional | Require authentication | -| **permissions** | `string[]` | optional | Required permissions | -| **cache** | `Object` | optional | Query caching | - - ---- - -## GraphQLQueryDepthLimit - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable query depth limiting | -| **maxDepth** | `integer` | optional | Maximum query depth | -| **ignoreFields** | `string[]` | optional | Fields excluded from depth calculation | -| **onDepthExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | optional | Action when depth exceeded | -| **errorMessage** | `string` | optional | Custom error message for depth violations | - - ---- - -## GraphQLRateLimit - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable rate limiting | -| **strategy** | `Enum<'token_bucket' \| 'fixed_window' \| 'sliding_window' \| 'cost_based'>` | optional | 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 | -| **onLimitExceeded** | `Enum<'reject' \| 'queue' \| 'log'>` | optional | Action when rate limit exceeded | -| **errorMessage** | `string` | optional | Custom error message for rate limit violations | -| **includeHeaders** | `boolean` | optional | Include rate limit headers in response | - - ---- - -## GraphQLResolverConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **path** | `string` | ✅ | Resolver path (Type.field) | -| **type** | `Enum<'datasource' \| 'computed' \| 'script' \| 'proxy'>` | ✅ | Resolver implementation type | -| **implementation** | `Object` | optional | Implementation configuration | -| **cache** | `Object` | optional | Resolver caching | - - ---- - -## GraphQLScalarType - -### Allowed Values - -* `ID` -* `String` -* `Int` -* `Float` -* `Boolean` -* `DateTime` -* `Date` -* `Time` -* `JSON` -* `JSONObject` -* `Upload` -* `URL` -* `Email` -* `PhoneNumber` -* `Currency` -* `Decimal` -* `BigInt` -* `Long` -* `UUID` -* `Base64` -* `Void` - - ---- - -## GraphQLSubscriptionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Subscription field name (camelCase recommended) | -| **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 | -| **authRequired** | `boolean` | optional | Require authentication | -| **permissions** | `string[]` | optional | Required permissions | -| **rateLimit** | `Object` | optional | Subscription rate limiting | - - ---- - -## GraphQLTypeConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | GraphQL type name (PascalCase recommended) | -| **object** | `string` | ✅ | Source ObjectQL object name | -| **description** | `string` | optional | Type description | -| **fields** | `Object` | optional | Field configuration | -| **interfaces** | `string[]` | optional | GraphQL interface names | -| **isInterface** | `boolean` | optional | Define as GraphQL interface | -| **directives** | `Object[]` | optional | GraphQL directives | - - ---- - diff --git a/content/docs/references/api/http-cache.mdx b/content/docs/references/api/http-cache.mdx deleted file mode 100644 index bc8a29f01..000000000 --- a/content/docs/references/api/http-cache.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Http Cache -description: Http Cache protocol schemas ---- - -HTTP Metadata Cache Protocol - -Implements efficient HTTP-level metadata caching with ETag support. - -Implements P0 requirement for ObjectStack kernel. - -## Caching in ObjectStack - -**HTTP Cache (`api/http-cache.zod.ts`) - This File** - -- **Purpose**: Cache API responses at HTTP protocol level - -- **Technologies**: HTTP headers (ETag, Last-Modified, Cache-Control), CDN - -- **Configuration**: Cache-Control headers, validation tokens - -- **Use case**: Reduce API response time for repeated metadata requests - -- **Scope**: HTTP layer, client-server communication - -**Application Cache (`system/cache.zod.ts`)** - -- **Purpose**: Cache computed data, query results, aggregations - -- **Technologies**: Redis, Memcached, in-memory LRU - -- **Configuration**: TTL, eviction policies, cache warming - -- **Use case**: Cache expensive database queries, computed values - -- **Scope**: Application layer, server-side data storage - -## Features - -- ETag-based conditional requests (HTTP 304 Not Modified) - -- Cache-Control directives - -- Metadata versioning - -- Selective cache invalidation - -Industry alignment: HTTP Caching (RFC 7234), Salesforce Metadata API - -@see ../../system/cache.zod.ts for application-level caching - - -**Source:** `packages/spec/src/api/http-cache.zod.ts` - - -## TypeScript Usage - -```typescript -import { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api'; -import type { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api'; - -// Validate data -const result = CacheControl.parse(data); -``` - ---- - -## CacheControl - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **directives** | `Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]` | ✅ | Cache control directives | -| **maxAge** | `number` | optional | Maximum cache age in seconds | -| **staleWhileRevalidate** | `number` | optional | Allow serving stale content while revalidating (seconds) | -| **staleIfError** | `number` | optional | Allow serving stale content on error (seconds) | - - ---- - -## CacheDirective - -### Allowed Values - -* `public` -* `private` -* `no-cache` -* `no-store` -* `must-revalidate` -* `max-age` - - ---- - -## CacheInvalidationRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **target** | `Enum<'all' \| 'object' \| 'field' \| 'permission' \| 'layout' \| 'custom'>` | ✅ | What to invalidate | -| **identifiers** | `string[]` | optional | Specific resources to invalidate (e.g., object names) | -| **cascade** | `boolean` | optional | If true, invalidate dependent resources | -| **pattern** | `string` | optional | Pattern for custom invalidation (supports wildcards) | - - ---- - -## CacheInvalidationResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Whether invalidation succeeded | -| **invalidated** | `number` | ✅ | Number of cache entries invalidated | -| **targets** | `string[]` | optional | List of invalidated resources | - - ---- - -## CacheInvalidationTarget - -### Allowed Values - -* `all` -* `object` -* `field` -* `permission` -* `layout` -* `custom` - - ---- - -## ETag - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | ETag value (hash or version identifier) | -| **weak** | `boolean` | optional | Whether this is a weak ETag | - - ---- - -## MetadataCacheRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | - - ---- - -## MetadataCacheResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `any` | optional | Metadata payload (omitted for 304 Not Modified) | -| **etag** | `Object` | optional | ETag for this resource version | -| **lastModified** | `string` | optional | Last modification timestamp | -| **cacheControl** | `Object` | optional | Cache control directives | -| **notModified** | `boolean` | optional | True if resource has not been modified (304 response) | -| **version** | `string` | optional | Metadata version identifier | - - ---- - diff --git a/content/docs/references/api/hub.mdx b/content/docs/references/api/hub.mdx deleted file mode 100644 index a9fb674aa..000000000 --- a/content/docs/references/api/hub.mdx +++ /dev/null @@ -1,636 +0,0 @@ ---- -title: Hub -description: Hub protocol schemas ---- - -# Hub Management API Protocol - -Defines RESTful API contracts for the ObjectStack Hub - the unified cloud - -management center for all tenants, plugins, spaces, and marketplace operations. - -This protocol enables: - -- Multi-tenant SaaS management - -- Plugin marketplace operations - -- Space/workspace lifecycle - -- License management and validation - -- Composer/builder services - -@see https://objectstack.ai/docs/api/hub - - -**Source:** `packages/spec/src/api/hub.zod.ts` - - -## TypeScript Usage - -```typescript -import { BuildStatusResponse, CompileManifestRequest, CompileManifestResponse, CreateSpaceRequest, CreateTenantRequest, GetBuildStatusRequest, GetMarketplacePluginRequest, GetPluginVersionsRequest, GetPluginVersionsResponse, HubHealthResponse, HubMetricsResponse, InstallPluginRequest, InstallPluginResponse, IssueLicenseRequest, LicenseResponse, ListLicensesRequest, ListLicensesResponse, ListMarketplaceRequest, ListMarketplaceResponse, ListSpacesRequest, ListSpacesResponse, ListTenantsRequest, ListTenantsResponse, MarketplacePluginResponse, PaginationRequest, PaginationResponse, PluginResponse, PluginVersionInfo, PublishPluginRequest, RevokeLicenseRequest, SearchPluginsRequest, SearchPluginsResponse, SpaceResponse, TenantResponse, UpdatePluginRequest, UpdateSpaceRequest, UpdateTenantRequest, ValidateLicenseRequest, ValidateLicenseResponse } from '@objectstack/spec/api'; -import type { BuildStatusResponse, CompileManifestRequest, CompileManifestResponse, CreateSpaceRequest, CreateTenantRequest, GetBuildStatusRequest, GetMarketplacePluginRequest, GetPluginVersionsRequest, GetPluginVersionsResponse, HubHealthResponse, HubMetricsResponse, InstallPluginRequest, InstallPluginResponse, IssueLicenseRequest, LicenseResponse, ListLicensesRequest, ListLicensesResponse, ListMarketplaceRequest, ListMarketplaceResponse, ListSpacesRequest, ListSpacesResponse, ListTenantsRequest, ListTenantsResponse, MarketplacePluginResponse, PaginationRequest, PaginationResponse, PluginResponse, PluginVersionInfo, PublishPluginRequest, RevokeLicenseRequest, SearchPluginsRequest, SearchPluginsResponse, SpaceResponse, TenantResponse, UpdatePluginRequest, UpdateSpaceRequest, UpdateTenantRequest, ValidateLicenseRequest, ValidateLicenseResponse } from '@objectstack/spec/api'; - -// Validate data -const result = BuildStatusResponse.parse(data); -``` - ---- - -## BuildStatusResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## CompileManifestRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **bom** | `Object` | ✅ | | -| **runtimeVersion** | `string` | optional | | -| **dryRun** | `boolean` | optional | | - - ---- - -## CompileManifestResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## CreateSpaceRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Space display name | -| **slug** | `string` | ✅ | URL-friendly identifier | -| **ownerId** | `string` | ✅ | Owner user/org ID | -| **runtime** | `Object` | optional | Runtime instance configuration | -| **bom** | `Object` | optional | Initial Bill of Materials | -| **subscription** | `Object` | optional | | -| **deployment** | `Object` | optional | | - - ---- - -## CreateTenantRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Tenant display name | -| **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | ✅ | | -| **customizations** | `Record` | optional | Custom configuration values | -| **quotas** | `Object` | optional | | - - ---- - -## GetBuildStatusRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **buildId** | `string` | ✅ | | - - ---- - -## GetMarketplacePluginRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | | - - ---- - -## GetPluginVersionsRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | Plugin identifier | - - ---- - -## GetPluginVersionsResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## HubHealthResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## HubMetricsResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## InstallPluginRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **spaceId** | `string` | ✅ | Target Space ID | -| **pluginId** | `string` | ✅ | Plugin Package ID | -| **version** | `string` | optional | Version requirement | -| **config** | `Record` | optional | Plugin configuration | - - ---- - -## InstallPluginResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `any` | optional | | - - ---- - -## IssueLicenseRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **spaceId** | `string` | ✅ | Target space ID | -| **planCode** | `string` | ✅ | Plan code | -| **expiresAt** | `string` | optional | | -| **customFeatures** | `string[]` | optional | | -| **customLimits** | `Record` | optional | | -| **plugins** | `string[]` | optional | | - - ---- - -## LicenseResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## ListLicensesRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **page** | `integer` | optional | | -| **perPage** | `integer` | optional | | -| **sortBy** | `string` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **spaceId** | `string` | optional | | -| **planCode** | `string` | optional | | -| **status** | `Enum<'active' \| 'expired' \| 'suspended' \| 'trial'>` | optional | | - - ---- - -## ListLicensesResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | | -| **pagination** | `Object` | ✅ | | - - ---- - -## ListMarketplaceRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **page** | `integer` | optional | | -| **perPage** | `integer` | optional | | -| **sortBy** | `string` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **category** | `string` | optional | | -| **tags** | `string[]` | optional | | -| **verified** | `boolean` | optional | | -| **search** | `string` | optional | | - - ---- - -## ListMarketplaceResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | | -| **pagination** | `Object` | ✅ | | -| **categories** | `Object[]` | optional | Available categories with counts | - - ---- - -## ListSpacesRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **page** | `integer` | optional | | -| **perPage** | `integer` | optional | | -| **sortBy** | `string` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **ownerId** | `string` | optional | Filter by owner | -| **search** | `string` | optional | Search in name and slug | - - ---- - -## ListSpacesResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | | -| **pagination** | `Object` | ✅ | | - - ---- - -## ListTenantsRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **page** | `integer` | optional | | -| **perPage** | `integer` | optional | | -| **sortBy** | `string` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | optional | | -| **search** | `string` | optional | | - - ---- - -## ListTenantsResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | | -| **pagination** | `Object` | ✅ | | - - ---- - -## MarketplacePluginResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## PaginationRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **page** | `integer` | optional | | -| **perPage** | `integer` | optional | | -| **sortBy** | `string` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | - - ---- - -## PaginationResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **page** | `integer` | ✅ | | -| **perPage** | `integer` | ✅ | | -| **total** | `integer` | ✅ | | -| **totalPages** | `integer` | ✅ | | -| **hasNext** | `boolean` | ✅ | | -| **hasPrev** | `boolean` | ✅ | | - - ---- - -## PluginResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## PluginVersionInfo - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **version** | `string` | ✅ | | -| **publishedAt** | `string` | ✅ | | -| **deprecated** | `boolean` | optional | | -| **yanked** | `boolean` | optional | Whether this version was removed | -| **changelog** | `string` | optional | | - - ---- - -## PublishPluginRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Plugin identifier (reverse domain notation) | -| **version** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **description** | `string` | optional | | -| **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 | | -| **license** | `string` | optional | SPDX license identifier | -| **pricing** | `Object` | optional | | -| **deprecated** | `boolean` | optional | | -| **deprecationMessage** | `string` | optional | | -| **replacedBy** | `string` | optional | Plugin ID that replaces this one | -| **flags** | `Object` | optional | | - - ---- - -## RevokeLicenseRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **spaceId** | `string` | ✅ | | -| **reason** | `string` | optional | | - - ---- - -## SearchPluginsRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | optional | | -| **category** | `string[]` | optional | | -| **tags** | `string[]` | optional | | -| **trustLevel** | `Enum<'official' \| 'verified' \| 'community' \| 'unverified'>[]` | optional | | -| **implementsProtocols** | `string[]` | optional | | -| **pricingModel** | `Enum<'free' \| 'freemium' \| 'paid' \| 'enterprise'>[]` | optional | | -| **minRating** | `number` | optional | | -| **sortBy** | `Enum<'relevance' \| 'downloads' \| 'rating' \| 'updated' \| 'name'>` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **page** | `integer` | optional | | -| **limit** | `integer` | optional | | - - ---- - -## SearchPluginsResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | | -| **pagination** | `Object` | ✅ | | - - ---- - -## SpaceResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## TenantResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - -## UpdatePluginRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Plugin identifier (reverse domain notation) | -| **version** | `string` | optional | | -| **name** | `string` | optional | | -| **description** | `string` | optional | | -| **readme** | `string` | optional | | -| **category** | `Enum<'data' \| 'integration' \| 'ui' \| 'analytics' \| 'security' \| 'automation' \| 'ai' \| 'utility' \| 'driver' \| 'gateway' \| 'adapter'>` | optional | | -| **tags** | `string[]` | optional | | -| **vendor** | `Object` | optional | | -| **capabilities** | `Object` | optional | | -| **compatibility** | `Object` | optional | | -| **links** | `Object` | optional | | -| **media** | `Object` | optional | | -| **license** | `string` | optional | SPDX license identifier | -| **pricing** | `Object` | optional | | -| **deprecated** | `boolean` | optional | | -| **deprecationMessage** | `string` | optional | | -| **replacedBy** | `string` | optional | Plugin ID that replaces this one | -| **flags** | `Object` | optional | | - - ---- - -## UpdateSpaceRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Space display name | -| **slug** | `string` | optional | URL-friendly identifier | -| **ownerId** | `string` | optional | Owner user/org ID | -| **runtime** | `Object` | optional | Runtime instance configuration | -| **bom** | `Object` | optional | Initial Bill of Materials | -| **subscription** | `Object` | optional | | -| **deployment** | `Object` | optional | | - - ---- - -## UpdateTenantRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Tenant display name | -| **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | optional | | -| **customizations** | `Record` | optional | Custom configuration values | -| **quotas** | `Object` | optional | | - - ---- - -## ValidateLicenseRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **spaceId** | `string` | ✅ | | -| **signature** | `string` | ✅ | License signature/token | - - ---- - -## ValidateLicenseResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - diff --git a/content/docs/references/api/identity.mdx b/content/docs/references/api/identity.mdx deleted file mode 100644 index 91c50f231..000000000 --- a/content/docs/references/api/identity.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Identity -description: Identity protocol schemas ---- - - -**Source:** `packages/spec/src/api/identity.zod.ts` - - -## TypeScript Usage - -```typescript -import { Session } from '@objectstack/spec/api'; -import type { Session } from '@objectstack/spec/api'; - -// Validate data -const result = Session.parse(data); -``` - ---- - -## Session - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **expiresAt** | `string` | ✅ | | -| **token** | `string` | optional | | -| **ipAddress** | `string` | optional | | -| **userAgent** | `string` | optional | | -| **userId** | `string` | ✅ | | - - ---- - diff --git a/content/docs/references/api/index.mdx b/content/docs/references/api/index.mdx index d907988d5..38b57d007 100644 --- a/content/docs/references/api/index.mdx +++ b/content/docs/references/api/index.mdx @@ -11,19 +11,21 @@ This section contains all protocol schemas for the api layer of ObjectStack. + - + + diff --git a/content/docs/references/api/meta.json b/content/docs/references/api/meta.json deleted file mode 100644 index 93483c006..000000000 --- a/content/docs/references/api/meta.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "title": "API Protocol", - "pages": [ - "analytics", - "auth", - "batch", - "connector", - "contract", - "discovery", - "documentation", - "endpoint", - "errors", - "graphql", - "http-cache", - "hub", - "identity", - "metadata", - "odata", - "package-registry", - "protocol", - "realtime", - "registry", - "rest-server", - "router", - "storage", - "view", - "websocket" - ] -} \ No newline at end of file diff --git a/content/docs/references/api/metadata.mdx b/content/docs/references/api/metadata.mdx deleted file mode 100644 index e77e267cb..000000000 --- a/content/docs/references/api/metadata.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Metadata -description: Metadata protocol schemas ---- - -Metadata Service Protocol - -Defines the standard API contracts for fetching system metadata. - -Frontend, IDEs, and Mobile apps use this to build dynamic UIs. - - -**Source:** `packages/spec/src/api/metadata.zod.ts` - - -## TypeScript Usage - -```typescript -import { AppDefinitionResponse, ConceptListResponse, ObjectDefinitionResponse } from '@objectstack/spec/api'; -import type { AppDefinitionResponse, ConceptListResponse, ObjectDefinitionResponse } from '@objectstack/spec/api'; - -// Validate data -const result = AppDefinitionResponse.parse(data); -``` - ---- - -## AppDefinitionResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | Full App Configuration | - - ---- - -## ConceptListResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object[]` | ✅ | List of available concepts (Objects, Apps, Flows) | - - ---- - -## ObjectDefinitionResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | Full Object Schema | - - ---- - diff --git a/content/docs/references/api/odata.mdx b/content/docs/references/api/odata.mdx deleted file mode 100644 index c94daf10a..000000000 --- a/content/docs/references/api/odata.mdx +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Odata -description: Odata protocol schemas ---- - -OData v4 Protocol Support - -Open Data Protocol (OData) v4 is an industry-standard protocol for building - -and consuming RESTful APIs. It provides a uniform way to expose, structure, - -query, and manipulate data. - -## Overview - -OData v4 provides standardized URL conventions for querying data including: - -- $select: Choose which fields to return - -- $filter: Filter results with complex expressions - -- $orderby: Sort results - -- $top/$skip: Pagination - -- $expand: Include related entities - -- $count: Get total count - -## Use Cases - -1. **Enterprise Integration** - -- Integrate with Microsoft Dynamics 365 - -- Connect to SharePoint Online - -- SAP OData services - -2. **API Standardization** - -- Provide consistent query interface - -- Standard pagination and filtering - -- Industry-recognized protocol - -3. **External Data Sources** - -- Connect to OData-compliant systems - -- Federated queries - -- Data virtualization - -@see https://www.odata.org/documentation/ - -@see https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html - -@example OData Query - -``` - -GET /api/odata/customers? - -$select=name,email& - -$filter=country eq 'US' and revenue gt 100000& - -$orderby=revenue desc& - -$top=10& - -$skip=20& - -$expand=orders& - -$count=true - -``` - -@example Programmatic Use - -```typescript - -const query: ODataQuery = { - -select: ['name', 'email'], - -filter: "country eq 'US' and revenue gt 100000", - -orderby: 'revenue desc', - -top: 10, - -skip: 20, - -expand: ['orders'], - -count: true - -} - -``` - - -**Source:** `packages/spec/src/api/odata.zod.ts` - - -## TypeScript Usage - -```typescript -import { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api'; -import type { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api'; - -// Validate data -const result = ODataConfig.parse(data); -``` - ---- - -## ODataConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable OData API | -| **path** | `string` | optional | OData endpoint path | -| **metadata** | `Object` | optional | OData metadata configuration | - - ---- - -## ODataError - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **error** | `Object` | ✅ | | - - ---- - -## ODataFilterFunction - -### Allowed Values - -* `contains` -* `startswith` -* `endswith` -* `length` -* `indexof` -* `substring` -* `tolower` -* `toupper` -* `trim` -* `concat` -* `year` -* `month` -* `day` -* `hour` -* `minute` -* `second` -* `date` -* `time` -* `now` -* `maxdatetime` -* `mindatetime` -* `round` -* `floor` -* `ceiling` -* `cast` -* `isof` -* `any` -* `all` - - ---- - -## ODataFilterOperator - -### Allowed Values - -* `eq` -* `ne` -* `lt` -* `le` -* `gt` -* `ge` -* `and` -* `or` -* `not` -* `(` -* `)` -* `in` -* `has` - - ---- - -## ODataMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **namespace** | `string` | ✅ | Service namespace | -| **entityTypes** | `Object[]` | ✅ | Entity types | -| **entitySets** | `Object[]` | ✅ | Entity sets | - - ---- - -## ODataQuery - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$select** | `string \| string[]` | optional | Fields to select | -| **$filter** | `string` | optional | Filter expression (OData filter syntax) | -| **$orderby** | `string \| string[]` | optional | Sort order | -| **$top** | `integer` | optional | Max results to return | -| **$skip** | `integer` | optional | Results to skip | -| **$expand** | `string \| string[]` | optional | Navigation properties to expand | -| **$count** | `boolean` | optional | Include total count | -| **$search** | `string` | optional | Search expression | -| **$format** | `Enum<'json' \| 'xml' \| 'atom'>` | optional | Response format | -| **$apply** | `string` | optional | Aggregation expression | - - ---- - -## ODataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **@odata.context** | `string` | optional | Metadata context URL | -| **@odata.count** | `integer` | optional | Total results count | -| **@odata.nextLink** | `string` | optional | Next page URL | -| **value** | `Record[]` | ✅ | Results array | - - ---- - diff --git a/content/docs/references/api/package-registry.mdx b/content/docs/references/api/package-registry.mdx deleted file mode 100644 index 754fe3561..000000000 --- a/content/docs/references/api/package-registry.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Package Registry -description: Package Registry protocol schemas ---- - - -**Source:** `packages/spec/src/api/package-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, ListPackagesRequest, ListPackagesResponse, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; -import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, ListPackagesRequest, ListPackagesResponse, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; - -// Validate data -const result = DisablePackageRequest.parse(data); -``` - ---- - -## DisablePackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## DisablePackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## EnablePackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## EnablePackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## GetPackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## GetPackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | - - ---- - -## InstallPackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | | -| **settings** | `Record` | optional | | -| **enableOnInstall** | `boolean` | optional | | - - ---- - -## InstallPackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## ListPackagesRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'uninstalling' \| 'error'>` | optional | | -| **type** | `Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| 'module' \| 'gateway' \| 'adapter'>` | optional | Type of package | -| **enabled** | `boolean` | optional | | - - ---- - -## ListPackagesResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **packages** | `Object[]` | ✅ | | -| **total** | `number` | ✅ | | - - ---- - -## UninstallPackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## UninstallPackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **success** | `boolean` | ✅ | | -| **message** | `string` | optional | | - - ---- - diff --git a/content/docs/references/api/protocol.mdx b/content/docs/references/api/protocol.mdx deleted file mode 100644 index 2f6908f59..000000000 --- a/content/docs/references/api/protocol.mdx +++ /dev/null @@ -1,525 +0,0 @@ ---- -title: Protocol -description: Protocol protocol schemas ---- - -ObjectStack Protocol - Zod Schema Definitions - -Defines the runtime-validated contract for interacting with ObjectStack metadata and data. - -Used by API adapters (HTTP, WebSocket, gRPC) to fetch data/metadata without knowing engine internals. - -This protocol enables: - -- Runtime request/response validation at API gateway level - -- Automatic API documentation generation - -- Type-safe RPC communication between microservices - -- Client SDK generation from schemas - -Architecture Alignment: - -- Salesforce: REST API Request/Response schemas - -- Kubernetes: API Resource schemas with runtime validation - -- GraphQL: Schema-first API design - - -**Source:** `packages/spec/src/api/protocol.zod.ts` - - -## TypeScript Usage - -```typescript -import { AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetUiViewRequest, GetUiViewResponse, ObjectStackProtocol, SaveMetaItemRequest, SaveMetaItemResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse } from '@objectstack/spec/api'; -import type { AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetUiViewRequest, GetUiViewResponse, ObjectStackProtocol, SaveMetaItemRequest, SaveMetaItemResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse } from '@objectstack/spec/api'; - -// Validate data -const result = AutomationTriggerRequest.parse(data); -``` - ---- - -## AutomationTriggerRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trigger** | `string` | ✅ | | -| **payload** | `Record` | ✅ | | - - ---- - -## AutomationTriggerResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | | -| **jobId** | `string` | optional | | -| **result** | `any` | optional | | - - ---- - -## BatchDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **request** | `Object` | ✅ | Batch operation request | - - ---- - -## BatchDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | 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 | - - ---- - -## CreateDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The object name. | -| **data** | `Record` | ✅ | The dictionary of field values to insert. | - - ---- - -## CreateDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The object name. | -| **id** | `string` | ✅ | The ID of the newly created record. | -| **record** | `Record` | ✅ | The created record, including server-generated fields (created_at, owner). | - - ---- - -## CreateManyDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **records** | `Record[]` | ✅ | Array of records to create | - - ---- - -## CreateManyDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **records** | `Record[]` | ✅ | Created records | -| **count** | `number` | ✅ | Number of records created | - - ---- - -## DeleteDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **id** | `string` | ✅ | Record ID to delete | - - ---- - -## DeleteDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **id** | `string` | ✅ | Deleted record ID | -| **success** | `boolean` | ✅ | Whether deletion succeeded | - - ---- - -## DeleteManyDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **ids** | `string[]` | ✅ | Array of record IDs to delete | -| **options** | `Object` | optional | Delete options | - - ---- - -## DeleteManyDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | 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 | - - ---- - -## FindDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The unique machine name of the object to query (e.g. "account"). | -| **query** | `Object` | optional | Structured query definition (filter, sort, select, pagination). | - - ---- - -## FindDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The object name for the returned records. | -| **records** | `Record[]` | ✅ | The list of matching records. | -| **total** | `number` | optional | Total number of records matching the filter (if requested). | -| **hasMore** | `boolean` | optional | True if there are more records available (pagination). | - - ---- - -## GetDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The object name. | -| **id** | `string` | ✅ | The unique record identifier (primary key). | - - ---- - -## GetDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The object name. | -| **id** | `string` | ✅ | The record ID. | -| **record** | `Record` | ✅ | The complete record data. | - - ---- - -## GetDiscoveryRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | - - ---- - -## GetDiscoveryResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **version** | `string` | ✅ | API version (e.g., "v1", "2024-01") | -| **apiName** | `string` | ✅ | API name | -| **capabilities** | `Object` | optional | Supported features/capabilities | -| **endpoints** | `Object` | optional | Available endpoint paths | - - ---- - -## GetMetaItemCachedRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Metadata type name | -| **name** | `string` | ✅ | Item name | -| **cacheRequest** | `Object` | optional | Cache validation parameters | - - ---- - -## GetMetaItemCachedResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `any` | optional | Metadata payload (omitted for 304 Not Modified) | -| **etag** | `Object` | optional | ETag for this resource version | -| **lastModified** | `string` | optional | Last modification timestamp | -| **cacheControl** | `Object` | optional | Cache control directives | -| **notModified** | `boolean` | optional | True if resource has not been modified (304 response) | -| **version** | `string` | optional | Metadata version identifier | - - ---- - -## GetMetaItemRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Metadata type name | -| **name** | `string` | ✅ | Item name (snake_case identifier) | - - ---- - -## GetMetaItemResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Metadata type name | -| **name** | `string` | ✅ | Item name | -| **item** | `any` | optional | Metadata item definition | - - ---- - -## GetMetaItemsRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Metadata type name (e.g., "object", "plugin") | - - ---- - -## GetMetaItemsResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Metadata type name | -| **items** | `any[]` | ✅ | Array of metadata items | - - ---- - -## GetMetaTypesRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | - - ---- - -## GetMetaTypesResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **types** | `string[]` | ✅ | Available metadata type names (e.g., "object", "plugin", "view") | - - ---- - -## GetUiViewRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name (snake_case) | -| **type** | `Enum<'list' \| 'form'>` | ✅ | View type | - - ---- - -## GetUiViewResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **list** | `Object` | optional | | -| **form** | `Object` | optional | | -| **listViews** | `Record` | optional | Additional named list views | -| **formViews** | `Record` | optional | Additional named form views | - - ---- - -## ObjectStackProtocol - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **getDiscovery** | `any` | optional | Get API discovery information | -| **getMetaTypes** | `any` | optional | Get available metadata types | -| **getMetaItems** | `any` | optional | Get all items of a metadata type | -| **getMetaItem** | `any` | optional | Get a specific metadata item | -| **saveMetaItem** | `any` | optional | Save metadata item | -| **getMetaItemCached** | `any` | optional | Get a metadata item with cache validation | -| **getUiView** | `any` | optional | Get UI view definition | -| **analyticsQuery** | `any` | optional | Execute analytics query | -| **getAnalyticsMeta** | `any` | optional | Get analytics metadata (cubes) | -| **triggerAutomation** | `any` | optional | Trigger an automation flow or script | -| **listSpaces** | `any` | optional | List Hub Spaces | -| **createSpace** | `any` | optional | Create Hub Space | -| **installPlugin** | `any` | optional | Install Plugin into Space | -| **listPackages** | `any` | optional | List installed packages with optional filters | -| **getPackage** | `any` | optional | Get a specific installed package by ID | -| **installPackage** | `any` | optional | Install a new package from manifest | -| **uninstallPackage** | `any` | optional | Uninstall a package by ID | -| **enablePackage** | `any` | optional | Enable a disabled package | -| **disablePackage** | `any` | optional | Disable an installed package | -| **findData** | `any` | optional | Find data records | -| **getData** | `any` | optional | Get single data record | -| **createData** | `any` | optional | Create a data record | -| **updateData** | `any` | optional | Update a data record | -| **deleteData** | `any` | optional | Delete a data record | -| **batchData** | `any` | optional | Perform batch operations | -| **createManyData** | `any` | optional | Create multiple records | -| **updateManyData** | `any` | optional | Update multiple records | -| **deleteManyData** | `any` | optional | Delete multiple records | - - ---- - -## SaveMetaItemRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Metadata type name | -| **name** | `string` | ✅ | Item name | -| **item** | `any` | optional | Metadata item definition | - - ---- - -## SaveMetaItemResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## UpdateDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | The object name. | -| **id** | `string` | ✅ | The ID of the record to update. | -| **data** | `Record` | ✅ | The fields to update (partial update). | - - ---- - -## UpdateDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **id** | `string` | ✅ | Updated record ID | -| **record** | `Record` | ✅ | Updated record | - - ---- - -## UpdateManyDataRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name | -| **records** | `Object[]` | ✅ | Array of updates | -| **options** | `Object` | optional | Update options | - - ---- - -## UpdateManyDataResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | 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 | - - ---- - diff --git a/content/docs/references/api/realtime.mdx b/content/docs/references/api/realtime.mdx deleted file mode 100644 index e89f52ca5..000000000 --- a/content/docs/references/api/realtime.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Realtime -description: Realtime protocol schemas ---- - -Transport Protocol Enum - -Defines the communication protocol for realtime data synchronization - - -**Source:** `packages/spec/src/api/realtime.zod.ts` - - -## TypeScript Usage - -```typescript -import { Presence, PresenceStatus, RealtimeAction, RealtimeConfig, RealtimeEvent, RealtimeEventType, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api'; -import type { Presence, PresenceStatus, RealtimeAction, RealtimeConfig, RealtimeEvent, RealtimeEventType, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api'; - -// Validate data -const result = Presence.parse(data); -``` - ---- - -## Presence - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **status** | `Enum<'online' \| 'away' \| 'offline'>` | ✅ | Current presence status | -| **lastSeen** | `string` | ✅ | ISO 8601 datetime of last activity | -| **metadata** | `Record` | optional | Custom presence data (e.g., current page, custom status) | - - ---- - -## PresenceStatus - -### Allowed Values - -* `online` -* `away` -* `offline` - - ---- - -## RealtimeAction - -### Allowed Values - -* `created` -* `updated` -* `deleted` - - ---- - -## RealtimeConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable realtime synchronization | -| **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | optional | Transport protocol | -| **subscriptions** | `Object[]` | optional | Default subscriptions | - - ---- - -## RealtimeEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique event identifier | -| **type** | `string` | ✅ | Event type (e.g., record.created, record.updated) | -| **object** | `string` | optional | Object name the event relates to | -| **action** | `Enum<'created' \| 'updated' \| 'deleted'>` | optional | Action performed | -| **payload** | `Record` | ✅ | Event payload data | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when event occurred | -| **userId** | `string` | optional | User who triggered the event | -| **sessionId** | `string` | optional | Session identifier | - - ---- - -## RealtimeEventType - -### Allowed Values - -* `record.created` -* `record.updated` -* `record.deleted` -* `field.changed` - - ---- - -## Subscription - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique subscription identifier | -| **events** | `Object[]` | ✅ | Array of events to subscribe to | -| **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol to use | -| **channel** | `string` | optional | Optional channel name for grouping subscriptions | - - ---- - -## SubscriptionEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>` | ✅ | Type of event to subscribe to | -| **object** | `string` | optional | Object name to subscribe to | -| **filters** | `any` | optional | Filter conditions | - - ---- - -## TransportProtocol - -### Allowed Values - -* `websocket` -* `sse` -* `polling` - - ---- - diff --git a/content/docs/references/api/registry.mdx b/content/docs/references/api/registry.mdx deleted file mode 100644 index 4ee095ee8..000000000 --- a/content/docs/references/api/registry.mdx +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Registry -description: Registry protocol schemas ---- - -Unified API Registry Protocol - -Provides a centralized registry for managing all API endpoints across different - -API types (REST, GraphQL, OData, WebSocket, Auth, File, Plugin-registered). - -This enables: - -- Unified API discovery and documentation (similar to Swagger/OpenAPI) - -- API testing interfaces - -- API governance and monitoring - -- Plugin API registration - -- Multi-protocol support - -Architecture Alignment: - -- Kubernetes: Service Discovery & API Server - -- AWS API Gateway: Unified API Management - -- Kong Gateway: Plugin-based API Management - -@example API Registry Entry - -```typescript - -const apiEntry: ApiRegistryEntry = { - -id: 'customer_crud', - -name: 'Customer CRUD API', - -type: 'rest', - -version: 'v1', - -basePath: '/api/v1/data/customer', - -endpoints: [...], - -metadata: { - -owner: 'sales_team', - -tags: ['customer', 'crm'] - -} - -} - -``` - - -**Source:** `packages/spec/src/api/registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiMetadata, ApiParameter, ApiProtocolType, ApiRegistry, ApiRegistryEntry, ApiResponse, ConflictResolutionStrategy, HttpStatusCode, ObjectQLReference, SchemaDefinition } from '@objectstack/spec/api'; -import type { ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiMetadata, ApiParameter, ApiProtocolType, ApiRegistry, ApiRegistryEntry, ApiResponse, ConflictResolutionStrategy, HttpStatusCode, ObjectQLReference, SchemaDefinition } from '@objectstack/spec/api'; - -// Validate data -const result = ApiDiscoveryQuery.parse(data); -``` - ---- - -## ApiDiscoveryQuery - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'rest' \| 'graphql' \| 'odata' \| 'websocket' \| 'file' \| 'auth' \| 'metadata' \| 'plugin' \| 'webhook' \| 'rpc'>` | optional | Filter by API protocol type | -| **tags** | `string[]` | optional | Filter by tags (ANY match) | -| **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'beta'>` | optional | Filter by lifecycle status | -| **pluginSource** | `string` | optional | Filter by plugin name | -| **search** | `string` | optional | Full-text search in name/description | -| **version** | `string` | optional | Filter by specific version | - - ---- - -## ApiDiscoveryResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **apis** | `Object[]` | ✅ | Matching API entries | -| **total** | `integer` | ✅ | Total matching APIs | -| **filters** | `Object` | optional | Applied query filters | - - ---- - -## ApiEndpointRegistration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique endpoint identifier | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | optional | HTTP method | -| **path** | `string` | ✅ | URL path pattern | -| **summary** | `string` | optional | Short endpoint summary | -| **description** | `string` | optional | Detailed endpoint description | -| **operationId** | `string` | optional | Unique operation identifier | -| **tags** | `string[]` | optional | Tags for categorization | -| **parameters** | `Object[]` | optional | Endpoint parameters | -| **requestBody** | `Object` | optional | Request body specification | -| **responses** | `Object[]` | optional | Possible responses | -| **rateLimit** | `Object` | optional | Endpoint specific rate limiting | -| **security** | `Record[]` | optional | Security requirements (e.g. [`{"bearerAuth": []}`]) | -| **requiredPermissions** | `string[]` | optional | Required RBAC permissions (e.g., "customer.read", "manage_users") | -| **priority** | `integer` | optional | Route priority for conflict resolution (0-1000, higher = more important) | -| **protocolConfig** | `Record` | optional | Protocol-specific configuration for custom protocols (gRPC, tRPC, etc.) | -| **deprecated** | `boolean` | optional | Whether endpoint is deprecated | -| **externalDocs** | `Object` | optional | External documentation link | - - ---- - -## ApiMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **owner** | `string` | optional | Owner team or person | -| **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'beta'>` | optional | API lifecycle status | -| **tags** | `string[]` | optional | Classification tags | -| **pluginSource** | `string` | optional | Source plugin name | -| **custom** | `Record` | optional | Custom metadata fields | - - ---- - -## ApiParameter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Parameter name | -| **in** | `Enum<'path' \| 'query' \| 'header' \| 'body' \| 'cookie'>` | ✅ | Parameter location | -| **description** | `string` | optional | Parameter description | -| **required** | `boolean` | optional | Whether parameter is required | -| **schema** | `Object \| Object` | ✅ | Parameter schema definition | -| **example** | `any` | optional | Example value | - - ---- - -## ApiProtocolType - -### Allowed Values - -* `rest` -* `graphql` -* `odata` -* `websocket` -* `file` -* `auth` -* `metadata` -* `plugin` -* `webhook` -* `rpc` - - ---- - -## ApiRegistry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **version** | `string` | ✅ | Registry version | -| **conflictResolution** | `Enum<'error' \| 'priority' \| 'first-wins' \| 'last-wins'>` | optional | Strategy for handling route conflicts | -| **apis** | `Object[]` | ✅ | 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 | -| **updatedAt** | `string` | optional | Last registry update time | - - ---- - -## ApiRegistryEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique API identifier (snake_case) | -| **name** | `string` | ✅ | API display name | -| **type** | `Enum<'rest' \| 'graphql' \| 'odata' \| 'websocket' \| 'file' \| 'auth' \| 'metadata' \| 'plugin' \| 'webhook' \| 'rpc'>` | ✅ | API protocol type | -| **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 | -| **config** | `Record` | optional | Protocol-specific configuration | -| **metadata** | `Object` | optional | Additional metadata | -| **termsOfService** | `string` | optional | Terms of service URL | -| **contact** | `Object` | optional | Contact information | -| **license** | `Object` | optional | License information | - - ---- - -## ApiResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **statusCode** | `integer \| Enum<'2xx' \| '3xx' \| '4xx' \| '5xx'>` | ✅ | HTTP status code | -| **description** | `string` | ✅ | Response description | -| **contentType** | `string` | optional | Response content type | -| **schema** | `any \| Object` | optional | Response body schema | -| **headers** | `Record` | optional | Response headers | -| **example** | `any` | optional | Example response | - - ---- - -## ConflictResolutionStrategy - -### Allowed Values - -* `error` -* `priority` -* `first-wins` -* `last-wins` - - ---- - -## HttpStatusCode - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Type: `integer` - ---- - -#### Option 2 - -Allowed Values: `2xx`, `3xx`, `4xx`, `5xx` - ---- - - ---- - -## ObjectQLReference - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **objectId** | `string` | ✅ | Object name to reference | -| **includeFields** | `string[]` | optional | Include only these fields in the schema | -| **excludeFields** | `string[]` | optional | Exclude these fields from the schema | -| **includeRelated** | `string[]` | optional | Include related objects via lookup fields | - - ---- - -## SchemaDefinition - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Static JSON Schema definition - -Type: `any` - ---- - -#### Option 2 - -Dynamic ObjectQL reference - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$ref** | `Object` | ✅ | Dynamic reference to ObjectQL object | - ---- - - ---- - diff --git a/content/docs/references/api/rest-server.mdx b/content/docs/references/api/rest-server.mdx deleted file mode 100644 index 4021a25da..000000000 --- a/content/docs/references/api/rest-server.mdx +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: Rest Server -description: Rest Server protocol schemas ---- - -REST API Server Protocol - -Defines the REST API server configuration for automatically generating - -RESTful CRUD endpoints, metadata endpoints, and batch operations. - -Features: - -- Automatic CRUD endpoint generation from Object definitions - -- Standard REST conventions (GET, POST, PUT, PATCH, DELETE) - -- Metadata API endpoints - -- Batch operation endpoints - -- OpenAPI/Swagger documentation generation - -Architecture alignment: - -- Salesforce: REST API with Object CRUD - -- Microsoft Dynamics: Web API with entity operations - -- Strapi: Auto-generated REST endpoints - - -**Source:** `packages/spec/src/api/rest-server.zod.ts` - - -## TypeScript Usage - -```typescript -import { BatchEndpointsConfig, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api'; -import type { BatchEndpointsConfig, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api'; - -// Validate data -const result = BatchEndpointsConfig.parse(data); -``` - ---- - -## BatchEndpointsConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxBatchSize** | `integer` | optional | Maximum records per batch operation | -| **enableBatchEndpoint** | `boolean` | optional | Enable POST /data/:object/batch endpoint | -| **operations** | `Object` | optional | Enable/disable specific batch operations | -| **defaultAtomic** | `boolean` | optional | Default atomic/transaction mode for batch operations | - - ---- - -## CrudEndpointPattern - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method | -| **path** | `string` | ✅ | URL path pattern | -| **summary** | `string` | optional | Operation summary | -| **description** | `string` | optional | Operation description | - - ---- - -## CrudEndpointsConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operations** | `Object` | optional | Enable/disable operations | -| **patterns** | `Record` | optional | Custom URL patterns for operations | -| **dataPrefix** | `string` | optional | URL prefix for data endpoints | -| **objectParamStyle** | `Enum<'path' \| 'query'>` | optional | How object name is passed (path param or query param) | - - ---- - -## CrudOperation - -### Allowed Values - -* `create` -* `read` -* `update` -* `delete` -* `list` - - ---- - -## EndpointRegistry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **endpoints** | `Object[]` | ✅ | All generated endpoints | -| **total** | `integer` | ✅ | Total number of endpoints | -| **byObject** | `Record` | optional | Endpoints grouped by object | -| **byOperation** | `Record` | optional | Endpoints grouped by operation | - - ---- - -## GeneratedEndpoint - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique endpoint identifier | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method | -| **path** | `string` | ✅ | Full URL path | -| **object** | `string` | ✅ | Object name (snake_case) | -| **operation** | `Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'list'> \| string` | ✅ | Operation type | -| **handler** | `string` | ✅ | Handler function identifier | -| **metadata** | `Object` | optional | | - - ---- - -## MetadataEndpointsConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **prefix** | `string` | optional | URL prefix for metadata endpoints | -| **enableCache** | `boolean` | optional | Enable HTTP cache headers (ETag, Last-Modified) | -| **cacheTtl** | `integer` | optional | Cache TTL in seconds | -| **endpoints** | `Object` | optional | Enable/disable specific endpoints | - - ---- - -## RestApiConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **version** | `string` | optional | API version (e.g., v1, v2, 2024-01) | -| **basePath** | `string` | optional | Base URL path for API | -| **apiPath** | `string` | optional | Full API path (defaults to `{basePath}`/`{version}`) | -| **enableCrud** | `boolean` | optional | Enable automatic CRUD endpoint generation | -| **enableMetadata** | `boolean` | optional | Enable metadata API endpoints | -| **enableUi** | `boolean` | optional | Enable UI API endpoints (Views, Menus, Layouts) | -| **enableBatch** | `boolean` | optional | Enable batch operation endpoints | -| **enableDiscovery** | `boolean` | optional | Enable API discovery endpoint | -| **documentation** | `Object` | optional | OpenAPI/Swagger documentation config | -| **responseFormat** | `Object` | optional | Response format options | - - ---- - -## RestServerConfig - -### Properties - -| 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 | - - ---- - -## RouteGenerationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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'>` | optional | Transform object names in URLs | -| **overrides** | `Record` | optional | Per-object route customization | - - ---- - diff --git a/content/docs/references/api/router.mdx b/content/docs/references/api/router.mdx deleted file mode 100644 index c5d2c4499..000000000 --- a/content/docs/references/api/router.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Router -description: Router protocol schemas ---- - -Route Category Enum - -Classifies routes for middleware application and security policies. - - -**Source:** `packages/spec/src/api/router.zod.ts` - - -## TypeScript Usage - -```typescript -import { RouteCategory, RouteDefinition, RouterConfig } from '@objectstack/spec/api'; -import type { RouteCategory, RouteDefinition, RouterConfig } from '@objectstack/spec/api'; - -// Validate data -const result = RouteCategory.parse(data); -``` - ---- - -## RouteCategory - -### Allowed Values - -* `system` -* `api` -* `auth` -* `static` -* `webhook` -* `plugin` - - ---- - -## RouteDefinition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | | -| **path** | `string` | ✅ | URL Path pattern | -| **category** | `Enum<'system' \| 'api' \| 'auth' \| 'static' \| 'webhook' \| 'plugin'>` | optional | | -| **handler** | `string` | ✅ | Unique handler identifier | -| **summary** | `string` | optional | OpenAPI summary | -| **description** | `string` | optional | OpenAPI description | -| **public** | `boolean` | optional | Is publicly accessible | -| **permissions** | `string[]` | optional | Required permissions | -| **timeout** | `integer` | optional | Execution timeout in ms | -| **rateLimit** | `string` | optional | Rate limit policy name | - - ---- - -## RouterConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **basePath** | `string` | optional | Global API prefix | -| **mounts** | `Object` | optional | | -| **cors** | `Object` | optional | | -| **staticMounts** | `Object[]` | optional | | - - ---- - diff --git a/content/docs/references/api/storage.mdx b/content/docs/references/api/storage.mdx deleted file mode 100644 index 7c7855111..000000000 --- a/content/docs/references/api/storage.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Storage -description: Storage protocol schemas ---- - -Storage Service Protocol - -Defines the API contract for client-side file operations. - -Focuses on secure, direct-to-cloud uploads (Presigned URLs) - -rather than proxying bytes through the API server. - - -**Source:** `packages/spec/src/api/storage.zod.ts` - - -## TypeScript Usage - -```typescript -import { CompleteUploadRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse } from '@objectstack/spec/api'; -import type { CompleteUploadRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse } from '@objectstack/spec/api'; - -// Validate data -const result = CompleteUploadRequest.parse(data); -``` - ---- - -## CompleteUploadRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fileId** | `string` | ✅ | File ID returned from presigned request | -| **eTag** | `string` | optional | S3 ETag verification | - - ---- - -## FileUploadResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | Uploaded file metadata | - - ---- - -## GetPresignedUrlRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **filename** | `string` | ✅ | Original filename | -| **mimeType** | `string` | ✅ | File MIME type | -| **size** | `number` | ✅ | File size in bytes | -| **scope** | `string` | optional | Target storage scope (e.g. user, private, public) | -| **bucket** | `string` | optional | Specific bucket override (admin only) | - - ---- - -## PresignedUrlResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Operation success status | -| **error** | `Object` | optional | Error details if success is false | -| **meta** | `Object` | optional | Response metadata | -| **data** | `Object` | ✅ | | - - ---- - diff --git a/content/docs/references/api/view.mdx b/content/docs/references/api/view.mdx deleted file mode 100644 index 602c0db2b..000000000 --- a/content/docs/references/api/view.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: View -description: View protocol schemas ---- - - -**Source:** `packages/spec/src/api/view.zod.ts` - - -## TypeScript Usage - -```typescript -import { HttpMethod } from '@objectstack/spec/api'; -import type { HttpMethod } from '@objectstack/spec/api'; - -// Validate data -const result = HttpMethod.parse(data); -``` - ---- - -## HttpMethod - -### Allowed Values - -* `GET` -* `POST` -* `PUT` -* `DELETE` -* `PATCH` -* `HEAD` -* `OPTIONS` - - ---- - diff --git a/content/docs/references/api/websocket.mdx b/content/docs/references/api/websocket.mdx deleted file mode 100644 index 662266178..000000000 --- a/content/docs/references/api/websocket.mdx +++ /dev/null @@ -1,629 +0,0 @@ ---- -title: Websocket -description: Websocket protocol schemas ---- - -WebSocket Event Protocol - -Defines the schema for WebSocket-based real-time communication in ObjectStack. - -Supports event subscriptions, filtering, presence tracking, and collaborative editing. - -Industry alignment: Firebase Realtime Database, Socket.IO, Pusher - - -**Source:** `packages/spec/src/api/websocket.zod.ts` - - -## TypeScript Usage - -```typescript -import { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api'; -import type { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api'; - -// Validate data -const result = AckMessage.parse(data); -``` - ---- - -## AckMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **ackMessageId** | `string` | ✅ | ID of the message being acknowledged | -| **success** | `boolean` | ✅ | Whether the operation was successful | -| **error** | `string` | optional | Error message if operation failed | - - ---- - -## CursorMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **cursor** | `Object` | ✅ | Cursor position | - - ---- - -## CursorPosition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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) | -| **color** | `string` | optional | Cursor color for visual representation | -| **userName** | `string` | optional | Display name of user | -| **lastUpdate** | `string` | ✅ | ISO 8601 datetime of last cursor update | - - ---- - -## DocumentState - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **documentId** | `string` | ✅ | Document identifier | -| **version** | `integer` | ✅ | Current document version | -| **content** | `string` | ✅ | Current document content | -| **lastModified** | `string` | ✅ | ISO 8601 datetime of last modification | -| **activeSessions** | `string[]` | ✅ | Active editing session IDs | -| **checksum** | `string` | optional | Content checksum for integrity verification | - - ---- - -## EditMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **operation** | `Object` | ✅ | Edit operation | - - ---- - -## EditOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operationId** | `string` | ✅ | Unique operation identifier | -| **documentId** | `string` | ✅ | Document identifier | -| **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) | -| **content** | `string` | optional | Content to insert/replace | -| **version** | `integer` | ✅ | Document version before this operation | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when operation was created | -| **baseOperationId** | `string` | optional | Previous operation ID this builds upon (for OT) | - - ---- - -## EditOperationType - -### Allowed Values - -* `insert` -* `delete` -* `replace` - - ---- - -## ErrorMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **code** | `string` | ✅ | Error code | -| **message** | `string` | ✅ | Error message | -| **details** | `any` | optional | Additional error details | - - ---- - -## EventFilter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **conditions** | `Object[]` | optional | Array of filter conditions | -| **and** | `any[]` | optional | AND logical combination of filters | -| **or** | `any[]` | optional | OR logical combination of filters | -| **not** | `any` | optional | NOT logical negation of filter | - - ---- - -## EventFilterCondition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field path to filter on (supports dot notation, e.g., "user.email") | -| **operator** | `Enum<'eq' \| 'ne' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'in' \| 'nin' \| 'contains' \| 'startsWith' \| 'endsWith' \| 'exists' \| 'regex'>` | ✅ | Comparison operator | -| **value** | `any` | optional | Value to compare against (not needed for "exists" operator) | - - ---- - -## EventMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscriptionId** | `string` | ✅ | Subscription ID this event belongs to | -| **eventName** | `string` | ✅ | Event name | -| **object** | `string` | optional | Object name the event relates to | -| **payload** | `any` | optional | Event payload data | -| **userId** | `string` | optional | User who triggered the event | - - ---- - -## EventPattern - -Event pattern (supports wildcards like "record.*" or "*.created") - - ---- - -## EventSubscription - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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** | `Object` | optional | Advanced filter conditions for event payloads | -| **channels** | `string[]` | optional | Channel names for scoped subscriptions | - - ---- - -## FilterOperator - -### Allowed Values - -* `eq` -* `ne` -* `gt` -* `gte` -* `lt` -* `lte` -* `in` -* `nin` -* `contains` -* `startsWith` -* `endsWith` -* `exists` -* `regex` - - ---- - -## PingMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | - - ---- - -## PongMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **pingMessageId** | `string` | optional | ID of ping message being responded to | - - ---- - -## PresenceMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **presence** | `Object` | ✅ | Presence state | - - ---- - -## PresenceState - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **sessionId** | `string` | ✅ | Unique session identifier | -| **status** | `Enum<'online' \| 'away' \| 'busy' \| 'offline'>` | ✅ | Current presence status | -| **lastSeen** | `string` | ✅ | ISO 8601 datetime of last activity | -| **currentLocation** | `string` | optional | Current page/route user is viewing | -| **device** | `Enum<'desktop' \| 'mobile' \| 'tablet' \| 'other'>` | optional | Device type | -| **customStatus** | `string` | optional | Custom user status message | -| **metadata** | `Record` | optional | Additional custom presence data | - - ---- - -## PresenceUpdate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **status** | `Enum<'online' \| 'away' \| 'busy' \| 'offline'>` | optional | Updated presence status | -| **currentLocation** | `string` | optional | Updated current location | -| **customStatus** | `string` | optional | Updated custom status message | -| **metadata** | `Record` | optional | Updated metadata | - - ---- - -## SimpleCursorPosition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **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) | - - ---- - -## SimplePresenceState - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **userName** | `string` | ✅ | User display name | -| **status** | `Enum<'online' \| 'away' \| 'offline'>` | ✅ | User presence status | -| **lastSeen** | `number` | ✅ | Unix timestamp of last activity in milliseconds | -| **metadata** | `Record` | optional | Additional presence metadata (e.g., current page, custom status) | - - ---- - -## SubscribeMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscription** | `Object` | ✅ | Subscription configuration | - - ---- - -## UnsubscribeMessage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **request** | `Object` | ✅ | Unsubscribe request | - - ---- - -## UnsubscribeRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **subscriptionId** | `string` | ✅ | Subscription ID to unsubscribe from | - - ---- - -## WebSocketConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | ✅ | WebSocket server URL | -| **protocols** | `string[]` | optional | WebSocket sub-protocols | -| **reconnect** | `boolean` | optional | Enable automatic reconnection | -| **reconnectInterval** | `integer` | optional | Reconnection interval in milliseconds | -| **maxReconnectAttempts** | `integer` | optional | Maximum reconnection attempts | -| **pingInterval** | `integer` | optional | Ping interval in milliseconds | -| **timeout** | `integer` | optional | Message timeout in milliseconds | -| **headers** | `Record` | optional | Custom headers for WebSocket handshake | - - ---- - -## WebSocketEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'subscribe' \| 'unsubscribe' \| 'data-change' \| 'presence-update' \| 'cursor-update' \| 'error'>` | ✅ | Event type | -| **channel** | `string` | ✅ | Channel identifier (e.g., "record.account.123", "user.456") | -| **payload** | `any` | optional | Event payload data | -| **timestamp** | `number` | ✅ | Unix timestamp in milliseconds | - - ---- - -## WebSocketMessage - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `subscribe` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscription** | `Object` | ✅ | Subscription configuration | - ---- - -#### Option 2 - -**Type:** `unsubscribe` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **request** | `Object` | ✅ | Unsubscribe request | - ---- - -#### Option 3 - -**Type:** `event` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **subscriptionId** | `string` | ✅ | Subscription ID this event belongs to | -| **eventName** | `string` | ✅ | Event name | -| **object** | `string` | optional | Object name the event relates to | -| **payload** | `any` | optional | Event payload data | -| **userId** | `string` | optional | User who triggered the event | - ---- - -#### Option 4 - -**Type:** `presence` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **presence** | `Object` | ✅ | Presence state | - ---- - -#### Option 5 - -**Type:** `cursor` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **cursor** | `Object` | ✅ | Cursor position | - ---- - -#### Option 6 - -**Type:** `edit` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **operation** | `Object` | ✅ | Edit operation | - ---- - -#### Option 7 - -**Type:** `ack` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **ackMessageId** | `string` | ✅ | ID of the message being acknowledged | -| **success** | `boolean` | ✅ | Whether the operation was successful | -| **error** | `string` | optional | Error message if operation failed | - ---- - -#### Option 8 - -**Type:** `error` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **code** | `string` | ✅ | Error code | -| **message** | `string` | ✅ | Error message | -| **details** | `any` | optional | Additional error details | - ---- - -#### Option 9 - -**Type:** `ping` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | - ---- - -#### Option 10 - -**Type:** `pong` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **messageId** | `string` | ✅ | Unique message identifier | -| **type** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent | -| **pingMessageId** | `string` | optional | ID of ping message being responded to | - ---- - - ---- - -## WebSocketMessageType - -### Allowed Values - -* `subscribe` -* `unsubscribe` -* `event` -* `ping` -* `pong` -* `ack` -* `error` -* `presence` -* `cursor` -* `edit` - - ---- - -## WebSocketPresenceStatus - -### Allowed Values - -* `online` -* `away` -* `busy` -* `offline` - - ---- - -## WebSocketServerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable WebSocket server | -| **path** | `string` | optional | WebSocket endpoint path | -| **heartbeatInterval** | `number` | optional | Heartbeat interval in milliseconds | -| **reconnectAttempts** | `number` | optional | Maximum reconnection attempts for clients | -| **presence** | `boolean` | optional | Enable presence tracking | -| **cursorSharing** | `boolean` | optional | Enable collaborative cursor sharing | - - ---- - diff --git a/content/docs/references/automation/approval.mdx b/content/docs/references/automation/approval.mdx deleted file mode 100644 index 16daf50af..000000000 --- a/content/docs/references/automation/approval.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Approval -description: Approval protocol schemas ---- - -Approval Step Approver Type - - -**Source:** `packages/spec/src/automation/approval.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApprovalAction, ApprovalActionType, ApprovalProcess, ApprovalStep, ApproverType } from '@objectstack/spec/automation'; -import type { ApprovalAction, ApprovalActionType, ApprovalProcess, ApprovalStep, ApproverType } from '@objectstack/spec/automation'; - -// Validate data -const result = ApprovalAction.parse(data); -``` - ---- - -## ApprovalAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'field_update' \| 'email_alert' \| 'webhook' \| 'script' \| 'connector_action'>` | ✅ | | -| **name** | `string` | ✅ | Action name | -| **config** | `Record` | ✅ | Action configuration | -| **connectorId** | `string` | optional | | -| **actionId** | `string` | optional | | - - ---- - -## ApprovalActionType - -### Allowed Values - -* `field_update` -* `email_alert` -* `webhook` -* `script` -* `connector_action` - - ---- - -## ApprovalProcess - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique process name | -| **label** | `string` | ✅ | Human readable label | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **description** | `string` | optional | | -| **entryCriteria** | `string` | optional | Formula to allow submission | -| **lockRecord** | `boolean` | optional | Lock record from editing during approval | -| **steps** | `Object[]` | ✅ | Sequence of approval steps | -| **onSubmit** | `Object[]` | optional | Actions on initial submission | -| **onFinalApprove** | `Object[]` | optional | Actions on final approval | -| **onFinalReject** | `Object[]` | optional | Actions on final rejection | -| **onRecall** | `Object[]` | optional | Actions on recall | - - ---- - -## ApprovalStep - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Step machine name | -| **label** | `string` | ✅ | Step display label | -| **description** | `string` | optional | | -| **entryCriteria** | `string` | optional | Formula expression to enter this step | -| **approvers** | `Object[]` | ✅ | List of allowed approvers | -| **behavior** | `Enum<'first_response' \| 'unanimous'>` | optional | How to handle multiple approvers | -| **rejectionBehavior** | `Enum<'reject_process' \| 'back_to_previous'>` | optional | What happens if rejected | -| **onApprove** | `Object[]` | optional | Actions on step approval | -| **onReject** | `Object[]` | optional | Actions on step rejection | - - ---- - -## ApproverType - -### Allowed Values - -* `user` -* `role` -* `manager` -* `field` -* `queue` - - ---- - diff --git a/content/docs/references/automation/connector.mdx b/content/docs/references/automation/connector.mdx deleted file mode 100644 index c6226bbf3..000000000 --- a/content/docs/references/automation/connector.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Connector -description: Connector protocol schemas ---- - - -**Source:** `packages/spec/src/automation/connector.zod.ts` - - -## TypeScript Usage - -```typescript -import { Authentication, ConflictResolution, Connector, ConnectorTrigger, DataSyncConfig } from '@objectstack/spec/automation'; -import type { Authentication, ConflictResolution, Connector, ConnectorTrigger, DataSyncConfig } from '@objectstack/spec/automation'; - -// Validate data -const result = Authentication.parse(data); -``` - ---- - -## Authentication - -### Properties - -| 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 | - - ---- - -## ConflictResolution - -### Allowed Values - -* `source_wins` -* `destination_wins` -* `latest_wins` -* `manual` -* `merge` - - ---- - -## Connector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Connector ID (snake_case) | -| **name** | `string` | ✅ | Connector name | -| **description** | `string` | optional | Connector description | -| **version** | `string` | optional | Connector version | -| **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 | -| **author** | `string` | optional | Connector author | -| **documentation** | `string` | optional | Documentation URL | -| **homepage** | `string` | optional | Homepage URL | -| **license** | `string` | optional | License (SPDX identifier) | -| **tags** | `string[]` | optional | Connector tags | -| **verified** | `boolean` | optional | Verified connector | -| **metadata** | `Record` | optional | Custom metadata | - - ---- - -## ConnectorTrigger - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Trigger ID (snake_case) | -| **name** | `string` | ✅ | Trigger name | -| **description** | `string` | optional | Trigger description | -| **type** | `Enum<'webhook' \| 'polling' \| 'stream'>` | ✅ | Trigger mechanism | -| **config** | `Record` | optional | Trigger configuration | -| **outputSchema** | `Record` | optional | Event payload schema | -| **pollingIntervalMs** | `integer` | optional | Polling interval in ms | - - ---- - -## DataSyncConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Sync configuration name (snake_case) | -| **label** | `string` | optional | Sync display name | -| **description** | `string` | optional | Sync description | -| **source** | `Object` | ✅ | Data source | -| **destination** | `Object` | ✅ | Data destination | -| **direction** | `Enum<'push' \| 'pull' \| 'bidirectional'>` | optional | Sync direction | -| **syncMode** | `Enum<'full' \| 'incremental' \| 'realtime'>` | optional | Sync mode | -| **conflictResolution** | `Enum<'source_wins' \| 'destination_wins' \| 'latest_wins' \| 'manual' \| 'merge'>` | optional | Conflict resolution | -| **schedule** | `string` | optional | Cron schedule | -| **enabled** | `boolean` | optional | Sync enabled | -| **changeTrackingField** | `string` | optional | Field for change tracking | -| **batchSize** | `integer` | optional | Batch size for processing | -| **retry** | `Object` | optional | Retry configuration | -| **validation** | `Object` | optional | Validation rules | -| **errorHandling** | `Object` | optional | Error handling | -| **optimization** | `Object` | optional | Performance optimization | -| **audit** | `Object` | optional | Audit configuration | -| **tags** | `string[]` | optional | Sync tags | -| **metadata** | `Record` | optional | Custom metadata | - - ---- - diff --git a/content/docs/references/automation/etl.mdx b/content/docs/references/automation/etl.mdx deleted file mode 100644 index cdf4a755a..000000000 --- a/content/docs/references/automation/etl.mdx +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Etl -description: Etl protocol schemas ---- - -ETL (Extract, Transform, Load) Pipeline Protocol - LEVEL 2: Data Engineering - -Inspired by modern data integration platforms like Airbyte, Fivetran, and Apache NiFi. - -**Positioning in 3-Layer Architecture:** - -- **L1: Simple Sync** (automation/sync.zod.ts) - Business users - Sync Salesforce to Sheets - -- **L2: ETL Pipeline** (THIS FILE) - Data engineers - Aggregate 10 sources to warehouse - -- **L3: Enterprise Connector** (integration/connector.zod.ts) - System integrators - Full SAP integration - -ETL pipelines enable automated data synchronization between systems, transforming - -data as it moves from source to destination. - -**SCOPE: Advanced multi-source, multi-stage transformations.** - -Supports complex operations: joins, aggregations, filtering, custom SQL. - -## When to Use This Layer - -**Use ETL Pipeline when:** - -- Combining data from multiple sources - -- Need aggregations, joins, transformations - -- Building data warehouses or analytics platforms - -- Complex data transformations required - -**Examples:** - -- Sales data from Salesforce + Marketing from HubSpot → Data Warehouse - -- Multi-region databases → Consolidated reporting - -- Legacy system migration with transformation - -**When to downgrade:** - -- Simple 1:1 sync → Use [Simple Sync](./sync.zod.ts) - -**When to upgrade:** - -- Need full connector lifecycle (auth, webhooks, rate limits) → Use [Enterprise Connector](../integration/connector.zod.ts) - -@see [./sync.zod.ts](./sync.zod.ts) for Level 1 (simple sync) - -@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration) - -## Use Cases - -1. **Data Warehouse Population** - -- Extract from multiple operational systems - -- Transform to analytical schema - -- Load into data warehouse - -2. **System Integration** - -- Sync data between CRM and Marketing Automation - -- Keep product catalog synchronized across e-commerce platforms - -- Replicate data for backup/disaster recovery - -3. **Data Migration** - -- Move data from legacy systems to modern platforms - -- Consolidate data from multiple sources - -- Split monolithic databases into microservices - -@see https://airbyte.com/ - -@see https://docs.fivetran.com/ - -@see https://nifi.apache.org/ - -@example - -```typescript - -const salesforceToDB: ETLPipeline = { - -name: 'salesforce_to_postgres', - -label: 'Salesforce Accounts to PostgreSQL', - -source: { - -type: 'api', - -connector: 'salesforce', - -config: { object: 'Account' } - -}, - -destination: { - -type: 'database', - -connector: 'postgres', - -config: { table: 'accounts' } - -}, - -transformations: [ - -{ type: 'map', config: { 'Name': 'account_name' } } - -], - -schedule: '0 2 * * *' // Daily at 2 AM - -} - -``` - - -**Source:** `packages/spec/src/automation/etl.zod.ts` - - -## TypeScript Usage - -```typescript -import { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; -import type { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; - -// Validate data -const result = ETLDestination.parse(data); -``` - ---- - -## ETLDestination - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'database' \| 'api' \| 'file' \| 'stream' \| 'object' \| 'warehouse' \| 'storage' \| 'spreadsheet'>` | ✅ | Destination type | -| **connector** | `string` | optional | Connector ID | -| **config** | `Record` | ✅ | Destination configuration | -| **writeMode** | `Enum<'append' \| 'overwrite' \| 'upsert' \| 'merge'>` | optional | How to write data | -| **primaryKey** | `string[]` | optional | Primary key fields | - - ---- - -## ETLEndpointType - -### Allowed Values - -* `database` -* `api` -* `file` -* `stream` -* `object` -* `warehouse` -* `storage` -* `spreadsheet` - - ---- - -## ETLPipeline - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Pipeline identifier (snake_case) | -| **label** | `string` | optional | Pipeline display name | -| **description** | `string` | optional | Pipeline description | -| **source** | `Object` | ✅ | Data source | -| **destination** | `Object` | ✅ | Data destination | -| **transformations** | `Object[]` | optional | Transformation pipeline | -| **syncMode** | `Enum<'full' \| 'incremental' \| 'cdc'>` | optional | Sync mode | -| **schedule** | `string` | optional | Cron schedule expression | -| **enabled** | `boolean` | optional | Pipeline enabled status | -| **retry** | `Object` | optional | Retry configuration | -| **notifications** | `Object` | optional | Notification settings | -| **tags** | `string[]` | optional | Pipeline tags | -| **metadata** | `Record` | optional | Custom metadata | - - ---- - -## ETLPipelineRun - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Run identifier | -| **pipelineName** | `string` | ✅ | Pipeline name | -| **status** | `Enum<'pending' \| 'running' \| 'succeeded' \| 'failed' \| 'cancelled' \| 'timeout'>` | ✅ | Run status | -| **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 | -| **logs** | `string[]` | optional | Execution logs | - - ---- - -## ETLRunStatus - -### Allowed Values - -* `pending` -* `running` -* `succeeded` -* `failed` -* `cancelled` -* `timeout` - - ---- - -## ETLSource - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | - - ---- - -## ETLSyncMode - -### Allowed Values - -* `full` -* `incremental` -* `cdc` - - ---- - -## ETLTransformation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Transformation name | -| **type** | `Enum<'map' \| 'filter' \| 'aggregate' \| 'join' \| 'script' \| 'lookup' \| 'split' \| 'merge' \| 'normalize' \| 'deduplicate'>` | ✅ | Transformation type | -| **config** | `Record` | ✅ | Transformation config | -| **continueOnError** | `boolean` | optional | Continue on error | - - ---- - -## ETLTransformationType - -### Allowed Values - -* `map` -* `filter` -* `aggregate` -* `join` -* `script` -* `lookup` -* `split` -* `merge` -* `normalize` -* `deduplicate` - - ---- - diff --git a/content/docs/references/automation/events.mdx b/content/docs/references/automation/events.mdx deleted file mode 100644 index dbced3d39..000000000 --- a/content/docs/references/automation/events.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Events -description: Events protocol schemas ---- - - -**Source:** `packages/spec/src/automation/events.zod.ts` - - -## TypeScript Usage - -```typescript -import { Event } from '@objectstack/spec/automation'; -import type { Event } from '@objectstack/spec/automation'; - -// Validate data -const result = Event.parse(data); -``` - ---- - -## Event - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Event Type (e.g. "APPROVE", "REJECT", "Submit") | -| **schema** | `Record` | optional | Expected event payload structure | - - ---- - diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx deleted file mode 100644 index 83a33ca09..000000000 --- a/content/docs/references/automation/flow.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Flow -description: Flow protocol schemas ---- - -Flow Node Types - - -**Source:** `packages/spec/src/automation/flow.zod.ts` - - -## TypeScript Usage - -```typescript -import { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; -import type { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; - -// Validate data -const result = Flow.parse(data); -``` - ---- - -## Flow - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Machine name | -| **label** | `string` | ✅ | Flow label | -| **description** | `string` | optional | | -| **version** | `integer` | optional | Version number | -| **status** | `Enum<'draft' \| 'active' \| 'obsolete' \| 'invalid'>` | optional | Deployment status | -| **template** | `boolean` | optional | Is logic template (Subflow) | -| **type** | `Enum<'autolaunched' \| 'record_change' \| 'schedule' \| 'screen' \| 'api'>` | ✅ | Flow type | -| **variables** | `Object[]` | optional | Flow variables | -| **nodes** | `Object[]` | ✅ | Flow nodes | -| **edges** | `Object[]` | ✅ | Flow connections | -| **active** | `boolean` | optional | Is active (Deprecated: use status) | -| **runAs** | `Enum<'system' \| 'user'>` | optional | Execution context | - - ---- - -## FlowEdge - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Edge unique ID | -| **source** | `string` | ✅ | Source Node ID | -| **target** | `string` | ✅ | Target Node ID | -| **condition** | `string` | optional | Expression returning boolean used for branching | -| **type** | `Enum<'default' \| 'fault'>` | optional | Connection type: Standard (Success) or Fault (Error) path | -| **label** | `string` | optional | Label on the connector | - - ---- - -## FlowNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Node unique ID | -| **type** | `Enum<'start' \| 'end' \| 'decision' \| 'assignment' \| 'loop' \| 'create_record' \| 'update_record' \| 'delete_record' \| 'get_record' \| 'http_request' \| 'script' \| 'wait' \| 'subflow' \| 'connector_action'>` | ✅ | Action type | -| **label** | `string` | ✅ | Node label | -| **config** | `Record` | optional | Node configuration | -| **connectorConfig** | `Object` | optional | | -| **position** | `Object` | optional | | - - ---- - -## FlowNodeAction - -### Allowed Values - -* `start` -* `end` -* `decision` -* `assignment` -* `loop` -* `create_record` -* `update_record` -* `delete_record` -* `get_record` -* `http_request` -* `script` -* `wait` -* `subflow` -* `connector_action` - - ---- - -## FlowVariable - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Variable name | -| **type** | `string` | ✅ | Data type (text, number, boolean, object, list) | -| **isInput** | `boolean` | optional | Is input parameter | -| **isOutput** | `boolean` | optional | Is output parameter | - - ---- - diff --git a/content/docs/references/automation/meta.json b/content/docs/references/automation/meta.json deleted file mode 100644 index 09fde8421..000000000 --- a/content/docs/references/automation/meta.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "title": "Automation Protocol", - "pages": [ - "approval", - "connector", - "etl", - "events", - "flow", - "state-machine", - "sync", - "trigger-registry", - "webhook", - "workflow" - ] -} \ No newline at end of file diff --git a/content/docs/references/automation/state-machine.mdx b/content/docs/references/automation/state-machine.mdx deleted file mode 100644 index a32737d68..000000000 --- a/content/docs/references/automation/state-machine.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: State Machine -description: State Machine protocol schemas ---- - -XState-inspired State Machine Protocol - -Used to define strict business logic constraints and lifecycle management. - -Prevent AI "hallucinations" by enforcing valid valid transitions. - - -**Source:** `packages/spec/src/automation/state-machine.zod.ts` - - -## TypeScript Usage - -```typescript -import { ActionRef, GuardRef, StateMachine, StateNode, Transition } from '@objectstack/spec/automation'; -import type { ActionRef, GuardRef, StateMachine, StateNode, Transition } from '@objectstack/spec/automation'; - -// Validate data -const result = ActionRef.parse(data); -``` - ---- - -## ActionRef - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Action Name - -Type: `string` - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **params** | `Record` | optional | | - ---- - - ---- - -## GuardRef - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Guard Name (e.g., "isManager", "amountGT1000") - -Type: `string` - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **params** | `Record` | optional | | - ---- - - ---- - -## StateMachine - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique Machine ID | -| **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 | | - - ---- - -## StateNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'atomic' \| 'compound' \| 'parallel' \| 'final' \| 'history'>` | optional | | -| **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 | | -| **initial** | `string` | optional | Initial child state (if compound) | -| **states** | `Record` | optional | | -| **meta** | `Object` | optional | | - - ---- - -## Transition - -### Properties - -| 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 | -| **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 deleted file mode 100644 index 0cacad7cb..000000000 --- a/content/docs/references/automation/sync.mdx +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Sync -description: Sync protocol schemas ---- - -Data Sync Protocol - LEVEL 1: Simple Synchronization - -Inspired by Salesforce Connect, Segment Sync, and Census Reverse ETL. - -**Positioning in 3-Layer Architecture:** - -- **L1: Simple Sync** (THIS FILE) - Business users - Sync Salesforce to Sheets - -- **L2: ETL Pipeline** (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse - -- **L3: Enterprise Connector** (integration/connector.zod.ts) - System integrators - Full SAP integration - -Data sync provides bidirectional or unidirectional data synchronization - -between ObjectStack and external systems, maintaining data consistency - -across platforms. - -**SCOPE: Simple field mappings only. NO complex transformations.** - -For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (Level 2). - -## When to Use This Layer - -**Use Simple Sync when:** - -- Syncing 1:1 fields between two systems - -- Simple field transformations (uppercase, cast, etc.) - -- No complex logic required - -- Business users need to configure integrations - -**Examples:** - -- Salesforce Contact ↔ Google Sheets - -- HubSpot Company ↔ CRM Account - -- Shopify Orders → Accounting System - -**When to upgrade:** - -- Need multi-source joins → Use [ETL Pipeline](./etl.zod.ts) - -- Need complex authentication/webhooks → Use [Enterprise Connector](../integration/connector.zod.ts) - -- Need aggregations or data warehousing → Use [ETL Pipeline](./etl.zod.ts) - -@see [./etl.zod.ts](./etl.zod.ts) for Level 2 (data engineering) - -@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration) - -## Use Cases - -1. **CRM Integration** - -- Sync contacts between ObjectStack and Salesforce - -- Keep opportunity data synchronized - -- Bidirectional updates - -2. **Customer Data Platform (CDP)** - -- Sync user profiles to Segment - -- Enrichment data from Clearbit - -- Marketing automation sync - -3. **Operational Analytics** - -- Sync production data to analytics warehouse - -- Real-time dashboards - -- Business intelligence - -@see https://help.salesforce.com/s/articleView?id=sf.platform_connect_about.htm - -@see https://segment.com/docs/connections/sync/ - -@see https://www.getcensus.com/ - -@example - -```typescript - -const contactSync: DataSyncConfig = { - -name: 'salesforce_contact_sync', - -label: 'Salesforce Contact Sync', - -source: { - -object: 'contact', - -filters: { status: 'active' } - -}, - -destination: { - -connector: 'salesforce', - -operation: 'upsert_contact', - -mapping: { - -first_name: 'FirstName', - -last_name: 'LastName', - -email: 'Email' - -} - -}, - -syncMode: 'incremental', - -schedule: '0 * * * *' // Hourly - -} - -``` - - -**Source:** `packages/spec/src/automation/sync.zod.ts` - - -## TypeScript Usage - -```typescript -import { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; -import type { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; - -// Validate data -const result = DataDestinationConfig.parse(data); -``` - ---- - -## DataDestinationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | optional | ObjectStack object name | -| **connectorInstanceId** | `string` | optional | Connector instance ID | -| **operation** | `Enum<'insert' \| 'update' \| 'upsert' \| 'delete' \| 'sync'>` | ✅ | Sync operation | -| **mapping** | `Record \| Object[]` | optional | Field mappings | -| **externalResource** | `string` | optional | External resource ID | -| **matchKey** | `string[]` | optional | Match key fields | - - ---- - -## DataSourceConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | optional | ObjectStack object name | -| **filters** | `any` | optional | Filter conditions | -| **fields** | `string[]` | optional | Fields to sync | -| **connectorInstanceId** | `string` | optional | Connector instance ID | -| **externalResource** | `string` | optional | External resource ID | - - ---- - -## SyncDirection - -### Allowed Values - -* `push` -* `pull` -* `bidirectional` - - ---- - -## SyncExecutionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Execution ID | -| **syncName** | `string` | ✅ | Sync name | -| **status** | `Enum<'pending' \| 'running' \| 'completed' \| 'partial' \| 'failed' \| 'cancelled'>` | ✅ | Execution status | -| **startedAt** | `string` | ✅ | Start time | -| **completedAt** | `string` | optional | Completion time | -| **durationMs** | `number` | optional | Duration in ms | -| **stats** | `Object` | optional | Execution statistics | -| **errors** | `Object[]` | optional | Errors | -| **logs** | `string[]` | optional | Execution logs | - - ---- - -## SyncExecutionStatus - -### Allowed Values - -* `pending` -* `running` -* `completed` -* `partial` -* `failed` -* `cancelled` - - ---- - -## SyncMode - -### Allowed Values - -* `full` -* `incremental` -* `realtime` - - ---- - diff --git a/content/docs/references/automation/trigger-registry.mdx b/content/docs/references/automation/trigger-registry.mdx deleted file mode 100644 index 2baebe727..000000000 --- a/content/docs/references/automation/trigger-registry.mdx +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: Trigger Registry -description: Trigger Registry protocol schemas ---- - -Trigger Registry Protocol - -Lightweight automation triggers for simple integrations. - -Inspired by Zapier, n8n, and Workato connector architectures. - -## When to use Trigger Registry vs. Integration Connector? - -**Use `automation/trigger-registry.zod.ts` when:** - -- Building simple automation triggers (e.g., "when Slack message received, create task") - -- No complex authentication needed (simple API keys, basic auth) - -- Lightweight, single-purpose integrations - -- Quick setup with minimal configuration - -- Webhook-based or polling triggers for automation workflows - -**Use `integration/connector.zod.ts` when:** - -- Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) - -- Complex OAuth2/SAML authentication required - -- Bidirectional sync with field mapping and transformations - -- Webhook management and rate limiting required - -- Full CRUD operations and data synchronization - -## Use Cases - -1. **Simple Automation Triggers** - -- Slack notifications on record updates - -- Twilio SMS on workflow events - -- SendGrid email templates - -2. **Lightweight Operations** - -- Single-action integrations (send, notify, log) - -- No bidirectional sync required - -- Webhook receivers for incoming events - -3. **Quick Integrations** - -- Payment webhooks (Stripe, PayPal) - -- Communication triggers (Twilio, SendGrid, Slack) - -- Simple API calls to third-party services - -@see https://zapier.com/developer/documentation/v2/ - -@see https://docs.n8n.io/integrations/creating-nodes/ - -@see ../../integration/connector.zod.ts for enterprise connectors - -@example - -```typescript - -const slackNotifier: Connector = { - -id: 'slack_notify', - -name: 'Slack Notification', - -category: 'communication', - -authentication: { - -type: 'apiKey', - -fields: [{ name: 'webhook_url', label: 'Webhook URL', type: 'url' }] - -}, - -operations: [ - -{ id: 'send_message', name: 'Send Message', type: 'action' } - -] - -} - -``` - - -**Source:** `packages/spec/src/automation/trigger-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { AuthField, AuthenticationType, ConnectorCategory, ConnectorInstance, ConnectorOperation, OAuth2Config, OperationParameter, OperationType } from '@objectstack/spec/automation'; -import type { AuthField, AuthenticationType, ConnectorCategory, ConnectorInstance, ConnectorOperation, OAuth2Config, OperationParameter, OperationType } from '@objectstack/spec/automation'; - -// Validate data -const result = AuthField.parse(data); -``` - ---- - -## AuthField - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Field name (snake_case) | -| **label** | `string` | ✅ | Field label | -| **type** | `Enum<'text' \| 'password' \| 'url' \| 'select'>` | optional | Field type | -| **description** | `string` | optional | Field description | -| **required** | `boolean` | optional | Required field | -| **default** | `string` | optional | Default value | -| **options** | `Object[]` | optional | Select field options | -| **placeholder** | `string` | optional | Placeholder text | - - ---- - -## AuthenticationType - -### Allowed Values - -* `none` -* `apiKey` -* `basic` -* `bearer` -* `oauth1` -* `oauth2` -* `custom` - - ---- - -## ConnectorCategory - -### Allowed Values - -* `crm` -* `payment` -* `communication` -* `storage` -* `analytics` -* `database` -* `marketing` -* `accounting` -* `hr` -* `productivity` -* `ecommerce` -* `support` -* `devtools` -* `social` -* `other` - - ---- - -## ConnectorInstance - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Instance ID | -| **connectorId** | `string` | ✅ | Connector ID | -| **name** | `string` | ✅ | Instance name | -| **description** | `string` | optional | Instance description | -| **credentials** | `Record` | ✅ | Encrypted credentials | -| **config** | `Record` | optional | Additional config | -| **active** | `boolean` | optional | Instance active status | -| **createdAt** | `string` | optional | Creation time | -| **lastTestedAt** | `string` | optional | Last test time | -| **testStatus** | `Enum<'unknown' \| 'success' \| 'failed'>` | optional | Connection test status | - - ---- - -## ConnectorOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Operation ID (snake_case) | -| **name** | `string` | ✅ | Operation name | -| **description** | `string` | optional | Operation description | -| **type** | `Enum<'read' \| 'write' \| 'delete' \| 'search' \| 'trigger' \| 'action'>` | ✅ | Operation type | -| **inputSchema** | `Object[]` | optional | Input parameters | -| **outputSchema** | `Record` | optional | Output schema | -| **sampleOutput** | `any` | optional | Sample output | -| **supportsPagination** | `boolean` | optional | Supports pagination | -| **supportsFiltering** | `boolean` | optional | Supports filtering | - - ---- - -## OAuth2Config - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **authorizationUrl** | `string` | ✅ | Authorization endpoint URL | -| **tokenUrl** | `string` | ✅ | Token endpoint URL | -| **scopes** | `string[]` | optional | OAuth scopes | -| **clientIdField** | `string` | optional | Client ID field name | -| **clientSecretField** | `string` | optional | Client secret field name | - - ---- - -## OperationParameter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Parameter name | -| **label** | `string` | ✅ | Parameter label | -| **description** | `string` | optional | Parameter description | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'date' \| 'file'>` | ✅ | Parameter type | -| **required** | `boolean` | optional | Required parameter | -| **default** | `any` | optional | Default value | -| **validation** | `Record` | optional | Validation rules | -| **dynamicOptions** | `string` | optional | Function to load dynamic options | - - ---- - -## OperationType - -### Allowed Values - -* `read` -* `write` -* `delete` -* `search` -* `trigger` -* `action` - - ---- - diff --git a/content/docs/references/automation/webhook.mdx b/content/docs/references/automation/webhook.mdx deleted file mode 100644 index 1a73d1a64..000000000 --- a/content/docs/references/automation/webhook.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Webhook -description: Webhook protocol schemas ---- - -Webhook Trigger Event - -When should this webhook fire? - - -**Source:** `packages/spec/src/automation/webhook.zod.ts` - - -## TypeScript Usage - -```typescript -import { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation'; -import type { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation'; - -// Validate data -const result = Webhook.parse(data); -``` - ---- - -## Webhook - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Webhook unique name (lowercase snake_case) | -| **label** | `string` | optional | Human-readable webhook label | -| **object** | `string` | optional | Object to listen to (optional for manual webhooks) | -| **triggers** | `Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]` | optional | Events that trigger execution | -| **url** | `string` | ✅ | External webhook endpoint URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | optional | HTTP method | -| **headers** | `Record` | optional | Custom HTTP headers | -| **body** | `any` | optional | Request body payload (if not using default record data) | -| **payloadFields** | `string[]` | optional | Fields to include. Empty = All | -| **includeSession** | `boolean` | optional | Include user session info | -| **authentication** | `Object` | optional | Authentication configuration | -| **retryPolicy** | `Object` | optional | Retry policy configuration | -| **timeoutMs** | `integer` | optional | Request timeout in milliseconds | -| **secret** | `string` | optional | Signing secret for HMAC signature verification | -| **isActive** | `boolean` | optional | Whether webhook is active | -| **description** | `string` | optional | Webhook description | -| **tags** | `string[]` | optional | Tags for organization | - - ---- - -## WebhookReceiver - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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'>` | optional | | -| **verificationParams** | `Object` | optional | | -| **action** | `Enum<'trigger_flow' \| 'script' \| 'upsert_record'>` | optional | | -| **target** | `string` | ✅ | Flow ID or Script name | - - ---- - -## WebhookTriggerType - -### Allowed Values - -* `create` -* `update` -* `delete` -* `undelete` -* `api` - - ---- - diff --git a/content/docs/references/automation/workflow.mdx b/content/docs/references/automation/workflow.mdx deleted file mode 100644 index a20dfda8c..000000000 --- a/content/docs/references/automation/workflow.mdx +++ /dev/null @@ -1,315 +0,0 @@ ---- -title: Workflow -description: Workflow protocol schemas ---- - -Trigger events for workflow automation - - -**Source:** `packages/spec/src/automation/workflow.zod.ts` - - -## TypeScript Usage - -```typescript -import { ConnectorActionRef, CustomScriptAction, EmailAlertAction, FieldUpdateAction, HttpCallAction, PushNotificationAction, TaskCreationAction, TimeTrigger, WorkflowAction, WorkflowRule, WorkflowTriggerType } from '@objectstack/spec/automation'; -import type { ConnectorActionRef, CustomScriptAction, EmailAlertAction, FieldUpdateAction, HttpCallAction, PushNotificationAction, TaskCreationAction, TimeTrigger, WorkflowAction, WorkflowRule, WorkflowTriggerType } from '@objectstack/spec/automation'; - -// Validate data -const result = ConnectorActionRef.parse(data); -``` - ---- - -## ConnectorActionRef - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **connectorId** | `string` | ✅ | Target Connector ID (e.g. slack, twilio) | -| **actionId** | `string` | ✅ | Target Action ID (e.g. send_message) | -| **input** | `Record` | ✅ | Input parameters matching the action schema | - - ---- - -## CustomScriptAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **language** | `Enum<'javascript' \| 'typescript' \| 'python'>` | optional | Script language | -| **code** | `string` | ✅ | Script code to execute | -| **timeout** | `number` | optional | Execution timeout in milliseconds | -| **context** | `Record` | optional | Additional context variables | - - ---- - -## EmailAlertAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **template** | `string` | ✅ | Email template ID/DevName | -| **recipients** | `string[]` | ✅ | List of recipient emails or user IDs | - - ---- - -## FieldUpdateAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | Field to update | -| **value** | `any` | optional | Value or Formula to set | - - ---- - -## HttpCallAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Target URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'>` | optional | HTTP Method | -| **headers** | `Record` | optional | HTTP Headers | -| **body** | `string` | optional | Request body (JSON or text) | - - ---- - -## PushNotificationAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **title** | `string` | ✅ | Notification title | -| **body** | `string` | ✅ | Notification body text | -| **recipients** | `string[]` | ✅ | User IDs or device tokens | -| **data** | `Record` | optional | Additional data payload | -| **badge** | `number` | optional | Badge count (iOS) | -| **sound** | `string` | optional | Notification sound | -| **clickAction** | `string` | optional | Action/URL when notification is clicked | - - ---- - -## TaskCreationAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **taskObject** | `string` | ✅ | Task object name (e.g., "task", "project_task") | -| **subject** | `string` | ✅ | Task subject/title | -| **description** | `string` | optional | Task description | -| **assignedTo** | `string` | optional | User ID or field reference for assignee | -| **dueDate** | `string` | optional | Due date (ISO string or formula) | -| **priority** | `string` | optional | Task priority | -| **relatedTo** | `string` | optional | Related record ID or field reference | -| **additionalFields** | `Record` | optional | Additional custom fields | - - ---- - -## TimeTrigger - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique identifier | -| **timeLength** | `integer` | ✅ | Duration amount (e.g. 1, 30) | -| **timeUnit** | `Enum<'minutes' \| 'hours' \| 'days'>` | ✅ | Unit of time | -| **offsetDirection** | `Enum<'before' \| 'after'>` | ✅ | Before or After the reference date | -| **offsetFrom** | `Enum<'trigger_date' \| 'date_field'>` | ✅ | Basis for calculation | -| **dateField** | `string` | optional | Date field to calculate from (required if offsetFrom is date_field) | -| **actions** | `Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | Actions to execute at the scheduled time | - - ---- - -## WorkflowAction - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `field_update` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | Field to update | -| **value** | `any` | optional | Value or Formula to set | - ---- - -#### Option 2 - -**Type:** `email_alert` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **template** | `string` | ✅ | Email template ID/DevName | -| **recipients** | `string[]` | ✅ | List of recipient emails or user IDs | - ---- - -#### Option 3 - -**Type:** `http_call` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Target URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'>` | optional | HTTP Method | -| **headers** | `Record` | optional | HTTP Headers | -| **body** | `string` | optional | Request body (JSON or text) | - ---- - -#### Option 4 - -**Type:** `connector_action` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **connectorId** | `string` | ✅ | Target Connector ID (e.g. slack, twilio) | -| **actionId** | `string` | ✅ | Target Action ID (e.g. send_message) | -| **input** | `Record` | ✅ | Input parameters matching the action schema | - ---- - -#### Option 5 - -**Type:** `task_creation` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **taskObject** | `string` | ✅ | Task object name (e.g., "task", "project_task") | -| **subject** | `string` | ✅ | Task subject/title | -| **description** | `string` | optional | Task description | -| **assignedTo** | `string` | optional | User ID or field reference for assignee | -| **dueDate** | `string` | optional | Due date (ISO string or formula) | -| **priority** | `string` | optional | Task priority | -| **relatedTo** | `string` | optional | Related record ID or field reference | -| **additionalFields** | `Record` | optional | Additional custom fields | - ---- - -#### Option 6 - -**Type:** `push_notification` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **title** | `string` | ✅ | Notification title | -| **body** | `string` | ✅ | Notification body text | -| **recipients** | `string[]` | ✅ | User IDs or device tokens | -| **data** | `Record` | optional | Additional data payload | -| **badge** | `number` | optional | Badge count (iOS) | -| **sound** | `string` | optional | Notification sound | -| **clickAction** | `string` | optional | Action/URL when notification is clicked | - ---- - -#### Option 7 - -**Type:** `custom_script` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Action name | -| **type** | `string` | ✅ | | -| **language** | `Enum<'javascript' \| 'typescript' \| 'python'>` | optional | Script language | -| **code** | `string` | ✅ | Script code to execute | -| **timeout** | `number` | optional | Execution timeout in milliseconds | -| **context** | `Record` | optional | Additional context variables | - ---- - - ---- - -## WorkflowRule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique workflow name (lowercase snake_case) | -| **objectName** | `string` | ✅ | Target Object | -| **triggerType** | `Enum<'on_create' \| 'on_update' \| 'on_create_or_update' \| 'on_delete' \| 'schedule'>` | ✅ | When to evaluate | -| **criteria** | `string` | optional | Formula condition. If TRUE, actions execute. | -| **actions** | `Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | optional | Immediate actions | -| **timeTriggers** | `Object[]` | optional | Scheduled actions relative to trigger or date field | -| **active** | `boolean` | optional | Whether this workflow is active | -| **reevaluateOnChange** | `boolean` | optional | Re-evaluate rule if field updates change the record validity | - - ---- - -## WorkflowTriggerType - -### Allowed Values - -* `on_create` -* `on_update` -* `on_create_or_update` -* `on_delete` -* `schedule` - - ---- - diff --git a/content/docs/references/contracts/meta.json b/content/docs/references/contracts/meta.json deleted file mode 100644 index 532dffd33..000000000 --- a/content/docs/references/contracts/meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Contracts Protocol", - "pages": [] -} \ No newline at end of file diff --git a/content/docs/references/data/analytics.mdx b/content/docs/references/data/analytics.mdx deleted file mode 100644 index 9bd580bd0..000000000 --- a/content/docs/references/data/analytics.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Analytics -description: Analytics protocol schemas ---- - -Analytics/Semantic Layer Protocol - -Defines the "Business Logic" for data analysis. - -Inspired by Cube.dev, LookML, and dbt MetricFlow. - -This layer decouples the "Physical Data" (Tables/Columns) from the - -"Business Data" (Metrics/Dimensions). - - -**Source:** `packages/spec/src/data/analytics.zod.ts` - - -## TypeScript Usage - -```typescript -import { AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data'; -import type { AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data'; - -// Validate data -const result = AnalyticsQuery.parse(data); -``` - ---- - -## AnalyticsQuery - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **measures** | `string[]` | ✅ | List of metrics to calculate | -| **dimensions** | `string[]` | optional | List of dimensions to group by | -| **filters** | `Object[]` | optional | | -| **timeDimensions** | `Object[]` | optional | | -| **order** | `Record>` | optional | | -| **limit** | `number` | optional | | -| **offset** | `number` | optional | | -| **timezone** | `string` | optional | | - - ---- - -## Cube - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Cube name (snake_case) | -| **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 | | -| **public** | `boolean` | optional | | - - ---- - -## CubeJoin - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Target cube name | -| **relationship** | `Enum<'one_to_one' \| 'one_to_many' \| 'many_to_one'>` | optional | | -| **sql** | `string` | ✅ | Join condition (ON clause) | - - ---- - -## Dimension - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique dimension ID | -| **label** | `string` | ✅ | Human readable label | -| **description** | `string` | optional | | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'time' \| 'geo'>` | ✅ | | -| **sql** | `string` | ✅ | SQL expression or column reference | -| **granularities** | `Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>[]` | optional | | - - ---- - -## DimensionType - -### Allowed Values - -* `string` -* `number` -* `boolean` -* `time` -* `geo` - - ---- - -## Metric - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique metric ID | -| **label** | `string` | ✅ | Human readable label | -| **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 | | -| **format** | `string` | optional | | - - ---- - -## TimeUpdateInterval - -### Allowed Values - -* `second` -* `minute` -* `hour` -* `day` -* `week` -* `month` -* `quarter` -* `year` - - ---- - diff --git a/content/docs/references/data/data-engine.mdx b/content/docs/references/data/data-engine.mdx deleted file mode 100644 index 03ee6a4ac..000000000 --- a/content/docs/references/data/data-engine.mdx +++ /dev/null @@ -1,464 +0,0 @@ ---- -title: Data Engine -description: Data Engine protocol schemas ---- - -Data Engine Protocol - -Defines the standard interface for data persistence engines in ObjectStack. - -This protocol abstracts the underlying storage mechanism (SQL, NoSQL, API, Memory), - -allowing the ObjectQL engine to execute standardized CRUD and Aggregation operations - -regardless of where the data resides. - -The Data Engine acts as the "Driver" layer in the Hexagonal Architecture. - - -**Source:** `packages/spec/src/data/data-engine.zod.ts` - - -## TypeScript Usage - -```typescript -import { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineContract, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data'; -import type { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineContract, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data'; - -// Validate data -const result = DataEngineAggregateOptions.parse(data); -``` - ---- - -## DataEngineAggregateOptions - -Options for DataEngine.aggregate operations - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | -| **groupBy** | `string[]` | optional | | -| **aggregations** | `Object[]` | optional | | - - ---- - -## DataEngineAggregateRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | ✅ | Options for DataEngine.aggregate operations | - - ---- - -## DataEngineBatchRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **requests** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | | -| **transaction** | `boolean` | optional | | - - ---- - -## DataEngineContract - -Standard Data Engine Contract - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | - - ---- - -## DataEngineCountOptions - -Options for DataEngine.count operations - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | - - ---- - -## DataEngineCountRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | optional | Options for DataEngine.count operations | - - ---- - -## DataEngineDeleteOptions - -Options for DataEngine.delete operations - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | -| **multi** | `boolean` | optional | | - - ---- - -## DataEngineDeleteRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **id** | `any` | optional | ID for single delete, or use filter in options | -| **options** | `Object` | optional | Options for DataEngine.delete operations | - - ---- - -## DataEngineExecuteRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **command** | `any` | optional | | -| **options** | `Record` | optional | | - - ---- - -## DataEngineFilter - -Data Engine query filter conditions - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Type: `Record` - ---- - -#### Option 2 - -Type: `any` - ---- - - ---- - -## DataEngineFindOneRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | optional | Query options for IDataEngine.find() operations | - - ---- - -## DataEngineFindRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | optional | Query options for IDataEngine.find() operations | - - ---- - -## DataEngineInsertOptions - -Options for DataEngine.insert operations - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **returning** | `boolean` | optional | | - - ---- - -## DataEngineInsertRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **data** | `Record \| Record[]` | ✅ | | -| **options** | `Object` | optional | Options for DataEngine.insert operations | - - ---- - -## DataEngineQueryOptions - -Query options for IDataEngine.find() operations - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | -| **select** | `string[]` | optional | | -| **sort** | `Record> \| Record> \| Object[]` | optional | Sort order definition | -| **limit** | `integer` | optional | | -| **skip** | `integer` | optional | | -| **top** | `integer` | optional | | -| **populate** | `string[]` | optional | | - - ---- - -## DataEngineRequest - -Virtual ObjectQL Request Protocol - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | optional | Query options for IDataEngine.find() operations | - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | optional | Query options for IDataEngine.find() operations | - ---- - -#### Option 3 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **data** | `Record \| Record[]` | ✅ | | -| **options** | `Object` | optional | Options for DataEngine.insert operations | - ---- - -#### Option 4 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **data** | `Record` | ✅ | | -| **id** | `any` | optional | ID for single update, or use filter in options | -| **options** | `Object` | optional | Options for DataEngine.update operations | - ---- - -#### Option 5 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **id** | `any` | optional | ID for single delete, or use filter in options | -| **options** | `Object` | optional | Options for DataEngine.delete operations | - ---- - -#### Option 6 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | optional | Options for DataEngine.count operations | - ---- - -#### Option 7 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **query** | `Object` | ✅ | Options for DataEngine.aggregate operations | - ---- - -#### Option 8 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **requests** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | | -| **transaction** | `boolean` | optional | | - ---- - -#### Option 9 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **command** | `any` | optional | | -| **options** | `Record` | optional | | - ---- - -#### Option 10 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **vector** | `number[]` | ✅ | | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | -| **select** | `string[]` | optional | | -| **limit** | `integer` | optional | | -| **threshold** | `number` | optional | | - ---- - - ---- - -## DataEngineSort - -Sort order definition - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Type: `Record>` - ---- - -#### Option 2 - -Type: `Record>` - ---- - -#### Option 3 - -Type: `Object[]` - ---- - - ---- - -## DataEngineUpdateOptions - -Options for DataEngine.update operations - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | -| **upsert** | `boolean` | optional | | -| **multi** | `boolean` | optional | | -| **returning** | `boolean` | optional | | - - ---- - -## DataEngineUpdateRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **data** | `Record` | ✅ | | -| **id** | `any` | optional | ID for single update, or use filter in options | -| **options** | `Object` | optional | Options for DataEngine.update operations | - - ---- - -## DataEngineVectorFindRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **method** | `string` | ✅ | | -| **object** | `string` | ✅ | | -| **vector** | `number[]` | ✅ | | -| **filter** | `Record \| any` | optional | Data Engine query filter conditions | -| **select** | `string[]` | optional | | -| **limit** | `integer` | optional | | -| **threshold** | `number` | optional | | - - ---- - diff --git a/content/docs/references/data/dataset.mdx b/content/docs/references/data/dataset.mdx deleted file mode 100644 index 93c9a9cbb..000000000 --- a/content/docs/references/data/dataset.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Dataset -description: Dataset protocol schemas ---- - -Data Import Strategy - -Defines how the engine handles existing records. - - -**Source:** `packages/spec/src/data/dataset.zod.ts` - - -## TypeScript Usage - -```typescript -import { Dataset, DatasetMode } from '@objectstack/spec/data'; -import type { Dataset, DatasetMode } from '@objectstack/spec/data'; - -// Validate data -const result = Dataset.parse(data); -``` - ---- - -## Dataset - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Target Object Name | -| **externalId** | `string` | optional | Field match for uniqueness check | -| **mode** | `Enum<'insert' \| 'update' \| 'upsert' \| 'replace' \| 'ignore'>` | optional | Conflict resolution strategy | -| **env** | `Enum<'prod' \| 'dev' \| 'test'>[]` | optional | Applicable environments | -| **records** | `Record[]` | ✅ | Data records | - - ---- - -## DatasetMode - -### Allowed Values - -* `insert` -* `update` -* `upsert` -* `replace` -* `ignore` - - ---- - diff --git a/content/docs/references/data/datasource.mdx b/content/docs/references/data/datasource.mdx deleted file mode 100644 index 5bbe6a9a8..000000000 --- a/content/docs/references/data/datasource.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Datasource -description: Datasource protocol schemas ---- - -Driver Identifier - -Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowflake"). - - -**Source:** `packages/spec/src/data/datasource.zod.ts` - - -## TypeScript Usage - -```typescript -import { Datasource, DatasourceCapabilities, DriverDefinition, DriverType } from '@objectstack/spec/data'; -import type { Datasource, DatasourceCapabilities, DriverDefinition, DriverType } from '@objectstack/spec/data'; - -// Validate data -const result = Datasource.parse(data); -``` - ---- - -## Datasource - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique datasource identifier | -| **label** | `string` | optional | Display label | -| **driver** | `string` | ✅ | Underlying driver type | -| **config** | `Record` | ✅ | Driver specific configuration | -| **pool** | `Object` | optional | Connection pool settings | -| **readReplicas** | `Record[]` | optional | Read-only replica configurations | -| **capabilities** | `Object` | optional | Capability overrides | -| **description** | `string` | optional | Internal description | -| **active** | `boolean` | optional | Is datasource enabled | - - ---- - -## DatasourceCapabilities - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **transactions** | `boolean` | optional | | -| **queryFilters** | `boolean` | optional | | -| **queryAggregations** | `boolean` | optional | | -| **querySorting** | `boolean` | optional | | -| **queryPagination** | `boolean` | optional | | -| **queryWindowFunctions** | `boolean` | optional | | -| **querySubqueries** | `boolean` | optional | | -| **joins** | `boolean` | optional | | -| **fullTextSearch** | `boolean` | optional | | -| **readOnly** | `boolean` | optional | | -| **dynamicSchema** | `boolean` | optional | | - - ---- - -## DriverDefinition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique driver identifier (e.g. "postgres") | -| **label** | `string` | ✅ | Display label (e.g. "PostgreSQL") | -| **description** | `string` | optional | | -| **icon** | `string` | optional | | -| **configSchema** | `Record` | ✅ | JSON Schema for connection configuration | -| **capabilities** | `Object` | optional | | - - ---- - -## DriverType - -Underlying driver identifier - - ---- - diff --git a/content/docs/references/data/document.mdx b/content/docs/references/data/document.mdx deleted file mode 100644 index efc87c6c3..000000000 --- a/content/docs/references/data/document.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Document -description: Document protocol schemas ---- - -Document Version Schema - -Represents a single version of a document in a version-controlled system. - -Each version is immutable and maintains its own metadata and download URL. - -@example - -```json - -{ - -"versionNumber": 2, - -"createdAt": 1704067200000, - -"createdBy": "user_123", - -"size": 2048576, - -"checksum": "a1b2c3d4e5f6", - -"downloadUrl": "https://storage.example.com/docs/v2/file.pdf", - -"isLatest": true - -} - -``` - - -**Source:** `packages/spec/src/data/document.zod.ts` - - -## TypeScript Usage - -```typescript -import { Document, DocumentTemplate, DocumentVersion, ESignatureConfig } from '@objectstack/spec/data'; -import type { Document, DocumentTemplate, DocumentVersion, ESignatureConfig } from '@objectstack/spec/data'; - -// Validate data -const result = Document.parse(data); -``` - ---- - -## Document - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Document ID | -| **name** | `string` | ✅ | Document name | -| **description** | `string` | optional | Document description | -| **fileType** | `string` | ✅ | File MIME type | -| **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 | -| **metadata** | `Record` | optional | Custom metadata | - - ---- - -## DocumentTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Template ID | -| **name** | `string` | ✅ | Template name | -| **description** | `string` | optional | Template description | -| **fileUrl** | `string` | ✅ | Template file URL | -| **fileType** | `string` | ✅ | File MIME type | -| **placeholders** | `Object[]` | ✅ | Template placeholders | - - ---- - -## DocumentVersion - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **versionNumber** | `number` | ✅ | Version number | -| **createdAt** | `number` | ✅ | Creation timestamp | -| **createdBy** | `string` | ✅ | Creator user ID | -| **size** | `number` | ✅ | File size in bytes | -| **checksum** | `string` | ✅ | File checksum | -| **downloadUrl** | `string` | ✅ | Download URL | -| **isLatest** | `boolean` | optional | Is latest version | - - ---- - -## ESignatureConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'docusign' \| 'adobe-sign' \| 'hellosign' \| 'custom'>` | ✅ | E-signature provider | -| **enabled** | `boolean` | optional | E-signature enabled | -| **signers** | `Object[]` | ✅ | Document signers | -| **expirationDays** | `number` | optional | Expiration days | -| **reminderDays** | `number` | optional | Reminder interval days | - - ---- - diff --git a/content/docs/references/data/driver-nosql.mdx b/content/docs/references/data/driver-nosql.mdx deleted file mode 100644 index be227bb59..000000000 --- a/content/docs/references/data/driver-nosql.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Driver Nosql -description: Driver Nosql protocol schemas ---- - -NoSQL Database Type Enumeration - -Supported NoSQL database types - - -**Source:** `packages/spec/src/data/driver-nosql.zod.ts` - - -## TypeScript Usage - -```typescript -import { AggregationPipeline, AggregationStage, ConsistencyLevel, DocumentValidationSchema, NoSQLDataTypeMapping, NoSQLDatabaseType, NoSQLDriverConfig, NoSQLIndex, NoSQLIndexType, NoSQLOperationType, NoSQLQueryOptions, NoSQLTransactionOptions, ReplicationConfig, ShardingConfig } from '@objectstack/spec/data'; -import type { AggregationPipeline, AggregationStage, ConsistencyLevel, DocumentValidation, NoSQLDataTypeMapping, NoSQLDatabaseType, NoSQLDriverConfig, NoSQLIndex, NoSQLIndexType, NoSQLOperationType, NoSQLQueryOptions, NoSQLTransactionOptions, ReplicationConfig, ShardingConfig } from '@objectstack/spec/data'; - -// Validate data -const result = AggregationPipeline.parse(data); -``` - ---- - -## AggregationPipeline - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **collection** | `string` | ✅ | Collection/table name | -| **stages** | `Object[]` | ✅ | Aggregation pipeline stages | -| **options** | `Object` | optional | Query options | - - ---- - -## AggregationStage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operator** | `string` | ✅ | Aggregation operator (e.g., $match, $group, $sort) | -| **options** | `Record` | ✅ | Stage-specific options | - - ---- - -## ConsistencyLevel - -### Allowed Values - -* `all` -* `quorum` -* `one` -* `local_quorum` -* `each_quorum` -* `eventual` - - ---- - -## DocumentValidationSchema - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable schema validation | -| **validationLevel** | `Enum<'strict' \| 'moderate' \| 'off'>` | optional | Validation strictness | -| **validationAction** | `Enum<'error' \| 'warn'>` | optional | Action on validation failure | -| **jsonSchema** | `Record` | optional | JSON Schema for validation | - - ---- - -## NoSQLDataTypeMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **text** | `string` | ✅ | NoSQL type for text fields | -| **number** | `string` | ✅ | NoSQL type for number fields | -| **boolean** | `string` | ✅ | NoSQL type for boolean fields | -| **date** | `string` | ✅ | NoSQL type for date fields | -| **datetime** | `string` | ✅ | NoSQL type for datetime fields | -| **json** | `string` | optional | NoSQL type for JSON/object fields | -| **uuid** | `string` | optional | NoSQL type for UUID fields | -| **binary** | `string` | optional | NoSQL type for binary fields | -| **array** | `string` | optional | NoSQL type for array fields | -| **objectId** | `string` | optional | NoSQL type for ObjectID fields (MongoDB) | -| **geopoint** | `string` | optional | NoSQL type for geospatial point fields | - - ---- - -## NoSQLDatabaseType - -### Allowed Values - -* `mongodb` -* `couchdb` -* `dynamodb` -* `cassandra` -* `redis` -* `elasticsearch` -* `neo4j` -* `orientdb` - - ---- - -## NoSQLDriverConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Driver instance name | -| **type** | `string` | ✅ | Driver type must be "nosql" | -| **capabilities** | `Object` | ✅ | Driver capability flags | -| **connectionString** | `string` | optional | Database connection string (driver-specific format) | -| **poolConfig** | `Object` | 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 | -| **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 | -| **region** | `string` | optional | AWS region (for managed NoSQL services) | -| **accessKeyId** | `string` | optional | AWS access key ID | -| **secretAccessKey** | `string` | optional | AWS secret access key | -| **ttlField** | `string` | optional | Field name for TTL (auto-deletion) | -| **maxDocumentSize** | `integer` | optional | Maximum document size in bytes | -| **collectionPrefix** | `string` | optional | Prefix for collection/table names | - - ---- - -## NoSQLIndex - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Index name | -| **type** | `Enum<'single' \| 'compound' \| 'unique' \| 'text' \| 'geospatial' \| 'hashed' \| 'ttl' \| 'sparse'>` | ✅ | Index type | -| **fields** | `Object[]` | ✅ | Fields to index | -| **unique** | `boolean` | optional | Enforce uniqueness | -| **sparse** | `boolean` | optional | Sparse index | -| **expireAfterSeconds** | `integer` | optional | TTL in seconds | -| **partialFilterExpression** | `Record` | optional | Partial index filter | -| **background** | `boolean` | optional | Create index in background | - - ---- - -## NoSQLIndexType - -### Allowed Values - -* `single` -* `compound` -* `unique` -* `text` -* `geospatial` -* `hashed` -* `ttl` -* `sparse` - - ---- - -## NoSQLOperationType - -### Allowed Values - -* `find` -* `findOne` -* `insert` -* `update` -* `delete` -* `aggregate` -* `mapReduce` -* `count` -* `distinct` -* `createIndex` -* `dropIndex` - - ---- - -## NoSQLQueryOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | -| **timeout** | `integer` | optional | Query timeout (ms) | -| **useCursor** | `boolean` | optional | Use cursor instead of loading all results | -| **batchSize** | `integer` | optional | Cursor batch size | -| **profile** | `boolean` | optional | Enable query profiling | -| **hint** | `string` | optional | Index hint for query optimization | - - ---- - -## NoSQLTransactionOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **readConcern** | `Enum<'local' \| 'majority' \| 'linearizable' \| 'snapshot'>` | optional | Read concern level | -| **writeConcern** | `Enum<'majority' \| 'acknowledged' \| 'unacknowledged'>` | optional | Write concern level | -| **readPreference** | `Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>` | optional | Read preference | -| **maxCommitTimeMS** | `integer` | optional | Transaction commit timeout (ms) | - - ---- - -## ReplicationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable replication | -| **replicaSetName** | `string` | optional | Replica set name | -| **replicas** | `integer` | optional | Number of replicas | -| **readPreference** | `Enum<'primary' \| 'primaryPreferred' \| 'secondary' \| 'secondaryPreferred' \| 'nearest'>` | optional | Read preference for replica set | -| **writeConcern** | `Enum<'majority' \| 'acknowledged' \| 'unacknowledged'>` | optional | Write concern level | - - ---- - -## ShardingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable sharding | -| **shardKey** | `string` | optional | Field to use as shard key | -| **shardingStrategy** | `Enum<'hash' \| 'range' \| 'zone'>` | optional | Sharding strategy | -| **numShards** | `integer` | optional | Number of shards | - - ---- - diff --git a/content/docs/references/data/driver-sql.mdx b/content/docs/references/data/driver-sql.mdx deleted file mode 100644 index 391918b2a..000000000 --- a/content/docs/references/data/driver-sql.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Driver Sql -description: Driver Sql protocol schemas ---- - -SQL Dialect Enumeration - -Supported SQL database dialects - - -**Source:** `packages/spec/src/data/driver-sql.zod.ts` - - -## TypeScript Usage - -```typescript -import { DataTypeMapping, SQLDialect, SQLDriverConfig, SSLConfig } from '@objectstack/spec/data'; -import type { DataTypeMapping, SQLDialect, SQLDriverConfig, SSLConfig } from '@objectstack/spec/data'; - -// Validate data -const result = DataTypeMapping.parse(data); -``` - ---- - -## DataTypeMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **text** | `string` | ✅ | SQL type for text fields (e.g., VARCHAR, TEXT) | -| **number** | `string` | ✅ | SQL type for number fields (e.g., NUMERIC, DECIMAL, INT) | -| **boolean** | `string` | ✅ | SQL type for boolean fields (e.g., BOOLEAN, BIT) | -| **date** | `string` | ✅ | SQL type for date fields (e.g., DATE) | -| **datetime** | `string` | ✅ | SQL type for datetime fields (e.g., TIMESTAMP, DATETIME) | -| **json** | `string` | optional | SQL type for JSON fields (e.g., JSON, JSONB) | -| **uuid** | `string` | optional | SQL type for UUID fields (e.g., UUID, CHAR(36)) | -| **binary** | `string` | optional | SQL type for binary fields (e.g., BLOB, BYTEA) | - - ---- - -## SQLDialect - -### Allowed Values - -* `postgresql` -* `mysql` -* `sqlite` -* `mssql` -* `oracle` -* `mariadb` - - ---- - -## SQLDriverConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Driver instance name | -| **type** | `string` | ✅ | Driver type must be "sql" | -| **capabilities** | `Object` | ✅ | Driver capability flags | -| **connectionString** | `string` | optional | Database connection string (driver-specific format) | -| **poolConfig** | `Object` | optional | Connection pool configuration | -| **dialect** | `Enum<'postgresql' \| 'mysql' \| 'sqlite' \| 'mssql' \| 'oracle' \| 'mariadb'>` | ✅ | SQL database dialect | -| **dataTypeMapping** | `Object` | ✅ | SQL data type mapping configuration | -| **ssl** | `boolean` | optional | Enable SSL/TLS connection | -| **sslConfig** | `Object` | optional | SSL/TLS configuration (required when ssl is true) | - - ---- - -## SSLConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **rejectUnauthorized** | `boolean` | optional | Reject connections with invalid certificates | -| **ca** | `string` | optional | CA certificate file path or content | -| **cert** | `string` | optional | Client certificate file path or content | -| **key** | `string` | optional | Client private key file path or content | - - ---- - diff --git a/content/docs/references/data/driver.mdx b/content/docs/references/data/driver.mdx deleted file mode 100644 index 50bd96846..000000000 --- a/content/docs/references/data/driver.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Driver -description: Driver protocol schemas ---- - -Common Driver Options - -Passed to most driver methods to control behavior (transactions, timeouts, etc.) - - -**Source:** `packages/spec/src/data/driver.zod.ts` - - -## TypeScript Usage - -```typescript -import { DriverCapabilities, DriverConfig, DriverInterface, DriverOptions, PoolConfig } from '@objectstack/spec/data'; -import type { DriverCapabilities, DriverConfig, DriverInterface, DriverOptions, PoolConfig } from '@objectstack/spec/data'; - -// Validate data -const result = DriverCapabilities.parse(data); -``` - ---- - -## DriverCapabilities - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **create** | `boolean` | optional | Supports CREATE operations | -| **read** | `boolean` | optional | Supports READ operations | -| **update** | `boolean` | optional | Supports UPDATE operations | -| **delete** | `boolean` | optional | Supports DELETE operations | -| **bulkCreate** | `boolean` | optional | Supports bulk CREATE operations | -| **bulkUpdate** | `boolean` | optional | Supports bulk UPDATE operations | -| **bulkDelete** | `boolean` | optional | Supports bulk DELETE operations | -| **transactions** | `boolean` | optional | Supports ACID transactions | -| **savepoints** | `boolean` | optional | Supports transaction savepoints | -| **isolationLevels** | `Enum<'read-uncommitted' \| 'read-committed' \| 'repeatable-read' \| 'serializable'>[]` | optional | Supported transaction isolation levels | -| **queryFilters** | `boolean` | optional | Supports WHERE clause filtering | -| **queryAggregations** | `boolean` | optional | Supports GROUP BY and aggregation functions | -| **querySorting** | `boolean` | optional | Supports ORDER BY sorting | -| **queryPagination** | `boolean` | optional | Supports LIMIT/OFFSET pagination | -| **queryWindowFunctions** | `boolean` | optional | Supports window functions with OVER clause | -| **querySubqueries** | `boolean` | optional | Supports subqueries | -| **queryCTE** | `boolean` | optional | Supports Common Table Expressions (WITH clause) | -| **joins** | `boolean` | optional | Supports SQL joins | -| **fullTextSearch** | `boolean` | optional | Supports full-text search | -| **jsonQuery** | `boolean` | optional | Supports JSON field querying | -| **geospatialQuery** | `boolean` | optional | Supports geospatial queries | -| **streaming** | `boolean` | optional | Supports result streaming (cursors/iterators) | -| **jsonFields** | `boolean` | optional | Supports JSON field types | -| **arrayFields** | `boolean` | optional | Supports array field types | -| **vectorSearch** | `boolean` | optional | Supports vector embeddings and similarity search | -| **geoSpatial** | `boolean` | optional | Supports geospatial queries (deprecated: use geospatialQuery) | -| **schemaSync** | `boolean` | optional | Supports automatic schema synchronization | -| **migrations** | `boolean` | optional | Supports database migrations | -| **indexes** | `boolean` | optional | Supports index creation and management | -| **connectionPooling** | `boolean` | optional | Supports connection pooling | -| **preparedStatements** | `boolean` | optional | Supports prepared statements (SQL injection prevention) | -| **queryCache** | `boolean` | optional | Supports query result caching | - - ---- - -## DriverConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Driver instance name | -| **type** | `Enum<'sql' \| 'nosql' \| 'cache' \| 'search' \| 'graph' \| 'timeseries'>` | ✅ | Driver type category | -| **capabilities** | `Object` | ✅ | Driver capability flags | -| **connectionString** | `string` | optional | Database connection string (driver-specific format) | -| **poolConfig** | `Object` | optional | Connection pool configuration | - - ---- - -## DriverInterface - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Driver unique name | -| **version** | `string` | ✅ | Driver version | -| **supports** | `Object` | ✅ | | - - ---- - -## DriverOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **transaction** | `any` | optional | Transaction handle | -| **timeout** | `number` | optional | Timeout in ms | -| **skipCache** | `boolean` | optional | Bypass cache | -| **traceContext** | `Record` | optional | OpenTelemetry context or request ID | -| **tenantId** | `string` | optional | Tenant Isolation identifier | - - ---- - -## PoolConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **min** | `number` | optional | Minimum number of connections in pool | -| **max** | `number` | optional | Maximum number of connections in pool | -| **idleTimeoutMillis** | `number` | optional | Time in ms before idle connection is closed | -| **connectionTimeoutMillis** | `number` | optional | Time in ms to wait for available connection | - - ---- - diff --git a/content/docs/references/data/external-lookup.mdx b/content/docs/references/data/external-lookup.mdx deleted file mode 100644 index 4ca9a769b..000000000 --- a/content/docs/references/data/external-lookup.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: External Lookup -description: External Lookup protocol schemas ---- - -External Data Source Schema - -Configuration for connecting to external data systems. - -Similar to Salesforce External Objects for real-time data integration. - -@example - -```json - -{ - -"id": "salesforce-accounts", - -"name": "Salesforce Account Data", - -"type": "rest-api", - -"endpoint": "https://api.salesforce.com/services/data/v58.0", - -"authentication": { - -"type": "oauth2", - -"config": { - -"clientId": "...", - -"clientSecret": "...", - -"tokenUrl": "https://login.salesforce.com/services/oauth2/token" - -} - -} - -} - -``` - - -**Source:** `packages/spec/src/data/external-lookup.zod.ts` - - -## TypeScript Usage - -```typescript -import { ExternalDataSource, ExternalFieldMapping, ExternalLookup } from '@objectstack/spec/data'; -import type { ExternalDataSource, ExternalFieldMapping, ExternalLookup } from '@objectstack/spec/data'; - -// Validate data -const result = ExternalDataSource.parse(data); -``` - ---- - -## ExternalDataSource - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Data source ID | -| **name** | `string` | ✅ | Data source name | -| **type** | `Enum<'odata' \| 'rest-api' \| 'graphql' \| 'custom'>` | ✅ | Protocol type | -| **endpoint** | `string` | ✅ | API endpoint URL | -| **authentication** | `Object` | ✅ | Authentication | - - ---- - -## ExternalFieldMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Source field name | -| **target** | `string` | ✅ | Target field name | -| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | -| **defaultValue** | `any` | optional | Default if source is null/undefined | -| **type** | `string` | optional | Field type | -| **readonly** | `boolean` | optional | Read-only field | - - ---- - -## ExternalLookup - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fieldName** | `string` | ✅ | Field name | -| **dataSource** | `Object` | ✅ | External data source | -| **query** | `Object` | ✅ | Query configuration | -| **fieldMappings** | `Object[]` | ✅ | Field mappings | -| **caching** | `Object` | optional | Caching configuration | -| **fallback** | `Object` | optional | Fallback configuration | -| **rateLimit** | `Object` | optional | Rate limiting | - - ---- - diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx deleted file mode 100644 index d670e3727..000000000 --- a/content/docs/references/data/field.mdx +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: Field -description: Field protocol schemas ---- - -Field Type Enum - - -**Source:** `packages/spec/src/data/field.zod.ts` - - -## TypeScript Usage - -```typescript -import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; -import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; - -// Validate data -const result = Address.parse(data); -``` - ---- - -## Address - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **street** | `string` | optional | Street address | -| **city** | `string` | optional | City name | -| **state** | `string` | optional | State/Province | -| **postalCode** | `string` | optional | Postal/ZIP code | -| **country** | `string` | optional | Country name or code | -| **countryCode** | `string` | optional | ISO country code (e.g., US, GB) | -| **formatted** | `string` | optional | Formatted address string | - - ---- - -## ComputedFieldCache - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | Enable caching for computed field results | -| **ttl** | `number` | ✅ | Cache TTL in seconds (0 = no expiration) | -| **invalidateOn** | `string[]` | ✅ | Field paths that invalidate cache (e.g., ["inventory.quantity", "pricing.base_price"]) | - - ---- - -## CurrencyConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **precision** | `integer` | optional | Decimal precision (default: 2) | -| **currencyMode** | `Enum<'dynamic' \| 'fixed'>` | optional | Currency mode: dynamic (user selectable) or fixed (single currency) | -| **defaultCurrency** | `string` | optional | Default or fixed currency code (ISO 4217, e.g., USD, CNY, EUR) | - - ---- - -## CurrencyValue - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `number` | ✅ | Monetary amount | -| **currency** | `string` | ✅ | Currency code (ISO 4217) | - - ---- - -## DataQualityRules - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **uniqueness** | `boolean` | optional | Enforce unique values across all records | -| **completeness** | `number` | optional | Minimum ratio of non-null values (0-1, default: 0 = no requirement) | -| **accuracy** | `Object` | optional | Accuracy validation configuration | - - ---- - -## Field - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Machine name (snake_case) | -| **label** | `string` | optional | Human readable label | -| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | ✅ | Field Data Type | -| **description** | `string` | optional | Tooltip/Help text | -| **format** | `string` | optional | Format string (e.g. email, phone) | -| **required** | `boolean` | optional | Is required | -| **searchable** | `boolean` | optional | Is searchable | -| **multiple** | `boolean` | optional | Allow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image. | -| **unique** | `boolean` | optional | Is unique constraint | -| **defaultValue** | `any` | optional | Default value | -| **maxLength** | `number` | optional | Max character length | -| **minLength** | `number` | optional | Min character length | -| **precision** | `number` | optional | Total digits | -| **scale** | `number` | optional | Decimal places | -| **min** | `number` | optional | Minimum value | -| **max** | `number` | optional | Maximum value | -| **options** | `Object[]` | optional | Static options for select/multiselect | -| **reference** | `string` | optional | Target Object Name | -| **referenceFilters** | `string[]` | optional | Filters applied to lookup dialogs (e.g. "active = true") | -| **writeRequiresMasterRead** | `boolean` | optional | If true, user needs read access to master record to edit this field | -| **deleteBehavior** | `Enum<'set_null' \| 'cascade' \| 'restrict'>` | optional | What happens if referenced record is deleted | -| **expression** | `string` | optional | Formula expression | -| **formula** | `string` | optional | Deprecated: Use expression | -| **summaryOperations** | `Object` | optional | Roll-up summary definition | -| **language** | `string` | optional | Programming language for syntax highlighting (e.g., javascript, python, sql) | -| **theme** | `string` | optional | Code editor theme (e.g., dark, light, monokai) | -| **lineNumbers** | `boolean` | optional | Show line numbers in code editor | -| **maxRating** | `number` | optional | Maximum rating value (default: 5) | -| **allowHalf** | `boolean` | optional | Allow half-star ratings | -| **displayMap** | `boolean` | optional | Display map widget for location field | -| **allowGeocoding** | `boolean` | optional | Allow address-to-coordinate conversion | -| **addressFormat** | `Enum<'us' \| 'uk' \| 'international'>` | optional | Address format template | -| **colorFormat** | `Enum<'hex' \| 'rgb' \| 'rgba' \| 'hsl'>` | optional | Color value format | -| **allowAlpha** | `boolean` | optional | Allow transparency/alpha channel | -| **presetColors** | `string[]` | optional | Preset color options | -| **step** | `number` | optional | Step increment for slider (default: 1) | -| **showValue** | `boolean` | optional | Display current value on slider | -| **marks** | `Record` | optional | Custom marks/labels at specific values (e.g., `{0: "Low", 50: "Medium", 100: "High"}`) | -| **barcodeFormat** | `Enum<'qr' \| 'ean13' \| 'ean8' \| 'code128' \| 'code39' \| 'upca' \| 'upce'>` | optional | Barcode format type | -| **qrErrorCorrection** | `Enum<'L' \| 'M' \| 'Q' \| 'H'>` | optional | QR code error correction level (L=7%, M=15%, Q=25%, H=30%). Only applicable when barcodeFormat is "qr" | -| **displayValue** | `boolean` | optional | Display human-readable value below barcode/QR code | -| **allowScanning** | `boolean` | optional | Enable camera scanning for barcode/QR code input | -| **currencyConfig** | `Object` | optional | Configuration for currency field type | -| **vectorConfig** | `Object` | optional | Configuration for vector field type (AI/ML embeddings) | -| **fileAttachmentConfig** | `Object` | optional | Configuration for file and attachment field types | -| **encryptionConfig** | `Object` | optional | Field-level encryption configuration for sensitive data (GDPR/HIPAA/PCI-DSS) | -| **maskingRule** | `Object` | optional | Data masking rules for PII protection | -| **auditTrail** | `boolean` | optional | Enable detailed audit trail for this field (tracks all changes with user and timestamp) | -| **dependencies** | `string[]` | optional | Array of field names that this field depends on (for formulas, visibility rules, etc.) | -| **cached** | `Object` | optional | Caching configuration for computed/formula fields | -| **dataQuality** | `Object` | optional | Data quality validation and monitoring rules | -| **hidden** | `boolean` | optional | Hidden from default UI | -| **readonly** | `boolean` | optional | Read-only in UI | -| **encryption** | `boolean` | optional | Deprecated: Use encryptionConfig for enhanced encryption features. Simple flag for backward compatibility. | -| **index** | `boolean` | optional | Create standard database index | -| **externalId** | `boolean` | optional | Is external ID for upsert operations | - - ---- - -## FieldType - -### Allowed Values - -* `text` -* `textarea` -* `email` -* `url` -* `phone` -* `password` -* `markdown` -* `html` -* `richtext` -* `number` -* `currency` -* `percent` -* `date` -* `datetime` -* `time` -* `boolean` -* `toggle` -* `select` -* `multiselect` -* `radio` -* `checkboxes` -* `lookup` -* `master_detail` -* `tree` -* `image` -* `file` -* `avatar` -* `video` -* `audio` -* `formula` -* `summary` -* `autonumber` -* `location` -* `address` -* `code` -* `json` -* `color` -* `rating` -* `slider` -* `signature` -* `qrcode` -* `progress` -* `tags` -* `vector` - - ---- - -## FileAttachmentConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **minSize** | `number` | optional | Minimum file size in bytes | -| **maxSize** | `number` | optional | Maximum file size in bytes (e.g., 10485760 = 10MB) | -| **allowedTypes** | `string[]` | optional | Allowed file extensions (e.g., [".pdf", ".docx", ".jpg"]) | -| **blockedTypes** | `string[]` | optional | Blocked file extensions (e.g., [".exe", ".bat", ".sh"]) | -| **allowedMimeTypes** | `string[]` | optional | Allowed MIME types (e.g., ["image/jpeg", "application/pdf"]) | -| **blockedMimeTypes** | `string[]` | optional | Blocked MIME types | -| **virusScan** | `boolean` | optional | Enable virus scanning for uploaded files | -| **virusScanProvider** | `Enum<'clamav' \| 'virustotal' \| 'metadefender' \| 'custom'>` | optional | Virus scanning service provider | -| **virusScanOnUpload** | `boolean` | optional | Scan files immediately on upload | -| **quarantineOnThreat** | `boolean` | optional | Quarantine files if threat detected | -| **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 | -| **allowMultiple** | `boolean` | optional | Allow multiple file uploads (overrides field.multiple) | -| **allowReplace** | `boolean` | optional | Allow replacing existing files | -| **allowDelete** | `boolean` | optional | Allow deleting uploaded files | -| **requireUpload** | `boolean` | optional | Require at least one file when field is required | -| **extractMetadata** | `boolean` | optional | Extract file metadata (name, size, type, etc.) | -| **extractText** | `boolean` | optional | Extract text content from documents (OCR/parsing) | -| **versioningEnabled** | `boolean` | optional | Keep previous versions of replaced files | -| **maxVersions** | `number` | optional | Maximum number of versions to retain | -| **publicRead** | `boolean` | optional | Allow public read access to uploaded files | -| **presignedUrlExpiry** | `number` | optional | Presigned URL expiration in seconds (default: 1 hour) | - - ---- - -## LocationCoordinates - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **latitude** | `number` | ✅ | Latitude coordinate | -| **longitude** | `number` | ✅ | Longitude coordinate | -| **altitude** | `number` | optional | Altitude in meters | -| **accuracy** | `number` | optional | Accuracy in meters | - - ---- - -## SelectOption - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **label** | `string` | ✅ | Display label (human-readable, any case allowed) | -| **value** | `string` | ✅ | Stored value (lowercase machine identifier) | -| **color** | `string` | optional | Color code for badges/charts | -| **default** | `boolean` | optional | Is default option | - - ---- - -## VectorConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **dimensions** | `integer` | ✅ | Vector dimensionality (e.g., 1536 for OpenAI embeddings) | -| **distanceMetric** | `Enum<'cosine' \| 'euclidean' \| 'dotProduct' \| 'manhattan'>` | optional | Distance/similarity metric for vector search | -| **normalized** | `boolean` | optional | Whether vectors are normalized (unit length) | -| **indexed** | `boolean` | optional | Whether to create a vector index for fast similarity search | -| **indexType** | `Enum<'hnsw' \| 'ivfflat' \| 'flat'>` | optional | Vector index algorithm (HNSW for high accuracy, IVFFlat for large datasets) | - - ---- - diff --git a/content/docs/references/data/filter.mdx b/content/docs/references/data/filter.mdx deleted file mode 100644 index 1f8ab7273..000000000 --- a/content/docs/references/data/filter.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Filter -description: Filter protocol schemas ---- - -Unified Query DSL Specification - -Based on industry best practices from: - -- Prisma ORM - -- Strapi CMS - -- TypeORM - -- LoopBack Framework - -Version: 1.0.0 - -Status: Draft - -Objective: Define a JSON-based, database-agnostic query syntax standard - -for data filtering interactions between frontend and backend APIs. - -Design Principles: - -1. Declarative: Frontend describes "what data to get", not "how to query" - -2. Database Agnostic: Syntax contains no database-specific directives - -3. Type Safe: Structure can be statically inferred by TypeScript - -4. Convention over Configuration: Implicit syntax for common queries - - -**Source:** `packages/spec/src/data/filter.zod.ts` - - -## TypeScript Usage - -```typescript -import { ComparisonOperator, EqualityOperator, FieldOperators, FieldReference, FilterCondition, NormalizedFilter, QueryFilter, RangeOperator, SetOperator, SpecialOperator, StringOperator } from '@objectstack/spec/data'; -import type { ComparisonOperator, EqualityOperator, FieldOperators, FieldReference, FilterCondition, NormalizedFilter, QueryFilter, RangeOperator, SetOperator, SpecialOperator, StringOperator } from '@objectstack/spec/data'; - -// Validate data -const result = ComparisonOperator.parse(data); -``` - ---- - -## ComparisonOperator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$gt** | `number \| string \| Object` | optional | | -| **$gte** | `number \| string \| Object` | optional | | -| **$lt** | `number \| string \| Object` | optional | | -| **$lte** | `number \| string \| Object` | optional | | - - ---- - -## EqualityOperator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$eq** | `any` | optional | | -| **$ne** | `any` | optional | | - - ---- - -## FieldOperators - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$eq** | `any` | optional | | -| **$ne** | `any` | optional | | -| **$gt** | `number \| string \| Object` | optional | | -| **$gte** | `number \| string \| Object` | optional | | -| **$lt** | `number \| string \| Object` | optional | | -| **$lte** | `number \| string \| Object` | optional | | -| **$in** | `any[]` | optional | | -| **$nin** | `any[]` | optional | | -| **$between** | `any[]` | optional | | -| **$contains** | `string` | optional | | -| **$startsWith** | `string` | optional | | -| **$endsWith** | `string` | optional | | -| **$null** | `boolean` | optional | | -| **$exist** | `boolean` | optional | | - - ---- - -## FieldReference - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$field** | `string` | ✅ | Field Reference/Column Name | - - ---- - -## FilterCondition - - ---- - -## NormalizedFilter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$and** | `Record \| any[]` | optional | | -| **$or** | `Record \| any[]` | optional | | -| **$not** | `Record \| any` | optional | | - - ---- - -## QueryFilter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **where** | `any` | optional | | - - ---- - -## RangeOperator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$between** | `any[]` | optional | | - - ---- - -## SetOperator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$in** | `any[]` | optional | | -| **$nin** | `any[]` | optional | | - - ---- - -## SpecialOperator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$null** | `boolean` | optional | | -| **$exist** | `boolean` | optional | | - - ---- - -## StringOperator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **$contains** | `string` | optional | | -| **$startsWith** | `string` | optional | | -| **$endsWith** | `string` | optional | | - - ---- - diff --git a/content/docs/references/data/hook.mdx b/content/docs/references/data/hook.mdx deleted file mode 100644 index dca260d28..000000000 --- a/content/docs/references/data/hook.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Hook -description: Hook protocol schemas ---- - -Hook Lifecycle Events - -Defines the interception points in the ObjectQL execution pipeline. - - -**Source:** `packages/spec/src/data/hook.zod.ts` - - -## TypeScript Usage - -```typescript -import { Hook, HookContext, HookEvent } from '@objectstack/spec/data'; -import type { Hook, HookContext, HookEvent } from '@objectstack/spec/data'; - -// Validate data -const result = Hook.parse(data); -``` - ---- - -## Hook - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Hook unique name (snake_case) | -| **label** | `string` | optional | Description of what this hook does | -| **object** | `string \| string[]` | ✅ | Target object(s) | -| **events** | `Enum<'beforeFind' \| 'afterFind' \| 'beforeFindOne' \| 'afterFindOne' \| 'beforeCount' \| 'afterCount' \| 'beforeAggregate' \| 'afterAggregate' \| 'beforeInsert' \| 'afterInsert' \| 'beforeUpdate' \| 'afterUpdate' \| 'beforeDelete' \| 'afterDelete' \| 'beforeUpdateMany' \| 'afterUpdateMany' \| 'beforeDeleteMany' \| 'afterDeleteMany'>[]` | ✅ | Lifecycle events | -| **handler** | `string \| any` | optional | Function handler name or direct function | -| **priority** | `number` | optional | Execution priority | -| **async** | `boolean` | optional | Run specifically as fire-and-forget | -| **onError** | `Enum<'abort' \| 'log'>` | optional | Error handling strategy | - - ---- - -## HookContext - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique execution ID for tracing | -| **object** | `string` | ✅ | | -| **event** | `Enum<'beforeFind' \| 'afterFind' \| 'beforeFindOne' \| 'afterFindOne' \| 'beforeCount' \| 'afterCount' \| 'beforeAggregate' \| 'afterAggregate' \| 'beforeInsert' \| 'afterInsert' \| 'beforeUpdate' \| 'afterUpdate' \| 'beforeDelete' \| 'afterDelete' \| 'beforeUpdateMany' \| 'afterUpdateMany' \| 'beforeDeleteMany' \| 'afterDeleteMany'>` | ✅ | | -| **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 | -| **transaction** | `any` | optional | Database transaction handle | -| **ql** | `any` | optional | ObjectQL Engine Reference | - - ---- - -## HookEvent - -### Allowed Values - -* `beforeFind` -* `afterFind` -* `beforeFindOne` -* `afterFindOne` -* `beforeCount` -* `afterCount` -* `beforeAggregate` -* `afterAggregate` -* `beforeInsert` -* `afterInsert` -* `beforeUpdate` -* `afterUpdate` -* `beforeDelete` -* `afterDelete` -* `beforeUpdateMany` -* `afterUpdateMany` -* `beforeDeleteMany` -* `afterDeleteMany` - - ---- - diff --git a/content/docs/references/data/mapping.mdx b/content/docs/references/data/mapping.mdx deleted file mode 100644 index a63ab9ef4..000000000 --- a/content/docs/references/data/mapping.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Mapping -description: Mapping protocol schemas ---- - -Transformation Logic - -Built-in helpers for converting data during import. - - -**Source:** `packages/spec/src/data/mapping.zod.ts` - - -## TypeScript Usage - -```typescript -import { FieldMapping, Mapping, TransformType } from '@objectstack/spec/data'; -import type { FieldMapping, Mapping, TransformType } from '@objectstack/spec/data'; - -// Validate data -const result = FieldMapping.parse(data); -``` - ---- - -## FieldMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string \| string[]` | ✅ | Source column header(s) | -| **target** | `string \| string[]` | ✅ | Target object field(s) | -| **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | optional | | -| **params** | `Object` | optional | | - - ---- - -## Mapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Mapping unique name (lowercase snake_case) | -| **label** | `string` | optional | | -| **sourceFormat** | `Enum<'csv' \| 'json' \| 'xml' \| 'sql'>` | optional | | -| **targetObject** | `string` | ✅ | Target Object Name | -| **fieldMapping** | `Object[]` | ✅ | | -| **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | optional | | -| **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) | -| **extractQuery** | `Object` | optional | Query to run for export only | -| **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | optional | | -| **batchSize** | `number` | optional | | - - ---- - -## TransformType - -### Allowed Values - -* `none` -* `constant` -* `lookup` -* `split` -* `join` -* `javascript` -* `map` - - ---- - diff --git a/content/docs/references/data/meta.json b/content/docs/references/data/meta.json deleted file mode 100644 index 47ac2f378..000000000 --- a/content/docs/references/data/meta.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "title": "Data Protocol", - "pages": [ - "analytics", - "data-engine", - "dataset", - "datasource", - "document", - "driver", - "driver-nosql", - "driver-sql", - "external-lookup", - "field", - "filter", - "hook", - "mapping", - "metrics", - "object", - "query", - "search-engine", - "validation" - ] -} \ No newline at end of file diff --git a/content/docs/references/data/metrics.mdx b/content/docs/references/data/metrics.mdx deleted file mode 100644 index 5bfeb736f..000000000 --- a/content/docs/references/data/metrics.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Metrics -description: Metrics protocol schemas ---- - - -**Source:** `packages/spec/src/data/metrics.zod.ts` - - -## TypeScript Usage - -```typescript -import { MetricType } from '@objectstack/spec/data'; -import type { MetricType } from '@objectstack/spec/data'; - -// Validate data -const result = MetricType.parse(data); -``` - ---- - -## MetricType - -### Allowed Values - -* `count` -* `sum` -* `avg` -* `min` -* `max` -* `count_distinct` -* `number` -* `string` -* `boolean` - - ---- - diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx deleted file mode 100644 index 38d139e35..000000000 --- a/content/docs/references/data/object.mdx +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Object -description: Object protocol schemas ---- - -API Operations Enum - - -**Source:** `packages/spec/src/data/object.zod.ts` - - -## TypeScript Usage - -```typescript -import { ApiMethod, CDCConfig, Index, Object, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; -import type { ApiMethod, CDCConfig, Index, Object, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; - -// Validate data -const result = ApiMethod.parse(data); -``` - ---- - -## ApiMethod - -### Allowed Values - -* `get` -* `list` -* `create` -* `update` -* `delete` -* `upsert` -* `bulk` -* `aggregate` -* `history` -* `search` -* `restore` -* `purge` -* `import` -* `export` - - ---- - -## CDCConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | Enable Change Data Capture | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | ✅ | Event types to capture | -| **destination** | `string` | ✅ | Destination endpoint (e.g., "kafka://topic", "webhook://url") | - - ---- - -## Index - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Index name (auto-generated if not provided) | -| **fields** | `string[]` | ✅ | Fields included in the index | -| **type** | `Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>` | optional | Index algorithm type | -| **unique** | `boolean` | optional | Whether the index enforces uniqueness | -| **partial** | `string` | optional | Partial index condition (SQL WHERE clause for conditional indexes) | - - ---- - -## Object - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Machine unique key (snake_case). Immutable. | -| **label** | `string` | optional | Human readable singular label (e.g. "Account") | -| **pluralLabel** | `string` | optional | Human readable plural label (e.g. "Accounts") | -| **description** | `string` | optional | Developer documentation / description | -| **icon** | `string` | optional | Icon name (Lucide/Material) for UI representation | -| **tags** | `string[]` | optional | Categorization tags (e.g. "sales", "system", "reference") | -| **active** | `boolean` | optional | Is the object active and usable | -| **isSystem** | `boolean` | optional | Is system object (protected from deletion) | -| **abstract** | `boolean` | optional | Is abstract base object (cannot be instantiated) | -| **datasource** | `string` | optional | Target Datasource ID. "default" is the primary DB. | -| **tableName** | `string` | optional | Physical table/collection name in the target datasource | -| **fields** | `Record` | ✅ | Field definitions map. Keys must be snake_case identifiers. | -| **indexes** | `Object[]` | optional | Database performance indexes | -| **tenancy** | `Object` | optional | Multi-tenancy configuration for SaaS applications | -| **softDelete** | `Object` | optional | Soft delete (trash/recycle bin) configuration | -| **versioning** | `Object` | optional | Record versioning and history tracking configuration | -| **partitioning** | `Object` | optional | Table partitioning configuration for performance | -| **cdc** | `Object` | optional | Change Data Capture (CDC) configuration for real-time data streaming | -| **validations** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | optional | Object-level validation rules | -| **stateMachine** | `Object` | optional | Single state machine for record lifecycle (shorthand) | -| **stateMachines** | `Record` | optional | Named state machines for parallel lifecycles (e.g., status, payment, approval) | -| **titleFormat** | `string` | optional | Title expression (e.g. "`{name}` - `{code}`"). Overrides nameField. | -| **compactLayout** | `string[]` | optional | Primary fields for hover/cards/lookups | -| **search** | `Object` | optional | Search engine configuration | -| **enable** | `Object` | optional | Enabled system features modules | - - ---- - -## ObjectCapabilities - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trackHistory** | `boolean` | optional | Enable field history tracking for audit compliance | -| **searchable** | `boolean` | optional | Index records for global search | -| **apiEnabled** | `boolean` | optional | Expose object via automatic APIs | -| **apiMethods** | `Enum<'get' \| 'list' \| 'create' \| 'update' \| 'delete' \| 'upsert' \| 'bulk' \| 'aggregate' \| 'history' \| 'search' \| 'restore' \| 'purge' \| 'import' \| 'export'>[]` | optional | Whitelist of allowed API operations | -| **files** | `boolean` | optional | Enable file attachments and document management | -| **feeds** | `boolean` | optional | Enable social feed, comments, and mentions (Chatter-like) | -| **activities** | `boolean` | optional | Enable standard tasks and events tracking | -| **trash** | `boolean` | optional | Enable soft-delete with restore capability | -| **mru** | `boolean` | optional | Track Most Recently Used (MRU) list for users | -| **clone** | `boolean` | optional | Allow record deep cloning | - - ---- - -## ObjectExtension - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **extend** | `string` | ✅ | Target object name (FQN) to extend | -| **fields** | `Record` | optional | Fields to add/override | -| **label** | `string` | optional | | -| **pluralLabel** | `string` | optional | | -| **description** | `string` | optional | | -| **validations** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | optional | | -| **indexes** | `Object[]` | optional | | -| **priority** | `integer` | optional | Merge priority (higher = applied later) | - - ---- - -## ObjectOwnershipEnum - -### Allowed Values - -* `own` -* `extend` - - ---- - -## PartitioningConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | Enable table partitioning | -| **strategy** | `Enum<'range' \| 'hash' \| 'list'>` | ✅ | Partitioning strategy: range (date ranges), hash (consistent hashing), list (predefined values) | -| **key** | `string` | ✅ | Field name to partition by | -| **interval** | `string` | optional | Partition interval for range strategy (e.g., "1 month", "1 year") | - - ---- - -## SoftDeleteConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | Enable soft delete (trash/recycle bin) | -| **field** | `string` | optional | Field name for soft delete timestamp | -| **cascadeDelete** | `boolean` | optional | Cascade soft delete to related records | - - ---- - -## TenancyConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | Enable multi-tenancy for this object | -| **strategy** | `Enum<'shared' \| 'isolated' \| 'hybrid'>` | ✅ | Tenant isolation strategy: shared (single DB, row-level), isolated (separate DB per tenant), hybrid (mix) | -| **tenantField** | `string` | optional | Field name for tenant identifier | -| **crossTenantAccess** | `boolean` | optional | Allow cross-tenant data access (with explicit permission) | - - ---- - -## VersioningConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | Enable record versioning | -| **strategy** | `Enum<'snapshot' \| 'delta' \| 'event-sourcing'>` | ✅ | Versioning strategy: snapshot (full copy), delta (changes only), event-sourcing (event log) | -| **retentionDays** | `number` | optional | Number of days to retain old versions (undefined = infinite) | -| **versionField** | `string` | optional | Field name for version number/timestamp | - - ---- - diff --git a/content/docs/references/data/query.mdx b/content/docs/references/data/query.mdx deleted file mode 100644 index 8cc0e2927..000000000 --- a/content/docs/references/data/query.mdx +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Query -description: Query protocol schemas ---- - -Sort Node - -Represents "Order By". - - -**Source:** `packages/spec/src/data/query.zod.ts` - - -## TypeScript Usage - -```typescript -import { AggregationFunction, AggregationNode, FieldNode, FullTextSearch, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data'; -import type { AggregationFunction, AggregationNode, FieldNode, FullTextSearch, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data'; - -// Validate data -const result = AggregationFunction.parse(data); -``` - ---- - -## AggregationFunction - -### Allowed Values - -* `count` -* `sum` -* `avg` -* `min` -* `max` -* `count_distinct` -* `array_agg` -* `string_agg` - - ---- - -## AggregationNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **function** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>` | ✅ | Aggregation function | -| **field** | `string` | optional | Field to aggregate (optional for COUNT(*)) | -| **alias** | `string` | ✅ | Result column alias | -| **distinct** | `boolean` | optional | Apply DISTINCT before aggregation | -| **filter** | `any` | optional | Filter/Condition to apply to the aggregation (FILTER WHERE clause) | - - ---- - -## FieldNode - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Type: `string` - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | | -| **fields** | `any[]` | optional | | -| **alias** | `string` | optional | | - ---- - - ---- - -## FullTextSearch - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | ✅ | Search query text | -| **fields** | `string[]` | optional | Fields to search in (if not specified, searches all text fields) | -| **fuzzy** | `boolean` | optional | Enable fuzzy matching (tolerates typos) | -| **operator** | `Enum<'and' \| 'or'>` | optional | Logical operator between terms | -| **boost** | `Record` | optional | Field-specific relevance boosting (field name -> boost factor) | -| **minScore** | `number` | optional | Minimum relevance score threshold | -| **language** | `string` | optional | Language for text analysis (e.g., "en", "zh", "es") | -| **highlight** | `boolean` | optional | Enable search result highlighting | - - ---- - -## JoinNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'inner' \| 'left' \| 'right' \| 'full'>` | ✅ | Join type | -| **strategy** | `Enum<'auto' \| 'database' \| 'hash' \| 'loop'>` | optional | Execution strategy hint | -| **object** | `string` | ✅ | Object/table to join | -| **alias** | `string` | optional | Table alias | -| **on** | `any` | ✅ | Join condition | -| **subquery** | `Object` | optional | Subquery instead of object | - - ---- - -## JoinStrategy - -### Allowed Values - -* `auto` -* `database` -* `hash` -* `loop` - - ---- - -## JoinType - -### Allowed Values - -* `inner` -* `left` -* `right` -* `full` - - ---- - -## Query - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **object** | `string` | ✅ | Object name (e.g. account) | -| **fields** | `string \| Object[]` | optional | Fields to retrieve | -| **where** | `any` | optional | Filtering criteria (WHERE) | -| **search** | `Object` | optional | Full-text search configuration ($search parameter) | -| **orderBy** | `Object[]` | 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[]` | optional | GROUP BY fields | -| **having** | `any` | optional | HAVING clause for aggregation filtering | -| **windowFunctions** | `Object[]` | optional | Window functions with OVER clause | -| **distinct** | `boolean` | optional | SELECT DISTINCT flag | -| **expand** | `Record` | optional | Recursive relation loading (nested queries) | - - ---- - -## SortNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | | -| **order** | `Enum<'asc' \| 'desc'>` | optional | | - - ---- - -## WindowFunction - -### Allowed Values - -* `row_number` -* `rank` -* `dense_rank` -* `percent_rank` -* `lag` -* `lead` -* `first_value` -* `last_value` -* `sum` -* `avg` -* `count` -* `min` -* `max` - - ---- - -## WindowFunctionNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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) | - - ---- - -## WindowSpec - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **partitionBy** | `string[]` | optional | PARTITION BY fields | -| **orderBy** | `Object[]` | optional | ORDER BY specification | -| **frame** | `Object` | optional | Window frame specification | - - ---- - diff --git a/content/docs/references/data/search-engine.mdx b/content/docs/references/data/search-engine.mdx deleted file mode 100644 index 256c44ca9..000000000 --- a/content/docs/references/data/search-engine.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Search Engine -description: Search Engine protocol schemas ---- - - -**Source:** `packages/spec/src/data/search-engine.zod.ts` - - -## TypeScript Usage - -```typescript -import { SearchConfig } from '@objectstack/spec/data'; -import type { SearchConfig } from '@objectstack/spec/data'; - -// Validate data -const result = SearchConfig.parse(data); -``` - ---- - -## SearchConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fields** | `string[]` | ✅ | Fields to index for full-text search weighting | -| **displayFields** | `string[]` | optional | Fields to display in search result cards | -| **filters** | `string[]` | optional | Default filters for search results | - - ---- - diff --git a/content/docs/references/data/validation.mdx b/content/docs/references/data/validation.mdx deleted file mode 100644 index c6044d2d2..000000000 --- a/content/docs/references/data/validation.mdx +++ /dev/null @@ -1,501 +0,0 @@ ---- -title: Validation -description: Validation protocol schemas ---- - -# ObjectStack Validation Protocol - -This module defines the validation schema protocol for ObjectStack, providing a comprehensive - -type-safe validation system similar to Salesforce's validation rules but with enhanced capabilities. - -## Overview - -Validation rules are applied at the data layer to ensure data integrity and enforce business logic. - -The system supports multiple validation types: - -1. **Script Validation**: Formula-based validation using expressions - -2. **Uniqueness Validation**: Enforce unique constraints across fields - -3. **State Machine Validation**: Control allowed state transitions - -4. **Format Validation**: Validate field formats (email, URL, regex, etc.) - -5. **Cross-Field Validation**: Validate relationships between multiple fields - -6. **Async Validation**: Remote validation via API calls - -7. **Custom Validation**: User-defined validation functions - -8. **Conditional Validation**: Apply validations based on conditions - -## Salesforce Comparison - -ObjectStack validation rules are inspired by Salesforce validation rules but enhanced: - -- Salesforce: Formula-based validation with `Error Condition Formula` - -- ObjectStack: Multiple validation types with composable rules - -Example Salesforce validation rule: - -``` - -Rule Name: Discount_Cannot_Exceed_40_Percent - -Error Condition Formula: Discount_Percent__c > 0.40 - -Error Message: Discount cannot exceed 40%. - -``` - -Equivalent ObjectStack rule: - -```typescript - -{ - -type: 'script', - -name: 'discount_cannot_exceed_40_percent', - -condition: 'discount_percent > 0.40', - -message: 'Discount cannot exceed 40%', - -severity: 'error' - -} - -``` - - -**Source:** `packages/spec/src/data/validation.zod.ts` - - -## TypeScript Usage - -```typescript -import { AsyncValidation, ConditionalValidation, CrossFieldValidation, CustomValidator, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, UniquenessValidation, ValidationRule } from '@objectstack/spec/data'; -import type { AsyncValidation, ConditionalValidation, CrossFieldValidation, CustomValidator, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, UniquenessValidation, ValidationRule } from '@objectstack/spec/data'; - -// Validate data -const result = AsyncValidation.parse(data); -``` - ---- - -## AsyncValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | Field to validate | -| **validatorUrl** | `string` | optional | External API endpoint for validation | -| **method** | `Enum<'GET' \| 'POST'>` | optional | HTTP method for external call | -| **headers** | `Record` | optional | Custom headers for the request | -| **validatorFunction** | `string` | optional | Reference to custom validator function | -| **timeout** | `number` | optional | Timeout in milliseconds | -| **debounce** | `number` | optional | Debounce delay in milliseconds | -| **params** | `Record` | optional | Additional parameters to pass to validator | - - ---- - -## ConditionalValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | Condition formula (e.g. "type = 'enterprise'") | -| **then** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| any` | ✅ | Validation rule to apply when condition is true | -| **otherwise** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| any` | optional | Validation rule to apply when condition is false | - - ---- - -## CrossFieldValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | Formula expression comparing fields (e.g. "end_date > start_date") | -| **fields** | `string[]` | ✅ | Fields involved in the validation | - - ---- - -## CustomValidator - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | | -| **handler** | `string` | ✅ | Name of the custom validation function registered in the system | -| **params** | `Record` | optional | Parameters passed to the custom handler | - - ---- - -## FormatValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | | -| **regex** | `string` | optional | | -| **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | - - ---- - -## JSONValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | JSON field to validate | -| **schema** | `Record` | ✅ | JSON Schema object definition | - - ---- - -## ScriptValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | Formula expression. If TRUE, validation fails. (e.g. amount < 0) | - - ---- - -## StateMachineValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | State field (e.g. status) | -| **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | - - ---- - -## UniquenessValidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | | -| **fields** | `string[]` | ✅ | Fields that must be combined unique | -| **scope** | `string` | optional | Formula condition for scope (e.g. active = true) | -| **caseSensitive** | `boolean` | optional | | - - ---- - -## ValidationRule - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `script` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | Formula expression. If TRUE, validation fails. (e.g. amount < 0) | - ---- - -#### Option 2 - -**Type:** `unique` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | | -| **fields** | `string[]` | ✅ | Fields that must be combined unique | -| **scope** | `string` | optional | Formula condition for scope (e.g. active = true) | -| **caseSensitive** | `boolean` | optional | | - ---- - -#### Option 3 - -**Type:** `state_machine` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | State field (e.g. status) | -| **transitions** | `Record` | ✅ | Map of `{ OldState: [AllowedNewStates] }` | - ---- - -#### Option 4 - -**Type:** `format` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | | -| **regex** | `string` | optional | | -| **format** | `Enum<'email' \| 'url' \| 'phone' \| 'json'>` | optional | | - ---- - -#### Option 5 - -**Type:** `cross_field` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | Formula expression comparing fields (e.g. "end_date > start_date") | -| **fields** | `string[]` | ✅ | Fields involved in the validation | - ---- - -#### Option 6 - -**Type:** `json_schema` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | JSON field to validate | -| **schema** | `Record` | ✅ | JSON Schema object definition | - ---- - -#### Option 7 - -**Type:** `async` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **tags** | `string[]` | optional | Categorization tags (e.g., "compliance", "billing") | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | optional | | -| **message** | `string` | ✅ | Error message to display to the user | -| **type** | `string` | ✅ | | -| **field** | `string` | ✅ | Field to validate | -| **validatorUrl** | `string` | optional | External API endpoint for validation | -| **method** | `Enum<'GET' \| 'POST'>` | optional | HTTP method for external call | -| **headers** | `Record` | optional | Custom headers for the request | -| **validatorFunction** | `string` | optional | Reference to custom validator function | -| **timeout** | `number` | optional | Timeout in milliseconds | -| **debounce** | `number` | optional | Debounce delay in milliseconds | -| **params** | `Record` | optional | Additional parameters to pass to validator | - ---- - -#### Option 8 - -**Type:** `custom` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | | -| **handler** | `string` | ✅ | Name of the custom validation function registered in the system | -| **params** | `Record` | optional | Parameters passed to the custom handler | - ---- - -#### Option 9 - -**Type:** `conditional` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label for the rule listing | -| **description** | `string` | optional | Administrative notes explaining the business reason | -| **active** | `boolean` | optional | | -| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | optional | Validation contexts | -| **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` | ✅ | Condition formula (e.g. "type = 'enterprise'") | -| **then** | `Object \| Object \| Object \| Object \| Object \| Object \| Object \| Object \| any` | ✅ | Validation rule to apply when condition is true | -| **otherwise** | `any` | optional | Validation rule to apply when condition is false | - ---- - - ---- - diff --git a/content/docs/references/identity/identity.mdx b/content/docs/references/identity/identity.mdx deleted file mode 100644 index bfcb9183f..000000000 --- a/content/docs/references/identity/identity.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Identity -description: Identity protocol schemas ---- - -Identity & User Model Specification - -Defines the standard user, account, and session data models for ObjectStack. - -These schemas represent "who is logged in" and their associated data. - -This is separate from authentication configuration (auth.zod.ts) which - -defines "how to login". - - -**Source:** `packages/spec/src/identity/identity.zod.ts` - - -## TypeScript Usage - -```typescript -import { Account, Session, User, VerificationToken } from '@objectstack/spec/identity'; -import type { Account, Session, User, VerificationToken } from '@objectstack/spec/identity'; - -// Validate data -const result = Account.parse(data); -``` - ---- - -## Account - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique account identifier | -| **userId** | `string` | ✅ | Associated user ID | -| **type** | `Enum<'oauth' \| 'oidc' \| 'email' \| 'credentials' \| 'saml' \| 'ldap'>` | ✅ | Account type | -| **provider** | `string` | ✅ | Provider name | -| **providerAccountId** | `string` | ✅ | Provider account ID | -| **refreshToken** | `string` | optional | OAuth refresh token | -| **accessToken** | `string` | optional | OAuth access token | -| **expiresAt** | `number` | optional | Token expiry timestamp (Unix) | -| **tokenType** | `string` | optional | OAuth token type | -| **scope** | `string` | optional | OAuth scope | -| **idToken** | `string` | optional | OAuth ID token | -| **sessionState** | `string` | optional | Session state | -| **createdAt** | `string` | ✅ | Account creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | - - ---- - -## Session - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique session identifier | -| **sessionToken** | `string` | ✅ | Session token | -| **userId** | `string` | ✅ | Associated user ID | -| **activeOrganizationId** | `string` | optional | Active organization ID for context switching | -| **expires** | `string` | ✅ | Session expiry timestamp | -| **createdAt** | `string` | ✅ | Session creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | -| **ipAddress** | `string` | optional | IP address | -| **userAgent** | `string` | optional | User agent string | -| **fingerprint** | `string` | optional | Device fingerprint | - - ---- - -## User - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique user identifier | -| **email** | `string` | ✅ | User email address | -| **emailVerified** | `boolean` | optional | Whether email is verified | -| **name** | `string` | optional | User display name | -| **image** | `string` | optional | Profile image URL | -| **createdAt** | `string` | ✅ | Account creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | - - ---- - -## VerificationToken - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **identifier** | `string` | ✅ | Token identifier (email or phone) | -| **token** | `string` | ✅ | Verification token | -| **expires** | `string` | ✅ | Token expiry timestamp | -| **createdAt** | `string` | ✅ | Token creation timestamp | - - ---- - diff --git a/content/docs/references/identity/meta.json b/content/docs/references/identity/meta.json deleted file mode 100644 index 782d0bb30..000000000 --- a/content/docs/references/identity/meta.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "title": "Identity Protocol", - "pages": [ - "identity", - "organization", - "role", - "scim" - ] -} \ No newline at end of file diff --git a/content/docs/references/identity/organization.mdx b/content/docs/references/identity/organization.mdx deleted file mode 100644 index 1a4127986..000000000 --- a/content/docs/references/identity/organization.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Organization -description: Organization protocol schemas ---- - -Organization Schema (Multi-Tenant Architecture) - -Defines the standard organization/workspace model for ObjectStack. - -Supports B2B SaaS scenarios where users belong to multiple teams/workspaces. - -This aligns with better-auth's organization plugin capabilities. - - -**Source:** `packages/spec/src/identity/organization.zod.ts` - - -## TypeScript Usage - -```typescript -import { Invitation, InvitationStatus, Member, Organization } from '@objectstack/spec/identity'; -import type { Invitation, InvitationStatus, Member, Organization } from '@objectstack/spec/identity'; - -// Validate data -const result = Invitation.parse(data); -``` - ---- - -## Invitation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique invitation identifier | -| **organizationId** | `string` | ✅ | Organization ID | -| **email** | `string` | ✅ | Invitee email address | -| **role** | `string` | ✅ | Role to assign upon acceptance | -| **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'expired'>` | optional | Invitation status | -| **expiresAt** | `string` | ✅ | Invitation expiry timestamp | -| **inviterId** | `string` | ✅ | User ID of the inviter | -| **createdAt** | `string` | ✅ | Invitation creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | - - ---- - -## InvitationStatus - -### Allowed Values - -* `pending` -* `accepted` -* `rejected` -* `expired` - - ---- - -## Member - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique member identifier | -| **organizationId** | `string` | ✅ | Organization ID | -| **userId** | `string` | ✅ | User ID | -| **role** | `string` | ✅ | Member role (e.g., owner, admin, member, guest) | -| **createdAt** | `string` | ✅ | Member creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | - - ---- - -## Organization - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique organization identifier | -| **name** | `string` | ✅ | Organization display name | -| **slug** | `string` | ✅ | Unique URL-friendly slug (lowercase alphanumeric, hyphens, underscores) | -| **logo** | `string` | optional | Organization logo URL | -| **metadata** | `Record` | optional | Custom metadata | -| **createdAt** | `string` | ✅ | Organization creation timestamp | -| **updatedAt** | `string` | ✅ | Last update timestamp | - - ---- - diff --git a/content/docs/references/identity/role.mdx b/content/docs/references/identity/role.mdx deleted file mode 100644 index c756198a2..000000000 --- a/content/docs/references/identity/role.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Role -description: Role protocol schemas ---- - -Role Schema (aka Business Unit / Org Unit) - -Defines the organizational hierarchy (Reporting Structure). - -COMPARISON: - -- Salesforce: "Role" (Hierarchy for visibility rollup) - -- Microsoft: "Business Unit" (Structural container for data) - -- Kubernetes/AWS: "Role" usually refers to Permissions (we use PermissionSet for that) - -ROLES IN OBJECTSTACK: - -Used primarily for "Reporting Structure" - Managers see subordinates' data. - -**NAMING CONVENTION:** - -Role names MUST be lowercase snake_case to prevent security issues. - -@example Good role names - -- 'sales_manager' - -- 'ceo' - -- 'region_east_vp' - -- 'engineering_lead' - -@example Bad role names (will be rejected) - -- 'SalesManager' (camelCase) - -- 'CEO' (uppercase) - -- 'Region East VP' (spaces and uppercase) - - -**Source:** `packages/spec/src/identity/role.zod.ts` - - -## TypeScript Usage - -```typescript -import { Role } from '@objectstack/spec/identity'; -import type { Role } from '@objectstack/spec/identity'; - -// Validate data -const result = Role.parse(data); -``` - ---- - -## Role - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique role name (lowercase snake_case) | -| **label** | `string` | ✅ | Display label (e.g. VP of Sales) | -| **parent** | `string` | optional | Parent Role ID (Reports To) | -| **description** | `string` | optional | | - - ---- - diff --git a/content/docs/references/identity/scim.mdx b/content/docs/references/identity/scim.mdx deleted file mode 100644 index af9732fc2..000000000 --- a/content/docs/references/identity/scim.mdx +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: Scim -description: Scim protocol schemas ---- - -# SCIM 2.0 Protocol Implementation - -System for Cross-domain Identity Management (SCIM) 2.0 specification - -implementation for ObjectStack. - -## Overview - -SCIM 2.0 is an HTTP-based protocol for managing user and group identities - -across domains. It provides a standardized REST API for user provisioning, - -de-provisioning, and synchronization. - -## Use Cases - -1. **Enterprise SSO Integration** - -- Integrate with Okta, Azure AD, OneLogin - -- Automatic user provisioning from corporate directory - -- Just-in-Time (JIT) user creation on first login - -2. **User Lifecycle Management** - -- Automatically create users when they join organization - -- Update user attributes when they change roles - -- Deactivate users when they leave organization - -3. **Group/Department Synchronization** - -- Sync organizational structure from AD/LDAP - -- Maintain group memberships automatically - -- Map corporate roles to application permissions - -4. **Compliance & Audit** - -- Maintain accurate user directory - -- Track all identity changes - -- Meet SOX/HIPAA requirements for user management - -## Specification References - -- **RFC 7643**: SCIM Core Schema - -- **RFC 7644**: SCIM Protocol - -- **RFC 7642**: SCIM Requirements - -## Industry Implementations - -- **Okta**: Leading SCIM provider - -- **Azure AD**: Microsoft's identity platform - -- **OneLogin**: Enterprise SSO provider - -- **Google Workspace**: Google's identity management - -@see https://datatracker.ietf.org/doc/html/rfc7643 - -@see https://datatracker.ietf.org/doc/html/rfc7644 - - -**Source:** `packages/spec/src/identity/scim.zod.ts` - - -## TypeScript Usage - -```typescript -import { SCIMAddress, SCIMEmail, SCIMEnterpriseUser, SCIMError, SCIMGroup, SCIMGroupReference, SCIMListResponse, SCIMMemberReference, SCIMMeta, SCIMName, SCIMPatchOperation, SCIMPatchRequest, SCIMPhoneNumber, SCIMUser } from '@objectstack/spec/identity'; -import type { SCIMAddress, SCIMEmail, SCIMEnterpriseUser, SCIMError, SCIMGroup, SCIMGroupReference, SCIMListResponse, SCIMMemberReference, SCIMMeta, SCIMName, SCIMPatchOperation, SCIMPatchRequest, SCIMPhoneNumber, SCIMUser } from '@objectstack/spec/identity'; - -// Validate data -const result = SCIMAddress.parse(data); -``` - ---- - -## SCIMAddress - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **formatted** | `string` | optional | Formatted address | -| **streetAddress** | `string` | optional | Street address | -| **locality** | `string` | optional | City/Locality | -| **region** | `string` | optional | State/Region | -| **postalCode** | `string` | optional | Postal code | -| **country** | `string` | optional | Country | -| **type** | `Enum<'work' \| 'home' \| 'other'>` | optional | Address type | -| **primary** | `boolean` | optional | Primary address indicator | - - ---- - -## SCIMEmail - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Email address | -| **type** | `Enum<'work' \| 'home' \| 'other'>` | optional | Email type | -| **display** | `string` | optional | Display label | -| **primary** | `boolean` | optional | Primary email indicator | - - ---- - -## SCIMEnterpriseUser - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **employeeNumber** | `string` | optional | Employee number | -| **costCenter** | `string` | optional | Cost center | -| **organization** | `string` | optional | Organization | -| **division** | `string` | optional | Division | -| **department** | `string` | optional | Department | -| **manager** | `Object` | optional | Manager reference | - - ---- - -## SCIMError - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs | -| **status** | `integer` | ✅ | HTTP status code | -| **scimType** | `Enum<'invalidFilter' \| 'tooMany' \| 'uniqueness' \| 'mutability' \| 'invalidSyntax' \| 'invalidPath' \| 'noTarget' \| 'invalidValue' \| 'invalidVers' \| 'sensitive'>` | optional | SCIM error type | -| **detail** | `string` | optional | Error detail message | - - ---- - -## SCIMGroup - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs (must include Group schema) | -| **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 | - - ---- - -## SCIMGroupReference - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Group ID | -| **$ref** | `string` | optional | URI reference to the group | -| **display** | `string` | optional | Group display name | -| **type** | `Enum<'direct' \| 'indirect'>` | optional | Membership type | - - ---- - -## SCIMListResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs | -| **totalResults** | `integer` | ✅ | Total results count | -| **Resources** | `Object \| Object \| Record[]` | ✅ | Resources array (Users, Groups, or custom resources) | -| **startIndex** | `integer` | optional | Start index (1-based) | -| **itemsPerPage** | `integer` | optional | Items per page | - - ---- - -## SCIMMemberReference - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Member ID | -| **$ref** | `string` | optional | URI reference to the member | -| **type** | `Enum<'User' \| 'Group'>` | optional | Member type | -| **display** | `string` | optional | Member display name | - - ---- - -## SCIMMeta - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **resourceType** | `string` | optional | Resource type | -| **created** | `string` | optional | Creation timestamp | -| **lastModified** | `string` | optional | Last modification timestamp | -| **location** | `string` | optional | Resource location URI | -| **version** | `string` | optional | Entity tag (ETag) for concurrency control | - - ---- - -## SCIMName - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **formatted** | `string` | optional | Formatted full name | -| **familyName** | `string` | optional | Family name (last name) | -| **givenName** | `string` | optional | Given name (first name) | -| **middleName** | `string` | optional | Middle name | -| **honorificPrefix** | `string` | optional | Honorific prefix (Mr., Ms., Dr.) | -| **honorificSuffix** | `string` | optional | Honorific suffix (Jr., Sr.) | - - ---- - -## SCIMPatchOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **op** | `Enum<'add' \| 'remove' \| 'replace'>` | ✅ | Operation type | -| **path** | `string` | optional | Attribute path (optional for add) | -| **value** | `any` | optional | Value to set | - - ---- - -## SCIMPatchRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs | -| **Operations** | `Object[]` | ✅ | Patch operations | - - ---- - -## SCIMPhoneNumber - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `string` | ✅ | Phone number | -| **type** | `Enum<'work' \| 'home' \| 'mobile' \| 'fax' \| 'pager' \| 'other'>` | optional | Phone number type | -| **display** | `string` | optional | Display label | -| **primary** | `boolean` | optional | Primary phone indicator | - - ---- - -## SCIMUser - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **schemas** | `string[]` | optional | SCIM schema URIs (must include User schema) | -| **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 | -| **displayName** | `string` | optional | Display name for UI | -| **nickName** | `string` | optional | Nickname | -| **profileUrl** | `string` | optional | Profile page URL | -| **title** | `string` | optional | Job title | -| **userType** | `string` | optional | User type (employee, contractor) | -| **preferredLanguage** | `string` | optional | Preferred language (ISO 639-1) | -| **locale** | `string` | optional | Locale (e.g., en-US) | -| **timezone** | `string` | optional | Timezone | -| **active** | `boolean` | optional | 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 | - - ---- - diff --git a/content/docs/references/integration/connector.mdx b/content/docs/references/integration/connector.mdx deleted file mode 100644 index bf4522946..000000000 --- a/content/docs/references/integration/connector.mdx +++ /dev/null @@ -1,448 +0,0 @@ ---- -title: Connector -description: Connector protocol schemas ---- - -Connector Protocol - LEVEL 3: Enterprise Connector - -Defines the standard connector specification for external system integration. - -Connectors enable ObjectStack to sync data with SaaS apps, databases, file storage, - -and message queues through a unified protocol. - -**Positioning in 3-Layer Architecture:** - -- **L1: Simple Sync** (automation/sync.zod.ts) - Business users - Sync Salesforce to Sheets - -- **L2: ETL Pipeline** (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse - -- **L3: Enterprise Connector** (THIS FILE) - System integrators - Full SAP integration - -**SCOPE: Most comprehensive integration layer.** - -Includes authentication, webhooks, rate limiting, field mapping, bidirectional sync, - -retry policies, and complete lifecycle management. - -This protocol supports multiple authentication strategies, bidirectional sync, - -field mapping, webhooks, and comprehensive rate limiting. - -Authentication is now imported from the canonical auth/config.zod.ts. - -## When to Use This Layer - -**Use Enterprise Connector when:** - -- Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) - -- Complex OAuth2/SAML authentication required - -- Bidirectional sync with field mapping and transformations - -- Webhook management and rate limiting required - -- Full CRUD operations and data synchronization - -- Need comprehensive retry strategies and error handling - -**Examples:** - -- Full Salesforce integration with webhooks - -- SAP ERP connector with CDC (Change Data Capture) - -- Microsoft Dynamics 365 connector - -**When to downgrade:** - -- Simple field sync → Use [Simple Sync](../automation/sync.zod.ts) - -- Data transformation only → Use [ETL Pipeline](../automation/etl.zod.ts) - -@see [../automation/sync.zod.ts](../automation/sync.zod.ts) for Level 1 (simple sync) - -@see [../automation/etl.zod.ts](../automation/etl.zod.ts) for Level 2 (data engineering) - -## When to use Integration Connector vs. Trigger Registry? - -**Use `integration/connector.zod.ts` when:** - -- Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) - -- Complex OAuth2/SAML authentication required - -- Bidirectional sync with field mapping and transformations - -- Webhook management and rate limiting required - -- Full CRUD operations and data synchronization - -- Need comprehensive retry strategies and error handling - -**Use `automation/trigger-registry.zod.ts` when:** - -- Building simple automation triggers (e.g., "when Slack message received, create task") - -- No complex authentication needed (simple API keys, basic auth) - -- Lightweight, single-purpose integrations - -- Quick setup with minimal configuration - -@see ../../automation/trigger-registry.zod.ts for lightweight automation triggers - - -**Source:** `packages/spec/src/integration/connector.zod.ts` - - -## TypeScript Usage - -```typescript -import { Authentication, ConflictResolution, Connector, ConnectorAction, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, FieldTransform, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; -import type { Authentication, ConflictResolution, Connector, ConnectorAction, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, FieldTransform, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; - -// Validate data -const result = Authentication.parse(data); -``` - ---- - -## Authentication - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `oauth2` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **authorizationUrl** | `string` | ✅ | OAuth2 authorization endpoint | -| **tokenUrl** | `string` | ✅ | OAuth2 token endpoint | -| **clientId** | `string` | ✅ | OAuth2 client ID | -| **clientSecret** | `string` | ✅ | OAuth2 client secret (typically from ENV) | -| **scopes** | `string[]` | optional | Requested OAuth2 scopes | -| **redirectUri** | `string` | optional | OAuth2 redirect URI | -| **refreshToken** | `string` | optional | Refresh token for token renewal | -| **tokenExpiry** | `number` | optional | Token expiry timestamp | - ---- - -#### Option 2 - -**Type:** `api-key` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **key** | `string` | ✅ | API key value | -| **headerName** | `string` | optional | HTTP header name for API key | -| **paramName** | `string` | optional | Query parameter name (alternative to header) | - ---- - -#### Option 3 - -**Type:** `basic` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **username** | `string` | ✅ | Username | -| **password** | `string` | ✅ | Password | - ---- - -#### Option 4 - -**Type:** `bearer` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **token** | `string` | ✅ | Bearer token | - ---- - -#### Option 5 - -**Type:** `none` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | - ---- - - ---- - -## ConflictResolution - -Conflict resolution strategy - -### Allowed Values - -* `source_wins` -* `target_wins` -* `latest_wins` -* `manual` - - ---- - -## Connector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `Enum<'saas' \| 'database' \| 'file_storage' \| 'message_queue' \| 'api' \| 'custom'>` | ✅ | Connector type | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | - - ---- - -## ConnectorAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **key** | `string` | ✅ | Action key (machine name) | -| **label** | `string` | ✅ | Human readable label | -| **description** | `string` | optional | | -| **inputSchema** | `Record` | optional | Input parameters schema (JSON Schema) | -| **outputSchema** | `Record` | optional | Output schema (JSON Schema) | - - ---- - -## ConnectorStatus - -Connector status - -### Allowed Values - -* `active` -* `inactive` -* `error` -* `configuring` - - ---- - -## ConnectorTrigger - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **key** | `string` | ✅ | Trigger key | -| **label** | `string` | ✅ | Trigger label | -| **description** | `string` | optional | | -| **type** | `Enum<'polling' \| 'webhook'>` | ✅ | Trigger type | -| **interval** | `number` | optional | Polling interval in seconds | - - ---- - -## ConnectorType - -Connector type - -### Allowed Values - -* `saas` -* `database` -* `file_storage` -* `message_queue` -* `api` -* `custom` - - ---- - -## DataSyncConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>` | optional | Synchronization strategy | -| **direction** | `Enum<'import' \| 'export' \| 'bidirectional'>` | optional | Sync direction | -| **schedule** | `string` | optional | Cron expression for scheduled sync | -| **realtimeSync** | `boolean` | optional | Enable real-time sync | -| **timestampField** | `string` | optional | Field to track last modification time | -| **conflictResolution** | `Enum<'source_wins' \| 'target_wins' \| 'latest_wins' \| 'manual'>` | optional | Conflict resolution strategy | -| **batchSize** | `number` | optional | Records per batch | -| **deleteMode** | `Enum<'hard_delete' \| 'soft_delete' \| 'ignore'>` | optional | Delete handling mode | -| **filters** | `Record` | optional | Filter criteria for selective sync | - - ---- - -## FieldTransform - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'uppercase' \| 'lowercase' \| 'trim' \| 'date_format' \| 'number_format' \| 'custom'>` | ✅ | Transformation type | -| **params** | `Record` | optional | Transformation parameters | -| **function** | `string` | optional | Custom JavaScript function for transformation | - - ---- - -## RateLimitStrategy - -Rate limiting strategy - -### Allowed Values - -* `fixed_window` -* `sliding_window` -* `token_bucket` -* `leaky_bucket` - - ---- - -## RetryConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>` | optional | Retry strategy | -| **maxAttempts** | `number` | optional | Maximum retry attempts | -| **initialDelayMs** | `number` | optional | Initial retry delay in ms | -| **maxDelayMs** | `number` | optional | Maximum retry delay in ms | -| **backoffMultiplier** | `number` | optional | Exponential backoff multiplier | -| **retryableStatusCodes** | `number[]` | optional | HTTP status codes to retry | -| **retryOnNetworkError** | `boolean` | optional | Retry on network errors | -| **jitter** | `boolean` | optional | Add jitter to retry delays | - - ---- - -## RetryStrategy - -Retry strategy - -### Allowed Values - -* `exponential_backoff` -* `linear_backoff` -* `fixed_delay` -* `no_retry` - - ---- - -## SyncStrategy - -Synchronization strategy - -### Allowed Values - -* `full` -* `incremental` -* `upsert` -* `append_only` - - ---- - -## WebhookConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Webhook unique name (lowercase snake_case) | -| **label** | `string` | optional | Human-readable webhook label | -| **object** | `string` | optional | Object to listen to (optional for manual webhooks) | -| **triggers** | `Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]` | optional | Events that trigger execution | -| **url** | `string` | ✅ | External webhook endpoint URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | optional | HTTP method | -| **headers** | `Record` | optional | Custom HTTP headers | -| **body** | `any` | optional | Request body payload (if not using default record data) | -| **payloadFields** | `string[]` | optional | Fields to include. Empty = All | -| **includeSession** | `boolean` | optional | Include user session info | -| **authentication** | `Object` | optional | Authentication configuration | -| **retryPolicy** | `Object` | optional | Retry policy configuration | -| **timeoutMs** | `integer` | optional | Request timeout in milliseconds | -| **secret** | `string` | optional | Signing secret for HMAC signature verification | -| **isActive** | `boolean` | optional | Whether webhook is active | -| **description** | `string` | optional | Webhook description | -| **tags** | `string[]` | optional | Tags for organization | -| **events** | `Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'sync.started' \| 'sync.completed' \| 'sync.failed' \| 'auth.expired' \| 'rate_limit.exceeded'>[]` | optional | Connector events to subscribe to | -| **signatureAlgorithm** | `Enum<'hmac_sha256' \| 'hmac_sha512' \| 'none'>` | optional | Webhook signature algorithm | - - ---- - -## WebhookEvent - -Webhook event type - -### Allowed Values - -* `record.created` -* `record.updated` -* `record.deleted` -* `sync.started` -* `sync.completed` -* `sync.failed` -* `auth.expired` -* `rate_limit.exceeded` - - ---- - -## WebhookSignatureAlgorithm - -Webhook signature algorithm - -### Allowed Values - -* `hmac_sha256` -* `hmac_sha512` -* `none` - - ---- - diff --git a/content/docs/references/integration/http.mdx b/content/docs/references/integration/http.mdx deleted file mode 100644 index fbba3db77..000000000 --- a/content/docs/references/integration/http.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Http -description: Http protocol schemas ---- - - -**Source:** `packages/spec/src/integration/http.zod.ts` - - -## TypeScript Usage - -```typescript -import { RateLimitConfig } from '@objectstack/spec/integration'; -import type { RateLimitConfig } from '@objectstack/spec/integration'; - -// Validate data -const result = RateLimitConfig.parse(data); -``` - ---- - -## RateLimitConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>` | optional | Rate limiting strategy | -| **maxRequests** | `number` | ✅ | Maximum requests per window | -| **windowSeconds** | `number` | ✅ | Time window in seconds | -| **burstCapacity** | `number` | optional | Burst capacity | -| **respectUpstreamLimits** | `boolean` | optional | Respect external rate limit headers | -| **rateLimitHeaders** | `Object` | optional | Custom rate limit headers | - - ---- - diff --git a/content/docs/references/integration/mapping.mdx b/content/docs/references/integration/mapping.mdx deleted file mode 100644 index 10ed4d7dc..000000000 --- a/content/docs/references/integration/mapping.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Mapping -description: Mapping protocol schemas ---- - - -**Source:** `packages/spec/src/integration/mapping.zod.ts` - - -## TypeScript Usage - -```typescript -import { FieldMapping } from '@objectstack/spec/integration'; -import type { FieldMapping } from '@objectstack/spec/integration'; - -// Validate data -const result = FieldMapping.parse(data); -``` - ---- - -## FieldMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Source field name | -| **target** | `string` | ✅ | Target field name | -| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | -| **defaultValue** | `any` | optional | Default if source is null/undefined | -| **dataType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'json' \| 'array'>` | optional | Target data type | -| **required** | `boolean` | optional | Field is required | -| **syncMode** | `Enum<'read_only' \| 'write_only' \| 'bidirectional'>` | optional | Sync mode | - - ---- - diff --git a/content/docs/references/integration/message-queue.mdx b/content/docs/references/integration/message-queue.mdx deleted file mode 100644 index efcb4623d..000000000 --- a/content/docs/references/integration/message-queue.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Message Queue -description: Message Queue protocol schemas ---- - - -**Source:** `packages/spec/src/integration/message-queue.zod.ts` - - -## TypeScript Usage - -```typescript -import { ConsumerConfig, MessageQueueProvider } from '@objectstack/spec/integration'; -import type { ConsumerConfig, MessageQueueProvider } from '@objectstack/spec/integration'; - -// Validate data -const result = ConsumerConfig.parse(data); -``` - ---- - -## ConsumerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable consumer | -| **consumerGroup** | `string` | optional | Consumer group ID | -| **concurrency** | `number` | optional | Number of concurrent consumers | -| **prefetchCount** | `number` | optional | Prefetch count | -| **ackMode** | `Enum<'auto' \| 'manual' \| 'client'>` | optional | Message acknowledgment mode | -| **autoCommit** | `boolean` | optional | Auto-commit offsets | -| **autoCommitIntervalMs** | `number` | optional | Auto-commit interval in ms | -| **sessionTimeoutMs** | `number` | optional | Session timeout in ms | -| **rebalanceTimeoutMs** | `number` | optional | Rebalance timeout in ms | - - ---- - -## MessageQueueProvider - -Message queue provider type - -### Allowed Values - -* `rabbitmq` -* `kafka` -* `redis_pubsub` -* `redis_streams` -* `aws_sqs` -* `aws_sns` -* `google_pubsub` -* `azure_service_bus` -* `azure_event_hubs` -* `nats` -* `pulsar` -* `activemq` -* `custom` - - ---- - diff --git a/content/docs/references/integration/meta.json b/content/docs/references/integration/meta.json deleted file mode 100644 index 43bfa6991..000000000 --- a/content/docs/references/integration/meta.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "title": "Integration Protocol", - "pages": [ - "connector", - "http", - "mapping", - "message-queue", - "misc", - "object-storage" - ] -} \ No newline at end of file diff --git a/content/docs/references/integration/misc.mdx b/content/docs/references/integration/misc.mdx deleted file mode 100644 index 2e9507653..000000000 --- a/content/docs/references/integration/misc.mdx +++ /dev/null @@ -1,856 +0,0 @@ ---- -title: Misc -description: Misc protocol schemas ---- - - -**Source:** `packages/spec/src/integration/misc.zod.ts` - - -## TypeScript Usage - -```typescript -import { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseProvider, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageFormat, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; -import type { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseProvider, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageFormat, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; - -// Validate data -const result = AckMode.parse(data); -``` - ---- - -## AckMode - -Message acknowledgment mode - -### Allowed Values - -* `auto` -* `manual` -* `client` - - ---- - -## ApiVersionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **version** | `string` | ✅ | API version (e.g., "v2", "2023-10-01") | -| **isDefault** | `boolean` | optional | Is this the default version | -| **deprecationDate** | `string` | optional | API version deprecation date (ISO 8601) | -| **sunsetDate** | `string` | optional | API version sunset date (ISO 8601) | - - ---- - -## BuildConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **buildCommand** | `string` | optional | Build command (e.g., npm run build) | -| **outputDirectory** | `string` | optional | Output directory (e.g., .next, dist) | -| **installCommand** | `string` | optional | Install command (e.g., npm install, pnpm install) | -| **devCommand** | `string` | optional | Development command (e.g., npm run dev) | -| **nodeVersion** | `string` | optional | Node.js version (e.g., 18.x, 20.x) | -| **env** | `Record` | optional | Build environment variables | - - ---- - -## CdcConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable CDC | -| **method** | `Enum<'log_based' \| 'trigger_based' \| 'query_based' \| 'custom'>` | ✅ | CDC method | -| **slotName** | `string` | optional | Replication slot name (for log-based CDC) | -| **publicationName** | `string` | optional | Publication name (for PostgreSQL) | -| **startPosition** | `string` | optional | Starting position/LSN for CDC stream | -| **batchSize** | `number` | optional | CDC batch size | -| **pollIntervalMs** | `number` | optional | CDC polling interval in ms | - - ---- - -## DatabaseConnector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | -| **provider** | `Enum<'postgresql' \| 'mysql' \| 'mariadb' \| 'mssql' \| 'oracle' \| 'mongodb' \| 'redis' \| 'cassandra' \| 'snowflake' \| 'bigquery' \| 'redshift' \| 'custom'>` | ✅ | Database provider type | -| **connectionConfig** | `Object` | ✅ | Database connection configuration | -| **poolConfig** | `Object` | optional | Connection pool configuration | -| **sslConfig** | `Object` | optional | SSL/TLS configuration | -| **tables** | `Object[]` | ✅ | Tables to sync | -| **cdcConfig** | `Object` | optional | CDC configuration | -| **readReplicaConfig** | `Object` | optional | Read replica configuration | -| **queryTimeoutMs** | `number` | optional | Query timeout in ms | -| **enableQueryLogging** | `boolean` | optional | Enable SQL query logging | - - ---- - -## DatabasePoolConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **min** | `number` | optional | Minimum connections in pool | -| **max** | `number` | optional | Maximum connections in pool | -| **idleTimeoutMs** | `number` | optional | Idle connection timeout in ms | -| **connectionTimeoutMs** | `number` | optional | Connection establishment timeout in ms | -| **acquireTimeoutMs** | `number` | optional | Connection acquisition timeout in ms | -| **evictionRunIntervalMs** | `number` | optional | Connection eviction check interval in ms | -| **testOnBorrow** | `boolean` | optional | Test connection before use | - - ---- - -## DatabaseProvider - -Database provider type - -### Allowed Values - -* `postgresql` -* `mysql` -* `mariadb` -* `mssql` -* `oracle` -* `mongodb` -* `redis` -* `cassandra` -* `snowflake` -* `bigquery` -* `redshift` -* `custom` - - ---- - -## DatabaseTable - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Table name in ObjectStack (snake_case) | -| **label** | `string` | ✅ | Display label | -| **schema** | `string` | optional | Database schema name | -| **tableName** | `string` | ✅ | Actual table name in database | -| **primaryKey** | `string` | ✅ | Primary key column | -| **enabled** | `boolean` | optional | Enable sync for this table | -| **fieldMappings** | `Object[]` | optional | Table-specific field mappings | -| **whereClause** | `string` | optional | SQL WHERE clause for filtering | - - ---- - -## DeliveryGuarantee - -Message delivery guarantee - -### Allowed Values - -* `at_most_once` -* `at_least_once` -* `exactly_once` - - ---- - -## DeploymentConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **autoDeployment** | `boolean` | optional | Enable automatic deployments | -| **regions** | `Enum<'iad1' \| 'sfo1' \| 'gru1' \| 'lhr1' \| 'fra1' \| 'sin1' \| 'syd1' \| 'hnd1' \| 'icn1'>[]` | optional | Deployment regions | -| **enablePreview** | `boolean` | optional | Enable preview deployments | -| **previewComments** | `boolean` | optional | Post preview URLs in PR comments | -| **productionProtection** | `boolean` | optional | Require approval for production deployments | -| **deployHooks** | `Object[]` | optional | Deploy hooks | - - ---- - -## DlqConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable DLQ | -| **queueName** | `string` | ✅ | Dead letter queue/topic name | -| **maxRetries** | `number` | optional | Max retries before DLQ | -| **retryDelayMs** | `number` | optional | Retry delay in ms | - - ---- - -## DomainConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **domain** | `string` | ✅ | Domain name (e.g., app.example.com) | -| **httpsRedirect** | `boolean` | optional | Redirect HTTP to HTTPS | -| **customCertificate** | `Object` | optional | Custom SSL certificate | -| **gitBranch** | `string` | optional | Git branch to deploy to this domain | - - ---- - -## EdgeFunctionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Edge function name | -| **path** | `string` | ✅ | Function path (e.g., /api/*) | -| **regions** | `string[]` | optional | Specific regions for this function | -| **memoryLimit** | `integer` | optional | Memory limit in MB | -| **timeout** | `integer` | optional | Timeout in seconds | - - ---- - -## EnvironmentVariables - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **key** | `string` | ✅ | Environment variable name | -| **value** | `string` | ✅ | Environment variable value | -| **target** | `Enum<'production' \| 'preview' \| 'development'>[]` | ✅ | Target environments | -| **isSecret** | `boolean` | optional | Encrypt this variable | -| **gitBranch** | `string` | optional | Specific git branch | - - ---- - -## FileAccessPattern - -File access pattern - -### Allowed Values - -* `public_read` -* `private` -* `authenticated_read` -* `bucket_owner_read` -* `bucket_owner_full` - - ---- - -## FileFilterConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **includePatterns** | `string[]` | optional | File patterns to include (glob) | -| **excludePatterns** | `string[]` | optional | File patterns to exclude (glob) | -| **minFileSize** | `number` | optional | Minimum file size in bytes | -| **maxFileSize** | `number` | optional | Maximum file size in bytes | -| **allowedExtensions** | `string[]` | optional | Allowed file extensions | -| **blockedExtensions** | `string[]` | optional | Blocked file extensions | - - ---- - -## FileMetadataConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **extractMetadata** | `boolean` | optional | Extract file metadata | -| **metadataFields** | `Enum<'content_type' \| 'file_size' \| 'last_modified' \| 'etag' \| 'checksum' \| 'creator' \| 'created_at' \| 'custom'>[]` | optional | Metadata fields to extract | -| **customMetadata** | `Record` | optional | Custom metadata key-value pairs | - - ---- - -## FileStorageConnector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | -| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'dropbox' \| 'box' \| 'onedrive' \| 'google_drive' \| 'sharepoint' \| 'ftp' \| 'local' \| 'custom'>` | ✅ | File storage provider type | -| **storageConfig** | `Object` | optional | Storage configuration | -| **buckets** | `Object[]` | ✅ | Buckets/containers to sync | -| **metadataConfig** | `Object` | optional | Metadata extraction configuration | -| **multipartConfig** | `Object` | optional | Multipart upload configuration | -| **versioningConfig** | `Object` | optional | File versioning configuration | -| **encryption** | `Object` | optional | Encryption configuration | -| **lifecyclePolicy** | `Object` | optional | Lifecycle policy | -| **contentProcessing** | `Object` | optional | Content processing configuration | -| **bufferSize** | `number` | optional | Buffer size in bytes | -| **transferAcceleration** | `boolean` | optional | Enable transfer acceleration | - - ---- - -## FileStorageProvider - -File storage provider type - -### Allowed Values - -* `s3` -* `azure_blob` -* `gcs` -* `dropbox` -* `box` -* `onedrive` -* `google_drive` -* `sharepoint` -* `ftp` -* `local` -* `custom` - - ---- - -## FileVersioningConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable file versioning | -| **maxVersions** | `number` | optional | Maximum versions to retain | -| **retentionDays** | `number` | optional | Version retention period in days | - - ---- - -## GitHubActionsWorkflow - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Workflow name | -| **path** | `string` | ✅ | Workflow file path (e.g., .github/workflows/ci.yml) | -| **enabled** | `boolean` | optional | Enable workflow | -| **triggers** | `Enum<'push' \| 'pull_request' \| 'release' \| 'schedule' \| 'workflow_dispatch' \| 'repository_dispatch'>[]` | optional | Workflow triggers | -| **env** | `Record` | optional | Environment variables | -| **secrets** | `string[]` | optional | Required secrets | - - ---- - -## GitHubCommitConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **authorName** | `string` | optional | Commit author name | -| **authorEmail** | `string` | optional | Commit author email | -| **signCommits** | `boolean` | optional | Sign commits with GPG | -| **messageTemplate** | `string` | optional | Commit message template | -| **useConventionalCommits** | `boolean` | optional | Use conventional commits format | - - ---- - -## GitHubConnector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | -| **provider** | `Enum<'github' \| 'github_enterprise'>` | ✅ | GitHub provider | -| **baseUrl** | `string` | optional | GitHub API base URL | -| **repositories** | `Object[]` | ✅ | Repositories to manage | -| **commitConfig** | `Object` | optional | Commit configuration | -| **pullRequestConfig** | `Object` | optional | Pull request configuration | -| **workflows** | `Object[]` | optional | GitHub Actions workflows | -| **releaseConfig** | `Object` | optional | Release configuration | -| **issueTracking** | `Object` | optional | Issue tracking configuration | -| **enableWebhooks** | `boolean` | optional | Enable GitHub webhooks | -| **webhookEvents** | `Enum<'push' \| 'pull_request' \| 'issues' \| 'issue_comment' \| 'release' \| 'workflow_run' \| 'deployment' \| 'deployment_status' \| 'check_run' \| 'check_suite' \| 'status'>[]` | optional | Webhook events to subscribe to | - - ---- - -## GitHubIssueTracking - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable issue tracking | -| **defaultLabels** | `string[]` | optional | Default issue labels | -| **templatePaths** | `string[]` | optional | Issue template paths | -| **autoAssign** | `boolean` | optional | Auto-assign issues | -| **autoCloseStale** | `Object` | optional | Auto-close stale issues configuration | - - ---- - -## GitHubProvider - -GitHub provider type - -### Allowed Values - -* `github` -* `github_enterprise` - - ---- - -## GitHubPullRequestConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **titleTemplate** | `string` | optional | PR title template | -| **bodyTemplate** | `string` | optional | PR body template | -| **defaultReviewers** | `string[]` | optional | Default reviewers (usernames) | -| **defaultAssignees** | `string[]` | optional | Default assignees (usernames) | -| **defaultLabels** | `string[]` | optional | Default labels | -| **draftByDefault** | `boolean` | optional | Create draft PRs by default | -| **deleteHeadBranch** | `boolean` | optional | Delete head branch after merge | - - ---- - -## GitHubReleaseConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **tagPattern** | `string` | optional | Tag name pattern (e.g., v*, release/*) | -| **semanticVersioning** | `boolean` | optional | Use semantic versioning | -| **autoReleaseNotes** | `boolean` | optional | Generate release notes automatically | -| **releaseNameTemplate** | `string` | optional | Release name template | -| **preReleasePattern** | `string` | optional | Pre-release pattern (e.g., *-alpha, *-beta) | -| **draftByDefault** | `boolean` | optional | Create draft releases by default | - - ---- - -## GitHubRepository - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **owner** | `string` | ✅ | Repository owner (organization or username) | -| **name** | `string` | ✅ | Repository name | -| **defaultBranch** | `string` | optional | Default branch name | -| **autoMerge** | `boolean` | optional | Enable auto-merge for pull requests | -| **branchProtection** | `Object` | optional | Branch protection configuration | -| **topics** | `string[]` | optional | Repository topics | - - ---- - -## GitRepositoryConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'github' \| 'gitlab' \| 'bitbucket'>` | ✅ | Git provider | -| **repo** | `string` | ✅ | Repository identifier (e.g., owner/repo) | -| **productionBranch** | `string` | optional | Production branch name | -| **autoDeployProduction** | `boolean` | optional | Auto-deploy production branch | -| **autoDeployPreview** | `boolean` | optional | Auto-deploy preview branches | - - ---- - -## MessageFormat - -Message format/serialization - -### Allowed Values - -* `json` -* `xml` -* `protobuf` -* `avro` -* `text` -* `binary` - - ---- - -## MessageQueueConnector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | -| **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 | -| **brokerConfig** | `Object` | ✅ | Broker connection configuration | -| **topics** | `Object[]` | ✅ | Topics/queues to sync | -| **deliveryGuarantee** | `Enum<'at_most_once' \| 'at_least_once' \| 'exactly_once'>` | optional | Message delivery guarantee | -| **sslConfig** | `Object` | optional | SSL/TLS configuration | -| **saslConfig** | `Object` | optional | SASL authentication configuration | -| **schemaRegistry** | `Object` | optional | Schema registry configuration | -| **preserveOrder** | `boolean` | optional | Preserve message ordering | -| **enableMetrics** | `boolean` | optional | Enable message queue metrics | -| **enableTracing** | `boolean` | optional | Enable distributed tracing | - - ---- - -## ProducerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable producer | -| **acks** | `Enum<'0' \| '1' \| 'all'>` | optional | Acknowledgment level | -| **compressionType** | `Enum<'none' \| 'gzip' \| 'snappy' \| 'lz4' \| 'zstd'>` | optional | Compression type | -| **batchSize** | `number` | optional | Batch size in bytes | -| **lingerMs** | `number` | optional | Linger time in ms | -| **maxInFlightRequests** | `number` | optional | Max in-flight requests | -| **idempotence** | `boolean` | optional | Enable idempotent producer | -| **transactional** | `boolean` | optional | Enable transactional producer | -| **transactionTimeoutMs** | `number` | optional | Transaction timeout in ms | - - ---- - -## SaasConnector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | -| **provider** | `Enum<'salesforce' \| 'hubspot' \| 'stripe' \| 'shopify' \| 'zendesk' \| 'intercom' \| 'mailchimp' \| 'slack' \| 'microsoft_dynamics' \| 'servicenow' \| 'netsuite' \| 'custom'>` | ✅ | SaaS provider type | -| **baseUrl** | `string` | ✅ | API base URL | -| **apiVersion** | `Object` | optional | API version configuration | -| **objectTypes** | `Object[]` | ✅ | Syncable object types | -| **oauthSettings** | `Object` | optional | OAuth-specific configuration | -| **paginationConfig** | `Object` | optional | Pagination configuration | -| **sandboxConfig** | `Object` | optional | Sandbox environment configuration | -| **customHeaders** | `Record` | optional | Custom HTTP headers for all requests | - - ---- - -## SaasObjectType - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Object type name (snake_case) | -| **label** | `string` | ✅ | Display label | -| **apiName** | `string` | ✅ | API name in external system | -| **enabled** | `boolean` | optional | Enable sync for this object | -| **supportsCreate** | `boolean` | optional | Supports record creation | -| **supportsUpdate** | `boolean` | optional | Supports record updates | -| **supportsDelete** | `boolean` | optional | Supports record deletion | -| **fieldMappings** | `Object[]` | optional | Object-specific field mappings | - - ---- - -## SaasProvider - -SaaS provider type - -### Allowed Values - -* `salesforce` -* `hubspot` -* `stripe` -* `shopify` -* `zendesk` -* `intercom` -* `mailchimp` -* `slack` -* `microsoft_dynamics` -* `servicenow` -* `netsuite` -* `custom` - - ---- - -## SslConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable SSL/TLS | -| **rejectUnauthorized** | `boolean` | optional | Reject unauthorized certificates | -| **ca** | `string` | optional | Certificate Authority certificate | -| **cert** | `string` | optional | Client certificate | -| **key** | `string` | optional | Client private key | - - ---- - -## StorageBucket - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Bucket identifier in ObjectStack (snake_case) | -| **label** | `string` | ✅ | Display label | -| **bucketName** | `string` | ✅ | Actual bucket/container name in storage system | -| **region** | `string` | optional | Storage region | -| **enabled** | `boolean` | optional | 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 | - - ---- - -## TopicQueue - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Topic/queue identifier in ObjectStack (snake_case) | -| **label** | `string` | ✅ | Display label | -| **topicName** | `string` | ✅ | Actual topic/queue name in message queue system | -| **enabled** | `boolean` | optional | Enable sync for this topic/queue | -| **mode** | `Enum<'consumer' \| 'producer' \| 'both'>` | optional | Consumer, producer, or both | -| **messageFormat** | `Enum<'json' \| 'xml' \| 'protobuf' \| 'avro' \| 'text' \| 'binary'>` | optional | 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 | -| **routingKey** | `string` | optional | Routing key pattern | -| **messageFilter** | `Object` | optional | Message filter criteria | - - ---- - -## VercelConnector - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique connector identifier | -| **label** | `string` | ✅ | Display label | -| **type** | `string` | ✅ | | -| **description** | `string` | optional | Connector description | -| **icon** | `string` | optional | Icon identifier | -| **authentication** | `Object \| Object \| Object \| Object \| Object` | ✅ | Authentication configuration | -| **actions** | `Object[]` | optional | | -| **triggers** | `Object[]` | optional | | -| **syncConfig** | `Object` | optional | Data sync configuration | -| **fieldMappings** | `Object[]` | optional | Field mapping rules | -| **webhooks** | `Object[]` | optional | Webhook configurations | -| **rateLimitConfig** | `Object` | optional | Rate limiting configuration | -| **retryConfig** | `Object` | optional | Retry configuration | -| **connectionTimeoutMs** | `number` | optional | Connection timeout in ms | -| **requestTimeoutMs** | `number` | optional | Request timeout in ms | -| **status** | `Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>` | optional | Connector status | -| **enabled** | `boolean` | optional | Enable connector | -| **metadata** | `Record` | optional | Custom connector metadata | -| **provider** | `Enum<'vercel'>` | ✅ | Vercel provider | -| **baseUrl** | `string` | optional | Vercel API base URL | -| **team** | `Object` | optional | Vercel team configuration | -| **projects** | `Object[]` | ✅ | Vercel projects | -| **monitoring** | `Object` | optional | Monitoring configuration | -| **enableWebhooks** | `boolean` | optional | Enable Vercel webhooks | -| **webhookEvents** | `Enum<'deployment.created' \| 'deployment.succeeded' \| 'deployment.failed' \| 'deployment.ready' \| 'deployment.error' \| 'deployment.canceled' \| 'deployment-checks-completed' \| 'deployment-prepared' \| 'project.created' \| 'project.removed'>[]` | optional | Webhook events to subscribe to | - - ---- - -## VercelFramework - -Frontend framework - -### Allowed Values - -* `nextjs` -* `react` -* `vue` -* `nuxtjs` -* `gatsby` -* `remix` -* `astro` -* `sveltekit` -* `solid` -* `angular` -* `static` -* `other` - - ---- - -## VercelMonitoring - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enableWebAnalytics** | `boolean` | optional | Enable Vercel Web Analytics | -| **enableSpeedInsights** | `boolean` | optional | Enable Vercel Speed Insights | -| **logDrains** | `Object[]` | optional | Log drains configuration | - - ---- - -## VercelProject - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | -| **rootDirectory** | `string` | optional | Root directory (for monorepos) | - - ---- - -## VercelProvider - -Vercel provider type - -### Allowed Values - -* `vercel` - - ---- - -## VercelTeam - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **teamId** | `string` | optional | Team ID or slug | -| **teamName** | `string` | optional | Team name | - - ---- - diff --git a/content/docs/references/integration/object-storage.mdx b/content/docs/references/integration/object-storage.mdx deleted file mode 100644 index deb000864..000000000 --- a/content/docs/references/integration/object-storage.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Object Storage -description: Object Storage protocol schemas ---- - - -**Source:** `packages/spec/src/integration/object-storage.zod.ts` - - -## TypeScript Usage - -```typescript -import { MultipartUploadConfig } from '@objectstack/spec/integration'; -import type { MultipartUploadConfig } from '@objectstack/spec/integration'; - -// Validate data -const result = MultipartUploadConfig.parse(data); -``` - ---- - -## MultipartUploadConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable multipart uploads | -| **partSize** | `number` | optional | Part size in bytes (min 5MB) | -| **maxConcurrentParts** | `number` | optional | Maximum concurrent part uploads | -| **threshold** | `number` | optional | File size threshold for multipart upload in bytes | - - ---- - diff --git a/content/docs/references/kernel/context.mdx b/content/docs/references/kernel/context.mdx deleted file mode 100644 index a9be68dbe..000000000 --- a/content/docs/references/kernel/context.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Context -description: Context protocol schemas ---- - -Runtime Mode Enum - -Defines the operating mode of the kernel - - -**Source:** `packages/spec/src/kernel/context.zod.ts` - - -## TypeScript Usage - -```typescript -import { KernelContext, RuntimeMode } from '@objectstack/spec/kernel'; -import type { KernelContext, RuntimeMode } from '@objectstack/spec/kernel'; - -// Validate data -const result = KernelContext.parse(data); -``` - ---- - -## KernelContext - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **instanceId** | `string` | ✅ | Unique UUID for this running kernel process | -| **mode** | `Enum<'development' \| 'production' \| 'test' \| 'provisioning'>` | optional | Kernel operating mode | -| **version** | `string` | ✅ | Kernel version | -| **appName** | `string` | optional | Host application name | -| **cwd** | `string` | ✅ | Current working directory | -| **workspaceRoot** | `string` | optional | Workspace root if different from cwd | -| **startTime** | `integer` | ✅ | Boot timestamp (ms) | -| **features** | `Record` | optional | Global feature toggles | - - ---- - -## RuntimeMode - -Kernel operating mode - -### Allowed Values - -* `development` -* `production` -* `test` -* `provisioning` - - ---- - diff --git a/content/docs/references/kernel/events.mdx b/content/docs/references/kernel/events.mdx deleted file mode 100644 index c84ef6e03..000000000 --- a/content/docs/references/kernel/events.mdx +++ /dev/null @@ -1,288 +0,0 @@ ---- -title: Events -description: Events protocol schemas ---- - -Event Priority Enum - -Priority levels for event processing - -Lower numbers = higher priority - - -**Source:** `packages/spec/src/kernel/events.zod.ts` - - -## TypeScript Usage - -```typescript -import { DeadLetterQueueEntry, Event, EventBusConfig, EventHandler, EventLogEntry, EventMessageQueueConfig, EventMetadata, EventPersistence, EventPriority, EventQueueConfig, EventReplayConfig, EventRoute, EventSourcingConfig, EventTypeDefinition, EventWebhookConfig, RealTimeNotificationConfig } from '@objectstack/spec/kernel'; -import type { DeadLetterQueueEntry, Event, EventBusConfig, EventHandler, EventLogEntry, EventMessageQueueConfig, EventMetadata, EventPersistence, EventPriority, EventQueueConfig, EventReplayConfig, EventRoute, EventSourcingConfig, EventTypeDefinition, EventWebhookConfig, RealTimeNotificationConfig } from '@objectstack/spec/kernel'; - -// Validate data -const result = DeadLetterQueueEntry.parse(data); -``` - ---- - -## DeadLetterQueueEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique entry identifier | -| **event** | `Object` | ✅ | Original event | -| **error** | `Object` | ✅ | Failure details | -| **retries** | `integer` | ✅ | Number of retry attempts | -| **firstFailedAt** | `string` | ✅ | When event first failed | -| **lastFailedAt** | `string` | ✅ | When event last failed | -| **failedHandler** | `string` | optional | Handler ID that failed | - - ---- - -## Event - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique event identifier | -| **name** | `string` | ✅ | Event name (lowercase with dots, e.g., user.created, order.paid) | -| **payload** | `any` | optional | Event payload schema | -| **metadata** | `Object` | ✅ | Event metadata | - - ---- - -## EventBusConfig - -### Properties - -| 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 | - - ---- - -## EventHandler - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique handler identifier | -| **eventName** | `string` | ✅ | Name of event to handle (supports wildcards like user.*) | -| **handler** | `any` | optional | Handler function | -| **priority** | `integer` | optional | Execution priority (lower numbers execute first) | -| **async** | `boolean` | optional | Execute in background (true) or block (false) | -| **retry** | `Object` | optional | Retry policy for failed handlers | -| **timeoutMs** | `integer` | optional | Handler timeout in milliseconds | -| **filter** | `any` | optional | Optional filter to determine if handler should execute | - - ---- - -## EventLogEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique log entry identifier | -| **event** | `Object` | ✅ | The event | -| **status** | `Enum<'pending' \| 'processing' \| 'completed' \| 'failed'>` | ✅ | Processing status | -| **handlersExecuted** | `Object[]` | 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 | - - ---- - -## EventMessageQueueConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'kafka' \| 'rabbitmq' \| 'aws-sqs' \| 'redis-pubsub' \| 'google-pubsub' \| 'azure-service-bus'>` | ✅ | Message queue provider | -| **topic** | `string` | ✅ | Topic or queue name | -| **eventPattern** | `string` | optional | Event name pattern to publish (supports wildcards) | -| **partitionKey** | `string` | optional | JSON path for partition key (e.g., "metadata.tenantId") | -| **format** | `Enum<'json' \| 'avro' \| 'protobuf'>` | optional | Message serialization format | -| **includeMetadata** | `boolean` | optional | Include event metadata in message | -| **compression** | `Enum<'none' \| 'gzip' \| 'snappy' \| 'lz4'>` | optional | Message compression | -| **batchSize** | `integer` | optional | Batch size for publishing | -| **flushIntervalMs** | `integer` | optional | Flush interval for batching | - - ---- - -## EventMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Event source (e.g., plugin name, system component) | -| **timestamp** | `string` | ✅ | ISO 8601 datetime when event was created | -| **userId** | `string` | optional | User who triggered the event | -| **tenantId** | `string` | optional | Tenant identifier for multi-tenant systems | -| **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'>` | optional | Event priority | - - ---- - -## EventPersistence - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable event persistence | -| **retention** | `integer` | ✅ | Days to retain persisted events | -| **filter** | `any` | optional | Optional filter function to select which events to persist | -| **storage** | `Enum<'database' \| 'file' \| 's3' \| 'custom'>` | optional | Storage backend for persisted events | - - ---- - -## EventPriority - -### Allowed Values - -* `critical` -* `high` -* `normal` -* `low` -* `background` - - ---- - -## EventQueueConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Event queue name | -| **concurrency** | `integer` | optional | Max concurrent event handlers | -| **retryPolicy** | `Object` | optional | Default retry policy for events | -| **deadLetterQueue** | `string` | optional | Dead letter queue name for failed events | -| **priorityEnabled** | `boolean` | optional | Process events based on priority | - - ---- - -## EventReplayConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fromTimestamp** | `string` | ✅ | Start timestamp for replay (ISO 8601) | -| **toTimestamp** | `string` | optional | End timestamp for replay (ISO 8601) | -| **eventTypes** | `string[]` | optional | Event types to replay (empty = all) | -| **filters** | `Record` | optional | Additional filters for event selection | -| **speed** | `number` | optional | Replay speed multiplier (1 = real-time) | -| **targetHandlers** | `string[]` | optional | Handler IDs to execute (empty = all) | - - ---- - -## EventRoute - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **from** | `string` | ✅ | Source event pattern (supports wildcards, e.g., user.* or *.created) | -| **to** | `string[]` | ✅ | Target event names to route to | -| **transform** | `any` | optional | Optional function to transform payload | - - ---- - -## EventSourcingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable event sourcing | -| **snapshotInterval** | `integer` | optional | Create snapshot every N events | -| **snapshotRetention** | `integer` | optional | Number of snapshots to retain | -| **retention** | `integer` | optional | Days to retain events | -| **aggregateTypes** | `string[]` | optional | Aggregate types to enable event sourcing for | -| **storage** | `Object` | optional | Event store configuration | - - ---- - -## EventTypeDefinition - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Event type name (lowercase with dots) | -| **version** | `string` | optional | Event schema version | -| **schema** | `any` | optional | JSON Schema for event payload validation | -| **description** | `string` | optional | Event type description | -| **deprecated** | `boolean` | optional | Whether this event type is deprecated | -| **tags** | `string[]` | optional | Event type tags | - - ---- - -## EventWebhookConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | optional | Unique webhook identifier | -| **eventPattern** | `string` | ✅ | Event name pattern (supports wildcards) | -| **url** | `string` | ✅ | Webhook endpoint URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH'>` | optional | HTTP method | -| **headers** | `Record` | optional | HTTP headers | -| **authentication** | `Object` | optional | Authentication configuration | -| **retryPolicy** | `Object` | optional | Retry policy | -| **timeoutMs** | `integer` | optional | Request timeout in milliseconds | -| **transform** | `any` | optional | Transform event before sending | -| **enabled** | `boolean` | optional | Whether webhook is enabled | - - ---- - -## RealTimeNotificationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable real-time notifications | -| **protocol** | `Enum<'websocket' \| 'sse' \| 'long-polling'>` | optional | Real-time protocol | -| **eventPattern** | `string` | optional | Event pattern to broadcast | -| **userFilter** | `boolean` | optional | Filter events by user | -| **tenantFilter** | `boolean` | optional | Filter events by tenant | -| **channels** | `Object[]` | optional | Named channels for event broadcasting | -| **rateLimit** | `Object` | optional | Rate limiting configuration | - - ---- - diff --git a/content/docs/references/kernel/feature.mdx b/content/docs/references/kernel/feature.mdx deleted file mode 100644 index 831e6e89b..000000000 --- a/content/docs/references/kernel/feature.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Feature -description: Feature protocol schemas ---- - -Feature Rollout Strategy - - -**Source:** `packages/spec/src/kernel/feature.zod.ts` - - -## TypeScript Usage - -```typescript -import { FeatureFlag, FeatureStrategy } from '@objectstack/spec/kernel'; -import type { FeatureFlag, FeatureStrategy } from '@objectstack/spec/kernel'; - -// Validate data -const result = FeatureFlag.parse(data); -``` - ---- - -## FeatureFlag - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Feature key (snake_case) | -| **label** | `string` | optional | Display label | -| **description** | `string` | optional | | -| **enabled** | `boolean` | optional | Is globally enabled | -| **strategy** | `Enum<'boolean' \| 'percentage' \| 'user_list' \| 'group' \| 'custom'>` | optional | | -| **conditions** | `Object` | optional | | -| **environment** | `Enum<'dev' \| 'staging' \| 'prod' \| 'all'>` | optional | Environment validity | -| **expiresAt** | `string` | optional | Feature flag expiration date | - - ---- - -## FeatureStrategy - -### Allowed Values - -* `boolean` -* `percentage` -* `user_list` -* `group` -* `custom` - - ---- - diff --git a/content/docs/references/kernel/index.mdx b/content/docs/references/kernel/index.mdx index bf7301267..eacc5b699 100644 --- a/content/docs/references/kernel/index.mdx +++ b/content/docs/references/kernel/index.mdx @@ -17,6 +17,9 @@ This section contains all protocol schemas for the kernel layer of ObjectStack. + + + diff --git a/content/docs/references/kernel/manifest.mdx b/content/docs/references/kernel/manifest.mdx deleted file mode 100644 index cf55e67ba..000000000 --- a/content/docs/references/kernel/manifest.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Manifest -description: Manifest protocol schemas ---- - -Schema for the ObjectStack Manifest. - -This defines the structure of a package configuration in the ObjectStack ecosystem. - -All packages (apps, plugins, drivers, modules) must conform to this schema. - -@example App Package - -```yaml - -id: com.acme.crm - -version: 1.0.0 - -type: app - -name: Acme CRM - -description: Customer Relationship Management system - -permissions: - -- system.user.read - -- system.object.create - -objects: - -- "./src/objects/*.object.yml" - -``` - - -**Source:** `packages/spec/src/kernel/manifest.zod.ts` - - -## TypeScript Usage - -```typescript -import { Manifest } from '@objectstack/spec/kernel'; -import type { Manifest } from '@objectstack/spec/kernel'; - -// Validate data -const result = Manifest.parse(data); -``` - ---- - -## Manifest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique package identifier (reverse domain style) | -| **namespace** | `string` | optional | Short namespace identifier for metadata scoping (e.g. "crm", "todo") | -| **version** | `string` | ✅ | Package version (semantic versioning) | -| **type** | `Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| 'module' \| 'gateway' \| 'adapter'>` | ✅ | Type of package | -| **name** | `string` | ✅ | Human-readable package name | -| **description** | `string` | optional | Package description | -| **permissions** | `string[]` | optional | Array of required permission strings | -| **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 | -| **capabilities** | `Object` | optional | Plugin capability declarations for interoperability | -| **extensions** | `Record` | optional | Extension points and contributions | -| **loading** | `Object` | optional | Plugin loading and runtime behavior configuration | - - ---- - diff --git a/content/docs/references/kernel/meta.json b/content/docs/references/kernel/meta.json deleted file mode 100644 index b6790a1ab..000000000 --- a/content/docs/references/kernel/meta.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "title": "Kernel Protocol", - "pages": [ - "context", - "events", - "feature", - "manifest", - "metadata-persistence", - "package-registry", - "permission", - "plugin", - "plugin-capability", - "plugin-lifecycle-advanced", - "plugin-lifecycle-events", - "plugin-loading", - "plugin-security-advanced", - "plugin-structure", - "plugin-validator", - "plugin-versioning", - "service-registry", - "startup-orchestrator", - "plugin-registry", - "plugin-security" - ] -} \ No newline at end of file diff --git a/content/docs/references/kernel/metadata-persistence.mdx b/content/docs/references/kernel/metadata-persistence.mdx deleted file mode 100644 index 11c0483c1..000000000 --- a/content/docs/references/kernel/metadata-persistence.mdx +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Metadata Persistence -description: Metadata Persistence protocol schemas ---- - - -**Source:** `packages/spec/src/kernel/metadata-persistence.zod.ts` - - -## TypeScript Usage - -```typescript -import { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; -import type { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; - -// Validate data -const result = MetadataCollectionInfo.parse(data); -``` - ---- - -## MetadataCollectionInfo - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Collection type | -| **count** | `integer` | ✅ | Number of items | -| **formats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Formats in collection | -| **totalSize** | `integer` | optional | Total size in bytes | -| **lastModified** | `string` | optional | Last modification date | -| **location** | `string` | optional | Collection location | - - ---- - -## MetadataExportOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **output** | `string` | ✅ | Output file path | -| **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | optional | Export format | -| **filter** | `string` | optional | Filter items to export | -| **includeStats** | `boolean` | optional | Include metadata statistics | -| **compress** | `boolean` | optional | Compress output (gzip) | -| **prettify** | `boolean` | optional | Pretty print output | - - ---- - -## MetadataFormat - -### Allowed Values - -* `json` -* `yaml` -* `typescript` -* `javascript` - - ---- - -## MetadataImportOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **conflictResolution** | `Enum<'skip' \| 'overwrite' \| 'merge' \| 'fail'>` | optional | How to handle existing items | -| **validate** | `boolean` | optional | Validate before import | -| **dryRun** | `boolean` | optional | Simulate import without saving | -| **continueOnError** | `boolean` | optional | Continue if validation fails | -| **transform** | `string` | optional | Transform items before import | - - ---- - -## MetadataLoadOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **patterns** | `string[]` | optional | File glob patterns | -| **ifNoneMatch** | `string` | optional | ETag for conditional request | -| **ifModifiedSince** | `string` | optional | Only load if modified after this date | -| **validate** | `boolean` | optional | Validate against schema | -| **useCache** | `boolean` | optional | Enable caching | -| **filter** | `string` | optional | Filter predicate as string | -| **limit** | `integer` | optional | Maximum items to load | -| **recursive** | `boolean` | optional | Search subdirectories | - - ---- - -## MetadataLoadResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `any \| null` | optional | Loaded metadata | -| **fromCache** | `boolean` | optional | Loaded from cache | -| **notModified** | `boolean` | optional | Not modified since last request | -| **etag** | `string` | optional | Entity tag | -| **stats** | `Object` | optional | Metadata statistics | -| **loadTime** | `number` | optional | Load duration in ms | - - ---- - -## MetadataLoaderContract - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Loader identifier | -| **protocol** | `string` | ✅ | Protocol identifier | -| **capabilities** | `Object` | ✅ | Loader capabilities | -| **supportedFormats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Supported formats | -| **supportsWatch** | `boolean` | optional | Supports file watching | -| **supportsWrite** | `boolean` | optional | Supports write operations | -| **supportsCache** | `boolean` | optional | Supports caching | - - ---- - -## MetadataManagerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **rootDir** | `string` | optional | Root directory path | -| **formats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | optional | Enabled formats | -| **cache** | `Object` | optional | Cache settings | -| **watch** | `boolean` | optional | Enable file watching | -| **watchOptions** | `Object` | optional | File watcher options | -| **validation** | `Object` | optional | Validation settings | -| **loaderOptions** | `Record` | optional | Loader-specific configuration | - - ---- - -## MetadataSaveOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | optional | Output format | -| **prettify** | `boolean` | optional | Format with indentation | -| **indent** | `integer` | optional | Indentation spaces | -| **sortKeys** | `boolean` | optional | Sort object keys | -| **includeDefaults** | `boolean` | optional | Include default values | -| **backup** | `boolean` | optional | Create backup file | -| **overwrite** | `boolean` | optional | Overwrite existing file | -| **atomic** | `boolean` | optional | Use atomic write operation | -| **path** | `string` | optional | Custom output path | - - ---- - -## MetadataSaveResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | Save successful | -| **path** | `string` | ✅ | Output path | -| **etag** | `string` | optional | Generated entity tag | -| **size** | `integer` | optional | File size | -| **saveTime** | `number` | optional | Save duration in ms | -| **backupPath** | `string` | optional | Backup file path | - - ---- - -## MetadataStats - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **size** | `integer` | ✅ | File size in bytes | -| **modifiedAt** | `string` | ✅ | Last modified date | -| **etag** | `string` | ✅ | Entity tag for cache validation | -| **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | ✅ | Serialization format | -| **path** | `string` | optional | File system path | -| **metadata** | `Record` | optional | Provider-specific metadata | - - ---- - -## MetadataWatchEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'added' \| 'changed' \| 'deleted'>` | ✅ | Event type | -| **metadataType** | `string` | ✅ | Type of metadata | -| **name** | `string` | ✅ | Item identifier | -| **path** | `string` | ✅ | File path | -| **data** | `any` | optional | Item data | -| **timestamp** | `string` | ✅ | Event timestamp | - - ---- - diff --git a/content/docs/references/kernel/package-registry.mdx b/content/docs/references/kernel/package-registry.mdx deleted file mode 100644 index 6b2df44f4..000000000 --- a/content/docs/references/kernel/package-registry.mdx +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: Package Registry -description: Package Registry protocol schemas ---- - -# Package Registry Protocol - -Defines the runtime state and lifecycle operations for installed packages. - -## Key Distinction: Package vs App - -- **Package (Manifest)**: The unit of installation — a deployable artifact containing - -metadata (objects, actions, flows, etc.) and optionally one or more Apps. - -- **App (AppSchema)**: A UI navigation shell defined inside a package. - -A package may contain: - -- Zero apps (pure functionality plugin, e.g. a storage driver) - -- One app (typical business application) - -- Multiple apps (suite of applications) - -## Architecture Alignment - -- **Salesforce**: Managed Packages with install/uninstall lifecycle - -- **VS Code**: Extension marketplace with enable/disable per-workspace - -- **Kubernetes**: Helm charts with release state tracking - -- **npm**: Package registry with install/uninstall/version management - - -**Source:** `packages/spec/src/kernel/package-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; -import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; - -// Validate data -const result = DisablePackageRequest.parse(data); -``` - ---- - -## DisablePackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## DisablePackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## EnablePackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## EnablePackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## GetPackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## GetPackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | - - ---- - -## InstallPackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | | -| **settings** | `Record` | optional | | -| **enableOnInstall** | `boolean` | optional | | - - ---- - -## InstallPackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `Object` | ✅ | | -| **message** | `string` | optional | | - - ---- - -## InstalledPackage - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **manifest** | `Object` | ✅ | | -| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'uninstalling' \| 'error'>` | optional | | -| **enabled** | `boolean` | optional | | -| **installedAt** | `string` | optional | | -| **updatedAt** | `string` | optional | | -| **statusChangedAt** | `string` | optional | | -| **errorMessage** | `string` | optional | | -| **settings** | `Record` | optional | | - - ---- - -## ListPackagesRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'uninstalling' \| 'error'>` | optional | | -| **type** | `Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| 'module' \| 'gateway' \| 'adapter'>` | optional | Type of package | -| **enabled** | `boolean` | optional | | - - ---- - -## ListPackagesResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **packages** | `Object[]` | ✅ | | -| **total** | `number` | ✅ | | - - ---- - -## PackageStatusEnum - -### Allowed Values - -* `installed` -* `disabled` -* `installing` -* `uninstalling` -* `error` - - ---- - -## UninstallPackageRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | - - ---- - -## UninstallPackageResponse - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **success** | `boolean` | ✅ | | -| **message** | `string` | optional | | - - ---- - diff --git a/content/docs/references/kernel/permission.mdx b/content/docs/references/kernel/permission.mdx deleted file mode 100644 index c781f0714..000000000 --- a/content/docs/references/kernel/permission.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Permission -description: Permission protocol schemas ---- - - -**Source:** `packages/spec/src/kernel/permission.zod.ts` - - -## TypeScript Usage - -```typescript -import { PermissionSet } from '@objectstack/spec/kernel'; -import type { PermissionSet } from '@objectstack/spec/kernel'; - -// Validate data -const result = PermissionSet.parse(data); -``` - ---- - -## PermissionSet - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **permissions** | `Object[]` | ✅ | | -| **groups** | `Object[]` | optional | | -| **defaultGrant** | `Enum<'prompt' \| 'allow' \| 'deny' \| 'inherit'>` | optional | | - - ---- - diff --git a/content/docs/references/kernel/plugin-capability.mdx b/content/docs/references/kernel/plugin-capability.mdx deleted file mode 100644 index fbbf7ef93..000000000 --- a/content/docs/references/kernel/plugin-capability.mdx +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Plugin Capability -description: Plugin Capability protocol schemas ---- - -# Plugin Capability Protocol - -Defines the standard way plugins declare their capabilities, implementations, - -and conformance levels to ensure interoperability across vendors. - -Based on the Protocol-Oriented Architecture pattern similar to: - -- Kubernetes CRDs (Custom Resource Definitions) - -- OSGi Service Registry - -- Eclipse Extension Points - - -**Source:** `packages/spec/src/kernel/plugin-capability.zod.ts` - - -## TypeScript Usage - -```typescript -import { CapabilityConformanceLevel, ExtensionPoint, PluginCapability, PluginCapabilityManifest, PluginDependency, PluginInterface, ProtocolFeature, ProtocolReference, ProtocolVersion } from '@objectstack/spec/kernel'; -import type { CapabilityConformanceLevel, ExtensionPoint, PluginCapability, PluginCapabilityManifest, PluginDependency, PluginInterface, ProtocolFeature, ProtocolReference, ProtocolVersion } from '@objectstack/spec/kernel'; - -// Validate data -const result = CapabilityConformanceLevel.parse(data); -``` - ---- - -## CapabilityConformanceLevel - -Level of protocol conformance - -### Allowed Values - -* `full` -* `partial` -* `experimental` -* `deprecated` - - ---- - -## ExtensionPoint - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique extension point identifier | -| **name** | `string` | ✅ | | -| **description** | `string` | optional | | -| **type** | `Enum<'action' \| 'hook' \| 'widget' \| 'provider' \| 'transformer' \| 'validator' \| 'decorator'>` | ✅ | | -| **contract** | `Object` | optional | | -| **cardinality** | `Enum<'single' \| 'multiple'>` | optional | Whether multiple extensions can register to this point | - - ---- - -## PluginCapability - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **protocol** | `Object` | ✅ | | -| **conformance** | `Enum<'full' \| 'partial' \| 'experimental' \| 'deprecated'>` | optional | Level of protocol conformance | -| **implementedFeatures** | `string[]` | optional | List of implemented feature names | -| **features** | `Object[]` | optional | | -| **metadata** | `Record` | optional | | -| **certified** | `boolean` | optional | Has passed official conformance tests | -| **certificationDate** | `string` | optional | | - - ---- - -## PluginCapabilityManifest - -### Properties - -| 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 | - - ---- - -## PluginDependency - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | Required plugin identifier | -| **version** | `string` | ✅ | Semantic version constraint | -| **optional** | `boolean` | optional | | -| **reason** | `string` | optional | | -| **requiredCapabilities** | `string[]` | optional | Protocol IDs the dependency must support | - - ---- - -## PluginInterface - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique interface identifier | -| **name** | `string` | ✅ | | -| **description** | `string` | optional | | -| **version** | `Object` | ✅ | Semantic version of the protocol | -| **methods** | `Object[]` | ✅ | | -| **events** | `Object[]` | optional | | -| **stability** | `Enum<'stable' \| 'beta' \| 'alpha' \| 'experimental'>` | optional | | - - ---- - -## ProtocolFeature - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Feature identifier within the protocol | -| **enabled** | `boolean` | optional | | -| **description** | `string` | optional | | -| **sinceVersion** | `string` | optional | Version when this feature was added | -| **deprecatedSince** | `string` | optional | Version when deprecated | - - ---- - -## ProtocolReference - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique protocol identifier (e.g., com.objectstack.protocol.storage.v1) | -| **label** | `string` | ✅ | | -| **version** | `Object` | ✅ | Semantic version of the protocol | -| **specification** | `string` | optional | URL or path to protocol specification | -| **description** | `string` | optional | | - - ---- - -## ProtocolVersion - -Semantic version of the protocol - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **major** | `integer` | ✅ | | -| **minor** | `integer` | ✅ | | -| **patch** | `integer` | ✅ | | - - ---- - diff --git a/content/docs/references/kernel/plugin-lifecycle-advanced.mdx b/content/docs/references/kernel/plugin-lifecycle-advanced.mdx deleted file mode 100644 index e7ebcefe9..000000000 --- a/content/docs/references/kernel/plugin-lifecycle-advanced.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Plugin Lifecycle Advanced -description: Plugin Lifecycle Advanced protocol schemas ---- - -# Advanced Plugin Lifecycle Protocol - -Defines advanced lifecycle management capabilities including: - -- Hot reload and live updates - -- Graceful degradation and fallback mechanisms - -- Health monitoring and auto-recovery - -- State preservation during updates - -This protocol extends the basic plugin lifecycle with enterprise-grade - -features for production environments. - - -**Source:** `packages/spec/src/kernel/plugin-lifecycle-advanced.zod.ts` - - -## TypeScript Usage - -```typescript -import { AdvancedPluginLifecycleConfig, DistributedStateConfig, GracefulDegradation, HotReloadConfig, PluginHealthCheck, PluginHealthReport, PluginHealthStatus, PluginStateSnapshot, PluginUpdateStrategy } from '@objectstack/spec/kernel'; -import type { AdvancedPluginLifecycleConfig, DistributedStateConfig, GracefulDegradation, HotReloadConfig, PluginHealthCheck, PluginHealthReport, PluginHealthStatus, PluginStateSnapshot, PluginUpdateStrategy } from '@objectstack/spec/kernel'; - -// Validate data -const result = AdvancedPluginLifecycleConfig.parse(data); -``` - ---- - -## AdvancedPluginLifecycleConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **health** | `Object` | optional | | -| **hotReload** | `Object` | optional | | -| **degradation** | `Object` | optional | | -| **updates** | `Object` | optional | | -| **resources** | `Object` | optional | | -| **observability** | `Object` | optional | | - - ---- - -## DistributedStateConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'redis' \| 'etcd' \| 'custom'>` | ✅ | Distributed state backend provider | -| **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 | | -| **customConfig** | `Record` | optional | Provider-specific configuration | - - ---- - -## GracefulDegradation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **fallbackMode** | `Enum<'minimal' \| 'cached' \| 'readonly' \| 'offline' \| 'disabled'>` | optional | | -| **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 | | - - ---- - -## HotReloadConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **watchPatterns** | `string[]` | optional | Glob patterns to watch for changes | -| **debounceDelay** | `integer` | optional | Wait time after change detection before reload | -| **preserveState** | `boolean` | optional | Keep plugin state across reloads | -| **stateStrategy** | `Enum<'memory' \| 'disk' \| 'distributed' \| 'none'>` | optional | How to preserve state during reload | -| **distributedConfig** | `Object` | optional | Configuration for distributed state management | -| **shutdownTimeout** | `integer` | optional | 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 | - - ---- - -## PluginHealthCheck - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **interval** | `integer` | optional | How often to perform health checks (default: 30s) | -| **timeout** | `integer` | optional | Maximum time to wait for health check response | -| **failureThreshold** | `integer` | optional | Consecutive failures needed to mark unhealthy | -| **successThreshold** | `integer` | optional | Consecutive successes needed to mark healthy | -| **checkMethod** | `string` | optional | Method name to call for health check | -| **autoRestart** | `boolean` | optional | Automatically restart plugin on health check failure | -| **maxRestartAttempts** | `integer` | optional | Maximum restart attempts before giving up | -| **restartBackoff** | `Enum<'fixed' \| 'linear' \| 'exponential'>` | optional | Backoff strategy for restart delays | - - ---- - -## PluginHealthReport - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | | - - ---- - -## PluginHealthStatus - -Current health status of the plugin - -### Allowed Values - -* `healthy` -* `degraded` -* `unhealthy` -* `failed` -* `recovering` -* `unknown` - - ---- - -## PluginStateSnapshot - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | | -| **version** | `string` | ✅ | | -| **timestamp** | `string` | ✅ | | -| **state** | `Record` | ✅ | | -| **metadata** | `Object` | optional | | - - ---- - -## PluginUpdateStrategy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **mode** | `Enum<'manual' \| 'automatic' \| 'scheduled' \| 'rolling'>` | optional | | -| **autoUpdateConstraints** | `Object` | optional | | -| **schedule** | `Object` | optional | | -| **rollback** | `Object` | optional | | -| **validation** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/kernel/plugin-lifecycle-events.mdx b/content/docs/references/kernel/plugin-lifecycle-events.mdx deleted file mode 100644 index 770e8cf50..000000000 --- a/content/docs/references/kernel/plugin-lifecycle-events.mdx +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Plugin Lifecycle Events -description: Plugin Lifecycle Events protocol schemas ---- - -Plugin Lifecycle Events Protocol - -Zod schemas for plugin lifecycle event data structures. - -These schemas align with the IPluginLifecycleEvents contract interface. - -Following ObjectStack "Zod First" principle - all data structures - -must have Zod schemas for runtime validation and JSON Schema generation. - - -**Source:** `packages/spec/src/kernel/plugin-lifecycle-events.zod.ts` - - -## TypeScript Usage - -```typescript -import { EventPhase, HookRegisteredEvent, HookTriggeredEvent, KernelEventBase, KernelReadyEvent, KernelShutdownEvent, PluginErrorEvent, PluginEventBase, PluginLifecycleEventType, PluginLifecyclePhaseEvent, PluginRegisteredEvent, ServiceRegisteredEvent, ServiceUnregisteredEvent } from '@objectstack/spec/kernel'; -import type { EventPhase, HookRegisteredEvent, HookTriggeredEvent, KernelEventBase, KernelReadyEvent, KernelShutdownEvent, PluginErrorEvent, PluginEventBase, PluginLifecycleEventType, PluginLifecyclePhaseEvent, PluginRegisteredEvent, ServiceRegisteredEvent, ServiceUnregisteredEvent } from '@objectstack/spec/kernel'; - -// Validate data -const result = EventPhase.parse(data); -``` - ---- - -## EventPhase - -Plugin lifecycle phase - -### Allowed Values - -* `init` -* `start` -* `destroy` - - ---- - -## HookRegisteredEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **hookName** | `string` | ✅ | Name of the hook | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | -| **handlerCount** | `integer` | ✅ | Number of handlers registered for this hook | - - ---- - -## HookTriggeredEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **hookName** | `string` | ✅ | Name of the hook | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | -| **args** | `any[]` | ✅ | Arguments passed to the hook handlers | -| **handlerCount** | `integer` | optional | Number of handlers that will handle this event | - - ---- - -## KernelEventBase - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | - - ---- - -## KernelReadyEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | -| **duration** | `number` | optional | Total initialization duration in milliseconds | -| **pluginCount** | `integer` | optional | Number of plugins initialized | - - ---- - -## KernelShutdownEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | -| **reason** | `string` | optional | Reason for kernel shutdown | - - ---- - -## PluginErrorEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginName** | `string` | ✅ | Name of the plugin | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred | -| **error** | `any` | ✅ | Error object | -| **phase** | `Enum<'init' \| 'start' \| 'destroy'>` | ✅ | Lifecycle phase where error occurred | -| **errorMessage** | `string` | optional | Error message | -| **errorStack** | `string` | optional | Error stack trace | - - ---- - -## PluginEventBase - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginName** | `string` | ✅ | Name of the plugin | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred | - - ---- - -## PluginLifecycleEventType - -Plugin lifecycle event type - -### Allowed Values - -* `kernel:ready` -* `kernel:shutdown` -* `kernel:before-init` -* `kernel:after-init` -* `plugin:registered` -* `plugin:before-init` -* `plugin:init` -* `plugin:after-init` -* `plugin:before-start` -* `plugin:started` -* `plugin:after-start` -* `plugin:before-destroy` -* `plugin:destroyed` -* `plugin:after-destroy` -* `plugin:error` -* `service:registered` -* `service:unregistered` -* `hook:registered` -* `hook:triggered` - - ---- - -## PluginLifecyclePhaseEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginName** | `string` | ✅ | Name of the plugin | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred | -| **duration** | `number` | optional | Duration of the lifecycle phase in milliseconds | -| **phase** | `Enum<'init' \| 'start' \| 'destroy'>` | optional | Lifecycle phase | - - ---- - -## PluginRegisteredEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginName** | `string` | ✅ | Name of the plugin | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred | -| **version** | `string` | optional | Plugin version | - - ---- - -## ServiceRegisteredEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **serviceName** | `string` | ✅ | Name of the registered service | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | -| **serviceType** | `string` | optional | Type or interface name of the service | - - ---- - -## ServiceUnregisteredEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **serviceName** | `string` | ✅ | Name of the unregistered service | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds | - - ---- - diff --git a/content/docs/references/kernel/plugin-loading.mdx b/content/docs/references/kernel/plugin-loading.mdx deleted file mode 100644 index a6f0e8a17..000000000 --- a/content/docs/references/kernel/plugin-loading.mdx +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Plugin Loading -description: Plugin Loading protocol schemas ---- - -# Plugin Loading Protocol - -Defines the enhanced plugin loading mechanism for the microkernel architecture. - -Inspired by industry best practices from: - -- Kubernetes CRDs and Operators - -- OSGi Dynamic Module System - -- Eclipse Plugin Framework - -- Webpack Module Federation - -This protocol enables: - -- Lazy loading and code splitting - -- Dynamic imports and parallel initialization - -- Capability-based discovery - -- Hot reload in development - -- Advanced caching strategies - - -**Source:** `packages/spec/src/kernel/plugin-loading.zod.ts` - - -## TypeScript Usage - -```typescript -import { PluginCaching, PluginCodeSplitting, PluginDependencyResolution, PluginDynamicImport, PluginHotReload, PluginInitialization, PluginLoadingConfig, PluginLoadingEvent, PluginLoadingState, PluginLoadingStrategy, PluginPerformanceMonitoring, PluginPreloadConfig, PluginSandboxing } from '@objectstack/spec/kernel'; -import type { PluginCaching, PluginCodeSplitting, PluginDependencyResolution, PluginDynamicImport, PluginHotReload, PluginInitialization, PluginLoadingConfig, PluginLoadingEvent, PluginLoadingState, PluginLoadingStrategy, PluginPerformanceMonitoring, PluginPreloadConfig, PluginSandboxing } from '@objectstack/spec/kernel'; - -// Validate data -const result = PluginCaching.parse(data); -``` - ---- - -## PluginCaching - -Plugin caching configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **storage** | `Enum<'memory' \| 'disk' \| 'indexeddb' \| 'hybrid'>` | optional | | -| **keyStrategy** | `Enum<'version' \| 'hash' \| 'timestamp'>` | optional | | -| **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 | | - - ---- - -## PluginCodeSplitting - -Plugin code splitting configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **strategy** | `Enum<'route' \| 'feature' \| 'size' \| 'custom'>` | optional | | -| **chunkNaming** | `Enum<'hashed' \| 'named' \| 'sequential'>` | optional | | -| **maxChunkSize** | `integer` | optional | Max chunk size in KB | -| **sharedDependencies** | `Object` | optional | | - - ---- - -## PluginDependencyResolution - -Plugin dependency resolution configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `Enum<'strict' \| 'compatible' \| 'latest' \| 'pinned'>` | optional | | -| **peerDependencies** | `Object` | optional | | -| **optionalDependencies** | `Object` | optional | | -| **conflictResolution** | `Enum<'fail' \| 'latest' \| 'oldest' \| 'manual'>` | optional | | -| **circularDependencies** | `Enum<'error' \| 'warn' \| 'allow'>` | optional | | - - ---- - -## PluginDynamicImport - -Plugin dynamic import configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **mode** | `Enum<'async' \| 'sync' \| 'eager' \| 'lazy'>` | optional | | -| **prefetch** | `boolean` | optional | Prefetch module in idle time | -| **preload** | `boolean` | optional | Preload module in parallel with parent | -| **webpackChunkName** | `string` | optional | Custom chunk name for webpack | -| **timeout** | `integer` | optional | Dynamic import timeout (ms) | -| **retry** | `Object` | optional | | - - ---- - -## PluginHotReload - -Plugin hot reload configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **strategy** | `Enum<'full' \| 'partial' \| 'state-preserve'>` | optional | | -| **watchPatterns** | `string[]` | optional | Glob patterns for files to watch | -| **ignorePatterns** | `string[]` | optional | Glob patterns for files to ignore | -| **debounceMs** | `integer` | optional | | -| **preserveState** | `boolean` | optional | | -| **stateSerialization** | `Object` | optional | | -| **hooks** | `Object` | optional | | - - ---- - -## PluginInitialization - -Plugin initialization configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **mode** | `Enum<'sync' \| 'async' \| 'parallel' \| 'sequential'>` | optional | | -| **timeout** | `integer` | optional | | -| **priority** | `integer` | optional | | -| **critical** | `boolean` | optional | If true, kernel bootstrap fails if plugin fails | -| **retry** | `Object` | optional | | -| **healthCheckInterval** | `integer` | optional | Health check interval in ms (0 = disabled) | - - ---- - -## PluginLoadingConfig - -Complete plugin loading configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `Enum<'eager' \| 'lazy' \| 'parallel' \| 'deferred' \| 'on-demand'>` | optional | 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 | - - ---- - -## PluginLoadingEvent - -Plugin loading lifecycle event - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'load-started' \| 'load-completed' \| 'load-failed' \| 'init-started' \| 'init-completed' \| 'init-failed' \| 'preload-started' \| 'preload-completed' \| 'cache-hit' \| 'cache-miss' \| 'hot-reload'>` | ✅ | | -| **pluginId** | `string` | ✅ | | -| **timestamp** | `integer` | ✅ | | -| **durationMs** | `integer` | optional | | -| **metadata** | `Record` | optional | | -| **error** | `Object` | optional | | - - ---- - -## PluginLoadingState - -Plugin loading state - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | | -| **state** | `Enum<'pending' \| 'loading' \| 'loaded' \| 'initializing' \| 'ready' \| 'failed' \| 'reloading'>` | ✅ | | -| **progress** | `number` | optional | | -| **startedAt** | `integer` | optional | | -| **completedAt** | `integer` | optional | | -| **lastError** | `string` | optional | | -| **retryCount** | `integer` | optional | | - - ---- - -## PluginLoadingStrategy - -Plugin loading strategy - -### Allowed Values - -* `eager` -* `lazy` -* `parallel` -* `deferred` -* `on-demand` - - ---- - -## PluginPerformanceMonitoring - -Plugin performance monitoring configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **metrics** | `Enum<'load-time' \| 'init-time' \| 'memory-usage' \| 'cpu-usage' \| 'api-calls' \| 'error-rate' \| 'cache-hit-rate'>[]` | optional | | -| **samplingRate** | `number` | optional | | -| **reportingInterval** | `integer` | optional | | -| **budgets** | `Object` | optional | | -| **onBudgetViolation** | `Enum<'warn' \| 'error' \| 'ignore'>` | optional | | - - ---- - -## PluginPreloadConfig - -Plugin preloading configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **priority** | `integer` | optional | | -| **resources** | `Enum<'metadata' \| 'dependencies' \| 'assets' \| 'code' \| 'services'>[]` | optional | | -| **conditions** | `Object` | optional | | - - ---- - -## PluginSandboxing - -Plugin sandboxing configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **isolationLevel** | `Enum<'none' \| 'process' \| 'vm' \| 'iframe' \| 'web-worker'>` | optional | | -| **allowedCapabilities** | `string[]` | optional | List of allowed capability IDs | -| **resourceQuotas** | `Object` | optional | | -| **permissions** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/kernel/plugin-registry.mdx b/content/docs/references/kernel/plugin-registry.mdx deleted file mode 100644 index 54bc24880..000000000 --- a/content/docs/references/kernel/plugin-registry.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Plugin Registry -description: Plugin Registry protocol schemas ---- - -# Plugin Registry Protocol - -Defines the schema for the plugin discovery and registry system. - -This enables plugins from different vendors to be discovered, validated, - -and composed together in the ObjectStack ecosystem. - - -**Source:** `packages/spec/src/kernel/plugin-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { PluginInstallConfig, PluginQualityMetrics, PluginRegistryEntry, PluginSearchFilters, PluginStatistics, PluginVendor } from '@objectstack/spec/kernel'; -import type { PluginInstallConfig, PluginQualityMetrics, PluginRegistryEntry, PluginSearchFilters, PluginStatistics, PluginVendor } from '@objectstack/spec/kernel'; - -// Validate data -const result = PluginInstallConfig.parse(data); -``` - ---- - -## PluginInstallConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | | -| **version** | `string` | optional | Defaults to latest | -| **config** | `Record` | optional | | -| **autoUpdate** | `boolean` | optional | | -| **options** | `Object` | optional | | - - ---- - -## PluginQualityMetrics - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **testCoverage** | `number` | optional | | -| **documentationScore** | `number` | optional | | -| **codeQuality** | `number` | optional | | -| **securityScan** | `Object` | optional | | -| **conformanceTests** | `Object[]` | optional | | - - ---- - -## PluginRegistryEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Plugin identifier (reverse domain notation) | -| **version** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **description** | `string` | optional | | -| **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 | | -| **license** | `string` | optional | SPDX license identifier | -| **pricing** | `Object` | optional | | -| **publishedAt** | `string` | optional | | -| **updatedAt** | `string` | optional | | -| **deprecated** | `boolean` | optional | | -| **deprecationMessage** | `string` | optional | | -| **replacedBy** | `string` | optional | Plugin ID that replaces this one | -| **flags** | `Object` | optional | | - - ---- - -## PluginSearchFilters - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **query** | `string` | optional | | -| **category** | `string[]` | optional | | -| **tags** | `string[]` | optional | | -| **trustLevel** | `Enum<'official' \| 'verified' \| 'community' \| 'unverified'>[]` | optional | | -| **implementsProtocols** | `string[]` | optional | | -| **pricingModel** | `Enum<'free' \| 'freemium' \| 'paid' \| 'enterprise'>[]` | optional | | -| **minRating** | `number` | optional | | -| **sortBy** | `Enum<'relevance' \| 'downloads' \| 'rating' \| 'updated' \| 'name'>` | optional | | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **page** | `integer` | optional | | -| **limit** | `integer` | optional | | - - ---- - -## PluginStatistics - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **downloads** | `integer` | optional | | -| **downloadsLastMonth** | `integer` | optional | | -| **activeInstallations** | `integer` | optional | | -| **ratings** | `Object` | optional | | -| **stars** | `integer` | optional | | -| **dependents** | `integer` | optional | | - - ---- - -## PluginVendor - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Vendor identifier (reverse domain) | -| **name** | `string` | ✅ | | -| **website** | `string` | optional | | -| **email** | `string` | optional | | -| **verified** | `boolean` | optional | Whether vendor is verified by ObjectStack | -| **trustLevel** | `Enum<'official' \| 'verified' \| 'community' \| 'unverified'>` | optional | | - - ---- - diff --git a/content/docs/references/kernel/plugin-security-advanced.mdx b/content/docs/references/kernel/plugin-security-advanced.mdx deleted file mode 100644 index faec1483a..000000000 --- a/content/docs/references/kernel/plugin-security-advanced.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Plugin Security Advanced -description: Plugin Security Advanced protocol schemas ---- - - -**Source:** `packages/spec/src/kernel/plugin-security.zod.ts` - - -## TypeScript Usage - -```typescript -import { SecurityPolicy, SecurityScanResult, SecurityVulnerability } from '@objectstack/spec/kernel'; -import type { SecurityPolicy, SecurityScanResult, SecurityVulnerability } from '@objectstack/spec/kernel'; - -// Validate data -const result = SecurityPolicy.parse(data); -``` - ---- - -## SecurityPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **autoScan** | `Object` | ✅ | | -| **thresholds** | `Object` | ✅ | | -| **allowedLicenses** | `string[]` | optional | | -| **prohibitedLicenses** | `string[]` | optional | | -| **codeSigning** | `Object` | optional | | -| **sandbox** | `Object` | optional | | - - ---- - -## SecurityScanResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **scanId** | `string` | ✅ | | -| **plugin** | `Object` | ✅ | | -| **scannedAt** | `string` | ✅ | | -| **scanner** | `Object` | ✅ | | -| **status** | `Enum<'passed' \| 'failed' \| 'warning'>` | ✅ | | -| **vulnerabilities** | `Object[]` | ✅ | | -| **summary** | `Object` | ✅ | | -| **licenseIssues** | `Object[]` | optional | | -| **codeQuality** | `Object` | optional | | -| **nextScanAt** | `string` | optional | | - - ---- - -## SecurityVulnerability - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **cve** | `string` | optional | CVE identifier | -| **id** | `string` | ✅ | Vulnerability ID | -| **title** | `string` | ✅ | | -| **description** | `string` | ✅ | | -| **severity** | `Enum<'critical' \| 'high' \| 'medium' \| 'low' \| 'info'>` | ✅ | | -| **cvss** | `number` | optional | | -| **package** | `Object` | ✅ | | -| **vulnerableVersions** | `string` | ✅ | Semver range of vulnerable versions | -| **patchedVersions** | `string` | optional | Semver range of patched versions | -| **references** | `Object[]` | optional | | -| **cwe** | `string[]` | optional | | -| **publishedAt** | `string` | optional | | -| **mitigation** | `string` | optional | | - - ---- - diff --git a/content/docs/references/kernel/plugin-security.mdx b/content/docs/references/kernel/plugin-security.mdx deleted file mode 100644 index d75ef460f..000000000 --- a/content/docs/references/kernel/plugin-security.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Plugin Security -description: Plugin Security protocol schemas ---- - -# Plugin Security & Dependency Resolution Protocol - -Provides comprehensive security scanning, vulnerability management, - -and dependency resolution for the ObjectStack plugin ecosystem. - -Features: - -- CVE/vulnerability scanning - -- Dependency graph resolution - -- Semantic version conflict detection - -- Supply chain security - -- Plugin sandboxing policies - -- Trust and verification workflows - - -**Source:** `packages/spec/src/kernel/plugin-security.zod.ts` - - -## TypeScript Usage - -```typescript -import { DependencyGraph, DependencyGraphNode, PackageDependency, PluginProvenance, PluginTrustScore, SBOM, SBOMEntry, VulnerabilitySeverity } from '@objectstack/spec/kernel'; -import type { DependencyGraph, DependencyGraphNode, PackageDependency, PluginProvenance, PluginTrustScore, SBOM, SBOMEntry, VulnerabilitySeverity } from '@objectstack/spec/kernel'; - -// Validate data -const result = DependencyGraph.parse(data); -``` - ---- - -## DependencyGraph - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **root** | `Object` | ✅ | | -| **nodes** | `Object[]` | ✅ | | -| **edges** | `Object[]` | ✅ | | -| **stats** | `Object` | ✅ | | - - ---- - -## DependencyGraphNode - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **version** | `string` | ✅ | | -| **dependencies** | `Object[]` | optional | | -| **depth** | `integer` | ✅ | | -| **isDirect** | `boolean` | ✅ | | -| **metadata** | `Object` | optional | | - - ---- - -## PackageDependency - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **versionConstraint** | `string` | ✅ | Semver range (e.g., `^1.0.0`, `>=2.0.0 <3.0.0`) | -| **type** | `Enum<'required' \| 'optional' \| 'peer' \| 'dev'>` | optional | | -| **resolvedVersion** | `string` | optional | | - - ---- - -## PluginProvenance - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | | -| **version** | `string` | ✅ | | -| **build** | `Object` | ✅ | | -| **artifacts** | `Object[]` | ✅ | | -| **signatures** | `Object[]` | optional | | -| **attestations** | `Object[]` | optional | | - - ---- - -## PluginTrustScore - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pluginId** | `string` | ✅ | | -| **score** | `number` | ✅ | | -| **components** | `Object` | ✅ | | -| **level** | `Enum<'verified' \| 'trusted' \| 'neutral' \| 'untrusted' \| 'blocked'>` | ✅ | | -| **badges** | `Enum<'official' \| 'verified-vendor' \| 'security-scanned' \| 'code-signed' \| 'open-source' \| 'popular'>[]` | optional | | -| **updatedAt** | `string` | ✅ | | - - ---- - -## SBOM - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **format** | `Enum<'spdx' \| 'cyclonedx'>` | optional | | -| **version** | `string` | ✅ | | -| **plugin** | `Object` | ✅ | | -| **components** | `Object[]` | ✅ | | -| **generatedAt** | `string` | ✅ | | -| **generator** | `Object` | optional | | - - ---- - -## SBOMEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **version** | `string` | ✅ | | -| **purl** | `string` | optional | Package URL identifier | -| **license** | `string` | optional | | -| **hashes** | `Object` | optional | | -| **supplier** | `Object` | optional | | -| **externalRefs** | `Object[]` | optional | | - - ---- - -## VulnerabilitySeverity - -### Allowed Values - -* `critical` -* `high` -* `medium` -* `low` -* `info` - - ---- - diff --git a/content/docs/references/kernel/plugin-structure.mdx b/content/docs/references/kernel/plugin-structure.mdx deleted file mode 100644 index e75ccd8a0..000000000 --- a/content/docs/references/kernel/plugin-structure.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Plugin Structure -description: Plugin Structure protocol schemas ---- - -ObjectStack Plugin Structure Standards (OPS) - -Formal Zod definitions for the Plugin Directory Structure and File Naming conventions. - -This can be used by the CLI or IDE extensions to lint project structure. - -@see PLUGIN_STANDARDS.md - - -**Source:** `packages/spec/src/kernel/plugin-structure.zod.ts` - - -## TypeScript Usage - -```typescript -import { OpsDomainModule, OpsFilePath, OpsPluginStructure } from '@objectstack/spec/kernel'; -import type { OpsDomainModule, OpsFilePath, OpsPluginStructure } from '@objectstack/spec/kernel'; - -// Validate data -const result = OpsDomainModule.parse(data); -``` - ---- - -## OpsDomainModule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **files** | `string[]` | ✅ | | - - ---- - -## OpsFilePath - - ---- - -## OpsPluginStructure - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **root** | `string` | ✅ | | -| **files** | `string[]` | ✅ | List of all file paths relative to root | - - ---- - diff --git a/content/docs/references/kernel/plugin-validator.mdx b/content/docs/references/kernel/plugin-validator.mdx deleted file mode 100644 index 6568499ee..000000000 --- a/content/docs/references/kernel/plugin-validator.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Plugin Validator -description: Plugin Validator protocol schemas ---- - -Plugin Validator Protocol - -Zod schemas for plugin validation data structures. - -These schemas align with the IPluginValidator contract interface. - -Following ObjectStack "Zod First" principle - all data structures - -must have Zod schemas for runtime validation and JSON Schema generation. - - -**Source:** `packages/spec/src/kernel/plugin-validator.zod.ts` - - -## TypeScript Usage - -```typescript -import { PluginMetadata, ValidationError, ValidationResult, ValidationWarning } from '@objectstack/spec/kernel'; -import type { PluginMetadata, ValidationError, ValidationResult, ValidationWarning } from '@objectstack/spec/kernel'; - -// Validate data -const result = PluginMetadata.parse(data); -``` - ---- - -## PluginMetadata - -Plugin metadata for validation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique plugin identifier | -| **version** | `string` | optional | Semantic version (e.g., 1.0.0) | -| **dependencies** | `string[]` | optional | Array of plugin names this plugin depends on | -| **signature** | `string` | optional | Cryptographic signature for plugin verification | - - ---- - -## ValidationError - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name that failed validation | -| **message** | `string` | ✅ | Human-readable error message | -| **code** | `string` | optional | Machine-readable error code | - - ---- - -## ValidationResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **valid** | `boolean` | ✅ | Whether the plugin passed validation | -| **errors** | `Object[]` | optional | Validation errors | -| **warnings** | `Object[]` | optional | Validation warnings | - - ---- - -## ValidationWarning - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name with warning | -| **message** | `string` | ✅ | Human-readable warning message | -| **code** | `string` | optional | Machine-readable warning code | - - ---- - diff --git a/content/docs/references/kernel/plugin-versioning.mdx b/content/docs/references/kernel/plugin-versioning.mdx deleted file mode 100644 index b905e0734..000000000 --- a/content/docs/references/kernel/plugin-versioning.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Plugin Versioning -description: Plugin Versioning protocol schemas ---- - - -**Source:** `packages/spec/src/kernel/plugin-versioning.zod.ts` - - -## TypeScript Usage - -```typescript -import { DependencyConflict, DependencyResolutionResult } from '@objectstack/spec/kernel'; -import type { DependencyConflict, DependencyResolutionResult } from '@objectstack/spec/kernel'; - -// Validate data -const result = DependencyConflict.parse(data); -``` - ---- - -## DependencyConflict - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **package** | `string` | ✅ | | -| **conflicts** | `Object[]` | ✅ | | -| **resolution** | `Object` | optional | | -| **severity** | `Enum<'error' \| 'warning' \| 'info'>` | ✅ | | - - ---- - -## DependencyResolutionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **status** | `Enum<'success' \| 'conflict' \| 'error'>` | ✅ | | -| **graph** | `Object` | optional | | -| **conflicts** | `Object[]` | optional | | -| **errors** | `Object[]` | optional | | -| **installOrder** | `string[]` | optional | | -| **resolvedIn** | `integer` | optional | | - - ---- - diff --git a/content/docs/references/kernel/plugin.mdx b/content/docs/references/kernel/plugin.mdx deleted file mode 100644 index 86378db47..000000000 --- a/content/docs/references/kernel/plugin.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Plugin -description: Plugin protocol schemas ---- - -Shared Plugin Types - -These are the specialized plugin types common between Manifest (Package) and Plugin (Runtime). - - -**Source:** `packages/spec/src/kernel/plugin.zod.ts` - - -## TypeScript Usage - -```typescript -import { Plugin, PluginContext, PluginLifecycle } from '@objectstack/spec/kernel'; -import type { Plugin, PluginContext, PluginLifecycle } from '@objectstack/spec/kernel'; - -// Validate data -const result = Plugin.parse(data); -``` - ---- - -## Plugin - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **onInstall** | `any` | optional | | -| **onEnable** | `any` | optional | | -| **onDisable** | `any` | optional | | -| **onUninstall** | `any` | optional | | -| **onUpgrade** | `any` | optional | | -| **id** | `string` | optional | Unique Plugin ID (e.g. com.example.crm) | -| **type** | `Enum<'standard' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql'>` | optional | Plugin Type categorization for runtime behavior | -| **staticPath** | `string` | optional | Absolute path to static assets (Required for type="ui-plugin") | -| **slug** | `string` | optional | URL path segment (Required for type="ui-plugin") | -| **default** | `boolean` | optional | Serve at root path (Only one "ui-plugin" can be default) | -| **version** | `string` | optional | Semantic Version | -| **description** | `string` | optional | | -| **author** | `string` | optional | | -| **homepage** | `string` | optional | | - - ---- - -## PluginContext - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **ql** | `Record` | ✅ | ObjectQL Engine Interface | -| **os** | `Record` | ✅ | ObjectStack Kernel Interface | -| **logger** | `Record` | ✅ | Logger Interface | -| **storage** | `Record` | ✅ | Storage Interface | -| **i18n** | `Record` | ✅ | Internationalization Interface | -| **metadata** | `Record` | ✅ | | -| **events** | `Record` | ✅ | | -| **app** | `Record` | ✅ | App Framework Interface | -| **drivers** | `Record` | ✅ | Driver Registry | - - ---- - -## PluginLifecycle - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **onInstall** | `any` | optional | | -| **onEnable** | `any` | optional | | -| **onDisable** | `any` | optional | | -| **onUninstall** | `any` | optional | | -| **onUpgrade** | `any` | optional | | - - ---- - diff --git a/content/docs/references/kernel/service-registry.mdx b/content/docs/references/kernel/service-registry.mdx deleted file mode 100644 index 64a103d67..000000000 --- a/content/docs/references/kernel/service-registry.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Service Registry -description: Service Registry protocol schemas ---- - -Service Registry Protocol - -Zod schemas for service registry data structures. - -These schemas align with the IServiceRegistry contract interface. - -Following ObjectStack "Zod First" principle - all data structures - -must have Zod schemas for runtime validation and JSON Schema generation. - -Note: IServiceRegistry itself is a runtime interface (methods only), - -so it correctly remains a TypeScript interface. This file contains - -schemas for configuration and metadata related to service registry. - - -**Source:** `packages/spec/src/kernel/service-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { ScopeConfig, ScopeInfo, ServiceFactoryRegistration, ServiceMetadata, ServiceRegistryConfig, ServiceScopeType } from '@objectstack/spec/kernel'; -import type { ScopeConfig, ScopeInfo, ServiceFactoryRegistration, ServiceMetadata, ServiceRegistryConfig, ServiceScopeType } from '@objectstack/spec/kernel'; - -// Validate data -const result = ScopeConfig.parse(data); -``` - ---- - -## ScopeConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **scopeType** | `string` | ✅ | Type of scope | -| **scopeId** | `string` | optional | Unique scope identifier | -| **metadata** | `Record` | optional | Scope-specific context metadata | - - ---- - -## ScopeInfo - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **scopeId** | `string` | ✅ | Unique scope identifier | -| **scopeType** | `string` | ✅ | Type of scope | -| **createdAt** | `integer` | ✅ | Unix timestamp in milliseconds when scope was created | -| **serviceCount** | `integer` | optional | Number of services registered in this scope | -| **metadata** | `Record` | optional | Scope-specific context metadata | - - ---- - -## ServiceFactoryRegistration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique service name identifier | -| **scope** | `Enum<'singleton' \| 'transient' \| 'scoped'>` | optional | Service scope type | -| **factoryType** | `Enum<'sync' \| 'async'>` | optional | Whether factory is synchronous or asynchronous | -| **singleton** | `boolean` | optional | Whether to cache the factory result (singleton pattern) | - - ---- - -## ServiceMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique service name identifier | -| **scope** | `Enum<'singleton' \| 'transient' \| 'scoped'>` | optional | Service scope type | -| **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 | - - ---- - -## ServiceRegistryConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strictMode** | `boolean` | optional | Throw errors on invalid operations (duplicate registration, service not found, etc.) | -| **allowOverwrite** | `boolean` | optional | Allow overwriting existing service registrations | -| **enableLogging** | `boolean` | optional | Enable logging for service registration and retrieval | -| **scopeTypes** | `string[]` | optional | Supported scope types | -| **maxServices** | `integer` | optional | Maximum number of services that can be registered | - - ---- - -## ServiceScopeType - -Service scope type - -### Allowed Values - -* `singleton` -* `transient` -* `scoped` - - ---- - diff --git a/content/docs/references/kernel/startup-orchestrator.mdx b/content/docs/references/kernel/startup-orchestrator.mdx deleted file mode 100644 index aa00df512..000000000 --- a/content/docs/references/kernel/startup-orchestrator.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Startup Orchestrator -description: Startup Orchestrator protocol schemas ---- - -Startup Orchestrator Protocol - -Zod schemas for plugin startup orchestration data structures. - -These schemas align with the IStartupOrchestrator contract interface. - -Following ObjectStack "Zod First" principle - all data structures - -must have Zod schemas for runtime validation and JSON Schema generation. - - -**Source:** `packages/spec/src/kernel/startup-orchestrator.zod.ts` - - -## TypeScript Usage - -```typescript -import { HealthStatus, PluginStartupResult, StartupOptions, StartupOrchestrationResult } from '@objectstack/spec/kernel'; -import type { HealthStatus, PluginStartupResult, StartupOptions, StartupOrchestrationResult } from '@objectstack/spec/kernel'; - -// Validate data -const result = HealthStatus.parse(data); -``` - ---- - -## HealthStatus - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **healthy** | `boolean` | ✅ | Whether the plugin is healthy | -| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when health check was performed | -| **details** | `Record` | optional | Optional plugin-specific health details | -| **message** | `string` | optional | Error message if plugin is unhealthy | - - ---- - -## PluginStartupResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **plugin** | `Record` | ✅ | Plugin metadata | -| **success** | `boolean` | ✅ | Whether the plugin started successfully | -| **duration** | `number` | ✅ | Time taken to start the plugin in milliseconds | -| **error** | `any` | optional | Error object if startup failed | -| **health** | `Object` | optional | Health status after startup if health check was enabled | - - ---- - -## StartupOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timeout** | `integer` | optional | Maximum time in milliseconds to wait for each plugin to start | -| **rollbackOnFailure** | `boolean` | optional | Whether to rollback already-started plugins if any plugin fails | -| **healthCheck** | `boolean` | optional | Whether to run health checks after plugin startup | -| **parallel** | `boolean` | optional | Whether to start plugins in parallel when dependencies allow | -| **context** | `any` | optional | Custom context object to pass to plugin lifecycle methods | - - ---- - -## StartupOrchestrationResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **results** | `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/meta.json b/content/docs/references/meta.json index 275154ecf..4ff9e75c3 100644 --- a/content/docs/references/meta.json +++ b/content/docs/references/meta.json @@ -11,6 +11,7 @@ "qa", "security", "shared", + "studio", "system", "ui", "quick-reference" diff --git a/content/docs/references/qa/meta.json b/content/docs/references/qa/meta.json deleted file mode 100644 index f546c4824..000000000 --- a/content/docs/references/qa/meta.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "title": "Qa Protocol", - "pages": [ - "testing" - ] -} \ No newline at end of file diff --git a/content/docs/references/qa/testing.mdx b/content/docs/references/qa/testing.mdx deleted file mode 100644 index c5d4d99f0..000000000 --- a/content/docs/references/qa/testing.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Testing -description: Testing protocol schemas ---- - - -**Source:** `packages/spec/src/qa/testing.zod.ts` - - -## TypeScript Usage - -```typescript -import { TestAction, TestActionType, TestAssertion, TestAssertionType, TestContext, TestScenario, TestStep, TestSuite } from '@objectstack/spec/qa'; -import type { TestAction, TestActionType, TestAssertion, TestAssertionType, TestContext, TestScenario, TestStep, TestSuite } from '@objectstack/spec/qa'; - -// Validate data -const result = TestAction.parse(data); -``` - ---- - -## TestAction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'create_record' \| 'update_record' \| 'delete_record' \| 'read_record' \| 'query_records' \| 'api_call' \| 'run_script' \| 'wait'>` | ✅ | | -| **target** | `string` | ✅ | Target Object, API Endpoint, or Function Name | -| **payload** | `Record` | optional | Data to send or use | -| **user** | `string` | optional | Run as specific user/role | - - ---- - -## TestActionType - -### Allowed Values - -* `create_record` -* `update_record` -* `delete_record` -* `read_record` -* `query_records` -* `api_call` -* `run_script` -* `wait` - - ---- - -## TestAssertion - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field path in the result to check (e.g. "body.data.0.status") | -| **operator** | `Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'is_null' \| 'not_null' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'error'>` | ✅ | | -| **expectedValue** | `any` | optional | | - - ---- - -## TestAssertionType - -### Allowed Values - -* `equals` -* `not_equals` -* `contains` -* `not_contains` -* `is_null` -* `not_null` -* `gt` -* `gte` -* `lt` -* `lte` -* `error` - - ---- - -## TestContext - -Initial context or variables for the test - - ---- - -## TestScenario - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **description** | `string` | optional | | -| **tags** | `string[]` | optional | | -| **setup** | `Object[]` | optional | Steps to run before main test | -| **steps** | `Object[]` | ✅ | Main test sequence | -| **teardown** | `Object[]` | optional | Steps to cleanup | -| **requires** | `Object` | optional | | - - ---- - -## TestStep - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **description** | `string` | optional | | -| **action** | `Object` | ✅ | | -| **assertions** | `Object[]` | optional | | -| **capture** | `Record` | optional | Map result fields to context variables: `{ "newId": "body._id" }` | - - ---- - -## TestSuite - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **scenarios** | `Object[]` | ✅ | | - - ---- - diff --git a/content/docs/references/security/meta.json b/content/docs/references/security/meta.json deleted file mode 100644 index e5d72448c..000000000 --- a/content/docs/references/security/meta.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "title": "Security Protocol", - "pages": [ - "permission", - "policy", - "rls", - "sharing", - "territory" - ] -} \ No newline at end of file diff --git a/content/docs/references/security/permission.mdx b/content/docs/references/security/permission.mdx deleted file mode 100644 index 503bbe276..000000000 --- a/content/docs/references/security/permission.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Permission -description: Permission protocol schemas ---- - -Entity (Object) Level Permissions - -Defines CRUD + VAMA (View All / Modify All) + Lifecycle access. - -Refined with enterprise data lifecycle controls: - -- Transfer (Ownership change) - -- Restore (Soft delete recovery) - -- Purge (Hard delete / Compliance) - - -**Source:** `packages/spec/src/security/permission.zod.ts` - - -## TypeScript Usage - -```typescript -import { FieldPermission, ObjectPermission, PermissionSet } from '@objectstack/spec/security'; -import type { FieldPermission, ObjectPermission, PermissionSet } from '@objectstack/spec/security'; - -// Validate data -const result = FieldPermission.parse(data); -``` - ---- - -## FieldPermission - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **readable** | `boolean` | optional | Field read access | -| **editable** | `boolean` | optional | Field edit access | - - ---- - -## ObjectPermission - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **allowCreate** | `boolean` | optional | Create permission | -| **allowRead** | `boolean` | optional | Read permission | -| **allowEdit** | `boolean` | optional | Edit permission | -| **allowDelete** | `boolean` | optional | Delete permission | -| **allowTransfer** | `boolean` | optional | Change record ownership | -| **allowRestore** | `boolean` | optional | Restore from trash (Undelete) | -| **allowPurge** | `boolean` | optional | Permanently delete (Hard Delete/GDPR) | -| **viewAllRecords** | `boolean` | optional | View All Data (Bypass Sharing) | -| **modifyAllRecords** | `boolean` | optional | Modify All Data (Bypass Sharing) | - - ---- - -## PermissionSet - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Permission set unique name (lowercase snake_case) | -| **label** | `string` | optional | Display label | -| **isProfile** | `boolean` | optional | Whether this is a user profile | -| **objects** | `Record` | ✅ | Entity permissions | -| **fields** | `Record` | optional | Field level security | -| **systemPermissions** | `string[]` | optional | System level capabilities | -| **rowLevelSecurity** | `Object[]` | optional | Row-level security policies (see rls.zod.ts for full spec) | -| **contextVariables** | `Record` | optional | Context variables for RLS evaluation | - - ---- - diff --git a/content/docs/references/security/policy.mdx b/content/docs/references/security/policy.mdx deleted file mode 100644 index c680ff295..000000000 --- a/content/docs/references/security/policy.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Policy -description: Policy protocol schemas ---- - -Password Complexity Policy - - -**Source:** `packages/spec/src/security/policy.zod.ts` - - -## TypeScript Usage - -```typescript -import { AuditPolicy, NetworkPolicy, PasswordPolicy, Policy, SessionPolicy } from '@objectstack/spec/security'; -import type { AuditPolicy, NetworkPolicy, PasswordPolicy, Policy, SessionPolicy } from '@objectstack/spec/security'; - -// Validate data -const result = AuditPolicy.parse(data); -``` - ---- - -## AuditPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **logRetentionDays** | `number` | optional | | -| **sensitiveFields** | `string[]` | ✅ | Fields to redact in logs (e.g. password, ssn) | -| **captureRead** | `boolean` | optional | Log read access (High volume!) | - - ---- - -## NetworkPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trustedRanges** | `string[]` | ✅ | CIDR ranges allowed to access (e.g. 10.0.0.0/8) | -| **blockUnknown** | `boolean` | optional | Block all IPs not in trusted ranges | -| **vpnRequired** | `boolean` | optional | | - - ---- - -## PasswordPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **minLength** | `number` | optional | | -| **requireUppercase** | `boolean` | optional | | -| **requireLowercase** | `boolean` | optional | | -| **requireNumbers** | `boolean` | optional | | -| **requireSymbols** | `boolean` | optional | | -| **expirationDays** | `number` | optional | Force password change every X days | -| **historyCount** | `number` | optional | Prevent reusing last X passwords | - - ---- - -## Policy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Policy Name | -| **password** | `Object` | optional | | -| **network** | `Object` | optional | | -| **session** | `Object` | optional | | -| **audit** | `Object` | optional | | -| **isDefault** | `boolean` | optional | Apply to all users by default | -| **assignedProfiles** | `string[]` | optional | Apply to specific profiles | - - ---- - -## SessionPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **idleTimeout** | `number` | optional | Minutes before idle session logout | -| **absoluteTimeout** | `number` | optional | Max session duration (minutes) | -| **forceMfa** | `boolean` | optional | Require 2FA for all users | - - ---- - diff --git a/content/docs/references/security/rls.mdx b/content/docs/references/security/rls.mdx deleted file mode 100644 index 6fab77ef2..000000000 --- a/content/docs/references/security/rls.mdx +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Rls -description: Rls protocol schemas ---- - -# Row-Level Security (RLS) Protocol - -Implements fine-grained record-level access control inspired by PostgreSQL RLS - -and Salesforce Criteria-Based Sharing Rules. - -## Overview - -Row-Level Security (RLS) allows you to control which rows users can access - -in database tables based on their identity and role. Unlike object-level - -permissions (CRUD), RLS provides record-level filtering. - -## Use Cases - -1. **Multi-Tenant Data Isolation** - -- Users only see records from their organization - -- `using: "tenant_id = current_user.tenant_id"` - -2. **Ownership-Based Access** - -- Users only see records they own - -- `using: "owner_id = current_user.id"` - -3. **Department-Based Access** - -- Users only see records from their department - -- `using: "department = current_user.department"` - -4. **Regional Access Control** - -- Sales reps only see accounts in their territory - -- `using: "region IN (current_user.assigned_regions)"` - -5. **Time-Based Access** - -- Users can only access active records - -- `using: "status = 'active' AND expiry_date > NOW()"` - -## PostgreSQL RLS Comparison - -PostgreSQL RLS Example: - -```sql - -CREATE POLICY tenant_isolation ON accounts - -FOR SELECT - -USING (tenant_id = current_setting('app.current_tenant_id')::uuid); - -CREATE POLICY account_insert ON accounts - -FOR INSERT - -WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::uuid); - -``` - -ObjectStack RLS Equivalent: - -```typescript - -{ - -name: 'tenant_isolation', - -object: 'account', - -operation: 'select', - -using: 'tenant_id = current_user.tenant_id' - -} - -``` - -## Salesforce Sharing Rules Comparison - -Salesforce uses "Sharing Rules" and "Role Hierarchy" for record-level access. - -ObjectStack RLS provides similar functionality with more flexibility. - -Salesforce: - -- Criteria-Based Sharing: Share records matching criteria with users/roles - -- Owner-Based Sharing: Share records based on owner's role - -- Manual Sharing: Individual record sharing - -ObjectStack RLS: - -- More flexible formula-based conditions - -- Direct SQL-like syntax - -- Supports complex logic with AND/OR/NOT - -## Best Practices - -1. **Always Define SELECT Policy**: Control what users can view - -2. **Define INSERT/UPDATE CHECK Policies**: Prevent data leakage - -3. **Use Role-Based Policies**: Apply different rules to different roles - -4. **Test Thoroughly**: RLS can have complex interactions - -5. **Monitor Performance**: Complex RLS policies can impact query performance - -## Security Considerations - -1. **Defense in Depth**: RLS is one layer; use with object permissions - -2. **Default Deny**: If no policy matches, access is denied - -3. **Policy Precedence**: More permissive policy wins (OR logic) - -4. **Context Variables**: Ensure current_user context is always set - -@see https://www.postgresql.org/docs/current/ddl-rowsecurity.html - -@see https://help.salesforce.com/s/articleView?id=sf.security_sharing_rules.htm - - -**Source:** `packages/spec/src/security/rls.zod.ts` - - -## TypeScript Usage - -```typescript -import { RLSConfig, RLSEvaluationResult, RLSOperation, RLSUserContext, RowLevelSecurityPolicy } from '@objectstack/spec/security'; -import type { RLSConfig, RLSEvaluationResult, RLSOperation, RLSUserContext, RowLevelSecurityPolicy } from '@objectstack/spec/security'; - -// Validate data -const result = RLSConfig.parse(data); -``` - ---- - -## RLSConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable RLS enforcement globally | -| **defaultPolicy** | `Enum<'deny' \| 'allow'>` | optional | Default action when no policies match | -| **allowSuperuserBypass** | `boolean` | optional | Allow superusers to bypass RLS | -| **bypassRoles** | `string[]` | optional | Roles that bypass RLS (see all data) | -| **logEvaluations** | `boolean` | optional | Log RLS policy evaluations for debugging | -| **cacheResults** | `boolean` | optional | Cache RLS evaluation results | -| **cacheTtlSeconds** | `integer` | optional | Cache TTL in seconds | -| **prefetchUserContext** | `boolean` | optional | Pre-fetch user context for performance | - - ---- - -## RLSEvaluationResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **policyName** | `string` | ✅ | Policy name | -| **granted** | `boolean` | ✅ | Whether access was granted | -| **durationMs** | `number` | optional | Evaluation duration in milliseconds | -| **error** | `string` | optional | Error message if evaluation failed | -| **usingResult** | `boolean` | optional | USING clause evaluation result | -| **checkResult** | `boolean` | optional | CHECK clause evaluation result | - - ---- - -## RLSOperation - -### Allowed Values - -* `select` -* `insert` -* `update` -* `delete` -* `all` - - ---- - -## RLSUserContext - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | User ID | -| **email** | `string` | optional | User email | -| **tenantId** | `string` | optional | Tenant/Organization ID | -| **role** | `string \| string[]` | optional | User role(s) | -| **department** | `string` | optional | User department | -| **attributes** | `Record` | optional | Additional custom user attributes | - - ---- - -## RowLevelSecurityPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Policy unique identifier (snake_case) | -| **label** | `string` | optional | Human-readable policy label | -| **description** | `string` | optional | Policy description and business justification | -| **object** | `string` | ✅ | Target object name | -| **operation** | `Enum<'select' \| 'insert' \| 'update' \| 'delete' \| 'all'>` | ✅ | Database operation this policy applies to | -| **using** | `string` | optional | Filter condition for SELECT/UPDATE/DELETE (PostgreSQL SQL WHERE clause syntax with parameterized context variables). Optional for INSERT-only policies. | -| **check** | `string` | optional | Validation condition for INSERT/UPDATE (defaults to USING clause if not specified - enforced at application level) | -| **roles** | `string[]` | optional | Roles this policy applies to (omit for all roles) | -| **enabled** | `boolean` | optional | Whether this policy is active | -| **priority** | `integer` | optional | Policy evaluation priority (higher = evaluated first) | -| **tags** | `string[]` | optional | Policy categorization tags | - - ---- - diff --git a/content/docs/references/security/sharing.mdx b/content/docs/references/security/sharing.mdx deleted file mode 100644 index 060c002b8..000000000 --- a/content/docs/references/security/sharing.mdx +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Sharing -description: Sharing protocol schemas ---- - -Organization-Wide Defaults (OWD) - -The baseline security posture for an object. - - -**Source:** `packages/spec/src/security/sharing.zod.ts` - - -## TypeScript Usage - -```typescript -import { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security'; -import type { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security'; - -// Validate data -const result = CriteriaSharingRule.parse(data); -``` - ---- - -## CriteriaSharingRule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **description** | `string` | optional | Administrative notes | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | -| **sharedWith** | `Object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **condition** | `string` | ✅ | Formula condition (e.g. "department = 'Sales'") | - - ---- - -## OWDModel - -### Allowed Values - -* `private` -* `public_read` -* `public_read_write` -* `controlled_by_parent` - - ---- - -## OwnerSharingRule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **description** | `string` | optional | Administrative notes | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | -| **sharedWith** | `Object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **ownedBy** | `Object` | ✅ | Source group/role whose records are being shared | - - ---- - -## ShareRecipientType - -### Allowed Values - -* `user` -* `group` -* `role` -* `role_and_subordinates` -* `guest` - - ---- - -## SharingLevel - -### Allowed Values - -* `read` -* `edit` -* `full` - - ---- - -## SharingRule - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `criteria` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **description** | `string` | optional | Administrative notes | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | -| **sharedWith** | `Object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **condition** | `string` | ✅ | Formula condition (e.g. "department = 'Sales'") | - ---- - -#### Option 2 - -**Type:** `owner` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique rule name (snake_case) | -| **label** | `string` | optional | Human-readable label | -| **description** | `string` | optional | Administrative notes | -| **object** | `string` | ✅ | Target Object Name | -| **active** | `boolean` | optional | | -| **accessLevel** | `Enum<'read' \| 'edit' \| 'full'>` | optional | | -| **sharedWith** | `Object` | ✅ | The recipient of the shared access | -| **type** | `string` | ✅ | | -| **ownedBy** | `Object` | ✅ | Source group/role whose records are being shared | - ---- - - ---- - -## SharingRuleType - -### Allowed Values - -* `owner` -* `criteria` - - ---- - diff --git a/content/docs/references/security/territory.mdx b/content/docs/references/security/territory.mdx deleted file mode 100644 index 8009e7703..000000000 --- a/content/docs/references/security/territory.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Territory -description: Territory protocol schemas ---- - -Territory Management Protocol - -Defines a matrix reporting structure that exists parallel to the Role Hierarchy. - -USE CASE: - -- Enterprise Sales Teams (Geo-based: "EMEA", "APAC") - -- Industry Verticals (Industry-based: "Healthcare", "Financial") - -- Strategic Accounts (Account-based: "Strategic Accounts") - -DIFFERENCE FROM ROLE: - -- Role: Hierarchy of PEOPLE (Who reports to whom). Stable. HR-driven. - -- Territory: Hierarchy of ACCOUNTS/REVENUE (Who owns which market). Flexible. Sales-driven. - -- One User can be assigned to MANY Territories (Matrix). - -- One User has only ONE Role (Tree). - - -**Source:** `packages/spec/src/security/territory.zod.ts` - - -## TypeScript Usage - -```typescript -import { Territory, TerritoryModel, TerritoryType } from '@objectstack/spec/security'; -import type { Territory, TerritoryModel, TerritoryType } from '@objectstack/spec/security'; - -// Validate data -const result = Territory.parse(data); -``` - ---- - -## Territory - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Territory unique name (lowercase snake_case) | -| **label** | `string` | ✅ | Territory Label (e.g. "West Coast") | -| **modelId** | `string` | ✅ | Belongs to which Territory Model | -| **parent** | `string` | optional | Parent Territory | -| **type** | `Enum<'geography' \| 'industry' \| 'named_account' \| 'product_line'>` | optional | | -| **assignmentRule** | `string` | optional | Criteria based assignment rule | -| **assignedUsers** | `string[]` | optional | | -| **accountAccess** | `Enum<'read' \| 'edit'>` | optional | | -| **opportunityAccess** | `Enum<'read' \| 'edit'>` | optional | | -| **caseAccess** | `Enum<'read' \| 'edit'>` | optional | | - - ---- - -## TerritoryModel - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Model Name (e.g. FY24 Planning) | -| **state** | `Enum<'planning' \| 'active' \| 'archived'>` | optional | | -| **startDate** | `string` | optional | | -| **endDate** | `string` | optional | | - - ---- - -## TerritoryType - -### Allowed Values - -* `geography` -* `industry` -* `named_account` -* `product_line` - - ---- - diff --git a/content/docs/references/shared/http.mdx b/content/docs/references/shared/http.mdx deleted file mode 100644 index 9c8a3b68b..000000000 --- a/content/docs/references/shared/http.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Http -description: Http protocol schemas ---- - -Shared HTTP Schemas - -Common HTTP-related schemas used across API and System protocols. - -These schemas ensure consistency across different parts of the stack. - - -**Source:** `packages/spec/src/shared/http.zod.ts` - - -## TypeScript Usage - -```typescript -import { CorsConfig, RateLimitConfig, StaticMount } from '@objectstack/spec/shared'; -import type { CorsConfig, RateLimitConfig, StaticMount } from '@objectstack/spec/shared'; - -// Validate data -const result = CorsConfig.parse(data); -``` - ---- - -## CorsConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable CORS | -| **origins** | `string \| string[]` | optional | Allowed origins (* for all) | -| **methods** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>[]` | optional | Allowed HTTP methods | -| **credentials** | `boolean` | optional | Allow credentials (cookies, authorization headers) | -| **maxAge** | `integer` | optional | Preflight cache duration in seconds | - - ---- - -## RateLimitConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable rate limiting | -| **windowMs** | `integer` | optional | Time window in milliseconds | -| **maxRequests** | `integer` | optional | Max requests per window | - - ---- - -## StaticMount - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **path** | `string` | ✅ | URL path to serve from | -| **directory** | `string` | ✅ | Physical directory to serve | -| **cacheControl** | `string` | optional | Cache-Control header value | - - ---- - diff --git a/content/docs/references/shared/identifiers.mdx b/content/docs/references/shared/identifiers.mdx deleted file mode 100644 index 6e61770f4..000000000 --- a/content/docs/references/shared/identifiers.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Identifiers -description: Identifiers protocol schemas ---- - -System Identifier Schema - -Universal naming convention for all machine identifiers (API Names) in ObjectStack. - -Enforces lowercase with underscores or dots to ensure: - -- Cross-platform compatibility (case-insensitive filesystems) - -- URL-friendliness (no encoding needed) - -- Database consistency (no collation issues) - -- Security (no case-sensitivity bugs in permission checks) - -**Applies to all metadata that acts as a machine identifier:** - -- Object names (tables/collections) - -- Field names - -- Role names - -- Permission set names - -- Action/trigger names - -- Event keys - -- App IDs - -- Menu/page IDs - -- Select option values - -- Workflow names - -- Webhook names - -**Naming Convention Summary:** - -| Type | Pattern | Example | - -|------|---------|---------| - -| Machine ID | snake_case | `crm_account`, `btn_submit`, `role_admin` | - -| Event keys | dot.notation | `user.login`, `order.created` | - -| Labels | Any case | `Client Account`, `Submit Form` | - -@example Valid identifiers - -- 'account' - -- 'crm_account' - -- 'user_profile' - -- 'order.created' (for events) - -- 'api_v2_endpoint' - -@example Invalid identifiers (will be rejected) - -- 'Account' (uppercase) - -- 'CrmAccount' (camelCase) - -- 'crm-account' (kebab-case - use underscore instead) - -- 'user profile' (spaces) - - -**Source:** `packages/spec/src/shared/identifiers.zod.ts` - - -## TypeScript Usage - -```typescript -import { EventName, SnakeCaseIdentifier, SystemIdentifier } from '@objectstack/spec/shared'; -import type { EventName, SnakeCaseIdentifier, SystemIdentifier } from '@objectstack/spec/shared'; - -// Validate data -const result = EventName.parse(data); -``` - ---- - -## EventName - -Event name (lowercase with dot notation for namespacing) - - ---- - -## SnakeCaseIdentifier - -Snake case identifier (lowercase with underscores only) - - ---- - -## SystemIdentifier - -System identifier (lowercase with underscores or dots) - - ---- - diff --git a/content/docs/references/shared/index.mdx b/content/docs/references/shared/index.mdx index 9229a9d7a..65a3c90db 100644 --- a/content/docs/references/shared/index.mdx +++ b/content/docs/references/shared/index.mdx @@ -7,7 +7,9 @@ This section contains all protocol schemas for the shared layer of ObjectStack. + + diff --git a/content/docs/references/shared/mapping.mdx b/content/docs/references/shared/mapping.mdx deleted file mode 100644 index 6b41ea5a7..000000000 --- a/content/docs/references/shared/mapping.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Mapping -description: Mapping protocol schemas ---- - -Base Field Mapping Protocol - -Shared by: ETL, Sync, Connector, External Lookup - -This module provides the canonical field mapping schema used across - -ObjectStack for data transformation and synchronization. - -**Use Cases:** - -- ETL pipelines (data/mapping.zod.ts) - -- Data synchronization (automation/sync.zod.ts) - -- Integration connectors (integration/connector.zod.ts) - -- External lookups (data/external-lookup.zod.ts) - -@example Basic field mapping - -```typescript - -const mapping: FieldMapping = { - -source: 'external_user_id', - -target: 'user_id', - -}; - -``` - -@example With transformation - -```typescript - -const mapping: FieldMapping = { - -source: 'user_name', - -target: 'name', - -transform: { type: 'cast', targetType: 'string' }, - -defaultValue: 'Unknown' - -}; - -``` - - -**Source:** `packages/spec/src/shared/mapping.zod.ts` - - -## TypeScript Usage - -```typescript -import { FieldMapping, TransformType } from '@objectstack/spec/shared'; -import type { FieldMapping, TransformType } from '@objectstack/spec/shared'; - -// Validate data -const result = FieldMapping.parse(data); -``` - ---- - -## FieldMapping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Source field name | -| **target** | `string` | ✅ | Target field name | -| **transform** | `Object \| Object \| Object \| Object \| Object` | optional | Transformation to apply | -| **defaultValue** | `any` | optional | Default if source is null/undefined | - - ---- - -## TransformType - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Set a constant value - -**Type:** `constant` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **value** | `any` | optional | Constant value to use | - ---- - -#### Option 2 - -Cast to a specific data type - -**Type:** `cast` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **targetType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date'>` | ✅ | Target data type | - ---- - -#### Option 3 - -Lookup value from another table - -**Type:** `lookup` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **table** | `string` | ✅ | Lookup table name | -| **keyField** | `string` | ✅ | Field to match on | -| **valueField** | `string` | ✅ | Field to retrieve | - ---- - -#### Option 4 - -Custom JavaScript transformation - -**Type:** `javascript` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string` | ✅ | JavaScript expression (e.g., "value.toUpperCase()") | - ---- - -#### Option 5 - -Map values using a dictionary - -**Type:** `map` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **mappings** | `Record` | ✅ | Value mappings (e.g., `{"Active": "active"}`) | - ---- - - ---- - diff --git a/content/docs/references/shared/meta.json b/content/docs/references/shared/meta.json deleted file mode 100644 index f1b46847c..000000000 --- a/content/docs/references/shared/meta.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "title": "Shared Protocol", - "pages": [ - "http", - "identifiers", - "mapping", - "view" - ] -} \ No newline at end of file diff --git a/content/docs/references/shared/view.mdx b/content/docs/references/shared/view.mdx deleted file mode 100644 index 3c36a22a9..000000000 --- a/content/docs/references/shared/view.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: View -description: View protocol schemas ---- - - -**Source:** `packages/spec/src/shared/view.zod.ts` - - -## TypeScript Usage - -```typescript -import { HttpMethod } from '@objectstack/spec/shared'; -import type { HttpMethod } from '@objectstack/spec/shared'; - -// Validate data -const result = HttpMethod.parse(data); -``` - ---- - -## HttpMethod - -### Allowed Values - -* `GET` -* `POST` -* `PUT` -* `DELETE` -* `PATCH` -* `HEAD` -* `OPTIONS` - - ---- - diff --git a/content/docs/references/studio/index.mdx b/content/docs/references/studio/index.mdx new file mode 100644 index 000000000..2e3a88125 --- /dev/null +++ b/content/docs/references/studio/index.mdx @@ -0,0 +1,10 @@ +--- +title: Studio Protocol +description: Complete reference for all studio protocol schemas +--- + +This section contains all protocol schemas for the studio layer of ObjectStack. + + + + diff --git a/content/docs/references/system/audit.mdx b/content/docs/references/system/audit.mdx deleted file mode 100644 index 30b08a236..000000000 --- a/content/docs/references/system/audit.mdx +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Audit -description: Audit protocol schemas ---- - -Audit Log Architecture - -Comprehensive audit logging system for compliance and security. - -Supports SOX, HIPAA, GDPR, and other regulatory requirements. - -Features: - -- Records all CRUD operations on data - -- Tracks authentication events (login, logout, password reset) - -- Monitors authorization changes (permissions, roles) - -- Configurable retention policies (180-day GDPR requirement) - -- Suspicious activity detection and alerting - - -**Source:** `packages/spec/src/system/audit.zod.ts` - - -## TypeScript Usage - -```typescript -import { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; -import type { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; - -// Validate data -const result = AuditConfig.parse(data); -``` - ---- - -## AuditConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | -| **label** | `string` | ✅ | Display label | -| **enabled** | `boolean` | optional | Enable audit logging | -| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to audit | -| **excludeEventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to exclude | -| **minimumSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Minimum severity level | -| **storage** | `Object` | ✅ | Storage configuration | -| **retentionPolicy** | `Object` | optional | Retention policy | -| **suspiciousActivityRules** | `Object[]` | optional | Suspicious activity rules | -| **includeSensitiveData** | `boolean` | optional | Include sensitive data | -| **redactFields** | `string[]` | optional | Fields to redact | -| **logReads** | `boolean` | optional | Log read operations | -| **readSamplingRate** | `number` | optional | Read sampling rate | -| **logSystemEvents** | `boolean` | optional | Log system events | -| **customHandlers** | `Object[]` | optional | Custom event handler references | -| **compliance** | `Object` | optional | Compliance configuration | - - ---- - -## AuditEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Audit event ID | -| **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'>` | optional | Event severity | -| **timestamp** | `string` | ✅ | Event timestamp | -| **actor** | `Object` | ✅ | Event actor | -| **target** | `Object` | optional | Event target | -| **description** | `string` | ✅ | Event description | -| **changes** | `Object[]` | optional | List of changes | -| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | 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 | - - ---- - -## AuditEventActor - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'user' \| 'system' \| 'service' \| 'api_client' \| 'integration'>` | ✅ | Actor type | -| **id** | `string` | ✅ | Actor identifier | -| **name** | `string` | optional | Actor display name | -| **email** | `string` | optional | Actor email address | -| **ipAddress** | `string` | optional | Actor IP address | -| **userAgent** | `string` | optional | User agent string | - - ---- - -## AuditEventChange - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Changed field name | -| **oldValue** | `any` | optional | Previous value | -| **newValue** | `any` | optional | New value | - - ---- - -## AuditEventFilter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 include | -| **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 | -| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Result status | -| **searchQuery** | `string` | optional | Search query | -| **customFilters** | `Record` | optional | Custom filters | - - ---- - -## AuditEventSeverity - -### Allowed Values - -* `debug` -* `info` -* `notice` -* `warning` -* `error` -* `critical` -* `alert` -* `emergency` - - ---- - -## AuditEventTarget - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | Target type | -| **id** | `string` | ✅ | Target identifier | -| **name** | `string` | optional | Target display name | -| **metadata** | `Record` | optional | Target metadata | - - ---- - -## AuditEventType - -### Allowed Values - -* `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` - - ---- - -## AuditRetentionPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **retentionDays** | `integer` | optional | Retention period in days | -| **archiveAfterRetention** | `boolean` | optional | Archive logs after retention period | -| **archiveStorage** | `Object` | optional | Archive storage configuration | -| **customRetention** | `Record` | optional | Custom retention by event type | -| **minimumRetentionDays** | `integer` | optional | Minimum retention for compliance | - - ---- - -## AuditStorageConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'database' \| 'elasticsearch' \| 'mongodb' \| 'clickhouse' \| 's3' \| 'gcs' \| 'azure_blob' \| 'custom'>` | ✅ | Storage backend type | -| **connectionString** | `string` | optional | Connection string | -| **config** | `Record` | optional | Storage-specific configuration | -| **bufferEnabled** | `boolean` | optional | Enable buffering | -| **bufferSize** | `integer` | optional | Buffer size | -| **flushIntervalSeconds** | `integer` | optional | Flush interval in seconds | -| **compression** | `boolean` | optional | Enable compression | - - ---- - -## SuspiciousActivityRule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Rule identifier | -| **name** | `string` | ✅ | Rule name | -| **description** | `string` | optional | Rule description | -| **enabled** | `boolean` | optional | Rule enabled status | -| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | ✅ | Event types to monitor | -| **condition** | `Object` | ✅ | Detection condition | -| **actions** | `Enum<'alert' \| 'lock_account' \| 'block_ip' \| 'require_mfa' \| 'log_critical' \| 'webhook'>[]` | ✅ | Actions to take | -| **alertSeverity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | optional | Alert severity | -| **notifications** | `Object` | optional | Notification configuration | - - ---- - diff --git a/content/docs/references/system/auth-config.mdx b/content/docs/references/system/auth-config.mdx deleted file mode 100644 index 932ffa516..000000000 --- a/content/docs/references/system/auth-config.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Auth Config -description: Auth Config protocol schemas ---- - -Better-Auth Configuration Protocol - -Defines the configuration required to initialize the Better-Auth kernel. - -Used in server-side configuration injection. - - -**Source:** `packages/spec/src/system/auth-config.zod.ts` - - -## TypeScript Usage - -```typescript -import { AuthConfig, AuthPluginConfig, AuthProviderConfig } from '@objectstack/spec/system'; -import type { AuthConfig, AuthPluginConfig, AuthProviderConfig } from '@objectstack/spec/system'; - -// Validate data -const result = AuthConfig.parse(data); -``` - ---- - -## AuthConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **secret** | `string` | optional | Encryption secret | -| **baseUrl** | `string` | optional | Base URL for auth routes | -| **databaseUrl** | `string` | optional | Database connection string | -| **providers** | `Object[]` | optional | | -| **plugins** | `Object` | optional | | -| **session** | `Object` | optional | | -| **[object Object]** | `any` | optional | | - - ---- - -## AuthPluginConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **organization** | `boolean` | optional | Enable Organization/Teams support | -| **twoFactor** | `boolean` | optional | Enable 2FA | -| **passkeys** | `boolean` | optional | Enable Passkey support | -| **magicLink** | `boolean` | optional | Enable Magic Link login | - - ---- - -## AuthProviderConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Provider ID (github, google) | -| **clientId** | `string` | ✅ | OAuth Client ID | -| **clientSecret** | `string` | ✅ | OAuth Client Secret | -| **scope** | `string[]` | optional | Requested permissions | - - ---- - diff --git a/content/docs/references/system/cache.mdx b/content/docs/references/system/cache.mdx deleted file mode 100644 index b61a630a6..000000000 --- a/content/docs/references/system/cache.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Cache -description: Cache protocol schemas ---- - -Application-Level Cache Protocol - -Multi-tier caching strategy for application data. - -Supports Memory, Redis, Memcached, and CDN. - -## Caching in ObjectStack - -**Application Cache (`system/cache.zod.ts`) - This File** - -- **Purpose**: Cache computed data, query results, aggregations - -- **Technologies**: Redis, Memcached, in-memory LRU - -- **Configuration**: TTL, eviction policies, cache warming - -- **Use case**: Cache expensive database queries, computed values - -- **Scope**: Application layer, server-side data storage - -**HTTP Cache (`api/http-cache.zod.ts`)** - -- **Purpose**: Cache API responses at HTTP protocol level - -- **Technologies**: HTTP headers (ETag, Last-Modified, Cache-Control), CDN - -- **Configuration**: Cache-Control headers, validation tokens - -- **Use case**: Reduce API response time for repeated metadata requests - -- **Scope**: HTTP layer, client-server communication - -@see ../../api/http-cache.zod.ts for HTTP-level caching - - -**Source:** `packages/spec/src/system/cache.zod.ts` - - -## TypeScript Usage - -```typescript -import { CacheConfig, CacheInvalidation, CacheStrategy, CacheTier } from '@objectstack/spec/system'; -import type { CacheConfig, CacheInvalidation, CacheStrategy, CacheTier } from '@objectstack/spec/system'; - -// Validate data -const result = CacheConfig.parse(data); -``` - ---- - -## CacheConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **tiers** | `Object[]` | ✅ | | -| **invalidation** | `Object[]` | ✅ | | -| **prefetch** | `boolean` | optional | | -| **compression** | `boolean` | optional | | -| **encryption** | `boolean` | optional | | - - ---- - -## CacheInvalidation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **trigger** | `Enum<'create' \| 'update' \| 'delete' \| 'manual'>` | ✅ | | -| **scope** | `Enum<'key' \| 'pattern' \| 'tag' \| 'all'>` | ✅ | | -| **pattern** | `string` | optional | | -| **tags** | `string[]` | optional | | - - ---- - -## CacheStrategy - -### Allowed Values - -* `lru` -* `lfu` -* `fifo` -* `ttl` -* `adaptive` - - ---- - -## CacheTier - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **type** | `Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>` | ✅ | | -| **maxSize** | `number` | optional | Max size in MB | -| **ttl** | `number` | optional | Default TTL in seconds | -| **strategy** | `Enum<'lru' \| 'lfu' \| 'fifo' \| 'ttl' \| 'adaptive'>` | optional | | -| **warmup** | `boolean` | optional | | - - ---- - diff --git a/content/docs/references/system/change-management.mdx b/content/docs/references/system/change-management.mdx deleted file mode 100644 index 829980d62..000000000 --- a/content/docs/references/system/change-management.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Change Management -description: Change Management protocol schemas ---- - -Change Type Enum - -Classification of change requests based on risk and approval requirements. - -Follows ITIL change management best practices. - - -**Source:** `packages/spec/src/system/change-management.zod.ts` - - -## TypeScript Usage - -```typescript -import { ChangeImpact, ChangePriority, ChangeRequest, ChangeStatus, ChangeType, RollbackPlan } from '@objectstack/spec/system'; -import type { ChangeImpact, ChangePriority, ChangeRequest, ChangeStatus, ChangeType, RollbackPlan } from '@objectstack/spec/system'; - -// Validate data -const result = ChangeImpact.parse(data); -``` - ---- - -## ChangeImpact - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **level** | `Enum<'low' \| 'medium' \| 'high' \| 'critical'>` | ✅ | Impact level | -| **affectedSystems** | `string[]` | ✅ | Affected systems | -| **affectedUsers** | `number` | optional | Affected user count | -| **downtime** | `Object` | optional | Downtime information | - - ---- - -## ChangePriority - -### Allowed Values - -* `critical` -* `high` -* `medium` -* `low` - - ---- - -## ChangeRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Change request ID | -| **title** | `string` | ✅ | Change title | -| **description** | `string` | ✅ | Change description | -| **type** | `Enum<'standard' \| 'normal' \| 'emergency' \| 'major'>` | ✅ | Change type | -| **priority** | `Enum<'critical' \| 'high' \| 'medium' \| 'low'>` | ✅ | Change priority | -| **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 | -| **approval** | `Object` | optional | Approval workflow | -| **attachments** | `Object[]` | optional | Attachments | - - ---- - -## ChangeStatus - -### Allowed Values - -* `draft` -* `submitted` -* `in-review` -* `approved` -* `scheduled` -* `in-progress` -* `completed` -* `failed` -* `rolled-back` -* `cancelled` - - ---- - -## ChangeType - -### Allowed Values - -* `standard` -* `normal` -* `emergency` -* `major` - - ---- - -## RollbackPlan - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **description** | `string` | ✅ | Rollback description | -| **steps** | `Object[]` | ✅ | Rollback steps | -| **testProcedure** | `string` | optional | Test procedure | - - ---- - diff --git a/content/docs/references/system/collaboration.mdx b/content/docs/references/system/collaboration.mdx deleted file mode 100644 index eebf7c8dd..000000000 --- a/content/docs/references/system/collaboration.mdx +++ /dev/null @@ -1,568 +0,0 @@ ---- -title: Collaboration -description: Collaboration protocol schemas ---- - -Real-Time Collaboration Protocol - -Defines schemas for real-time collaborative editing in ObjectStack. - -Supports Operational Transformation (OT), CRDT (Conflict-free Replicated Data Types), - -cursor sharing, and awareness state for collaborative applications. - -Industry alignment: Google Docs, Figma, VSCode Live Share, Yjs - - -**Source:** `packages/spec/src/system/collaboration.zod.ts` - - -## TypeScript Usage - -```typescript -import { AwarenessEvent, AwarenessSession, AwarenessUpdate, AwarenessUserState, CRDTMergeResult, CRDTState, CRDTType, CollaborationMode, CollaborationSession, CollaborationSessionConfig, CollaborativeCursor, CounterOperation, CursorColorPreset, CursorSelection, CursorStyle, CursorUpdate, GCounter, LWWRegister, ORSet, ORSetElement, OTComponent, OTOperation, OTOperationType, OTTransformResult, PNCounter, TextCRDTOperation, TextCRDTState, UserActivityStatus, VectorClock } from '@objectstack/spec/system'; -import type { AwarenessEvent, AwarenessSession, AwarenessUpdate, AwarenessUserState, CRDTMergeResult, CRDTState, CRDTType, CollaborationMode, CollaborationSession, CollaborationSessionConfig, CollaborativeCursor, CounterOperation, CursorColorPreset, CursorSelection, CursorStyle, CursorUpdate, GCounter, LWWRegister, ORSet, ORSetElement, OTComponent, OTOperation, OTOperationType, OTTransformResult, PNCounter, TextCRDTOperation, TextCRDTState, UserActivityStatus, VectorClock } from '@objectstack/spec/system'; - -// Validate data -const result = AwarenessEvent.parse(data); -``` - ---- - -## AwarenessEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **eventId** | `string` | ✅ | Event identifier | -| **sessionId** | `string` | ✅ | Session identifier | -| **eventType** | `Enum<'user.joined' \| 'user.left' \| 'user.updated' \| 'session.created' \| 'session.ended'>` | ✅ | Type of awareness event | -| **userId** | `string` | optional | User involved in event | -| **timestamp** | `string` | ✅ | ISO 8601 datetime of event | -| **payload** | `any` | optional | Event payload | - - ---- - -## AwarenessSession - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sessionId** | `string` | ✅ | Session identifier | -| **documentId** | `string` | optional | Document ID this session is for | -| **users** | `Object[]` | ✅ | 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 | - - ---- - -## AwarenessUpdate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **status** | `Enum<'active' \| 'idle' \| 'viewing' \| 'disconnected'>` | optional | Updated status | -| **currentDocument** | `string` | optional | Updated current document | -| **currentView** | `string` | optional | Updated current view | -| **metadata** | `Record` | optional | Updated metadata | - - ---- - -## AwarenessUserState - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **sessionId** | `string` | ✅ | Session identifier | -| **userName** | `string` | ✅ | Display name | -| **userAvatar** | `string` | optional | User avatar URL | -| **status** | `Enum<'active' \| 'idle' \| 'viewing' \| 'disconnected'>` | ✅ | Current activity status | -| **currentDocument** | `string` | optional | Document ID user is currently editing | -| **currentView** | `string` | optional | Current view/page user is on | -| **lastActivity** | `string` | ✅ | ISO 8601 datetime of last activity | -| **joinedAt** | `string` | ✅ | ISO 8601 datetime when user joined session | -| **permissions** | `string[]` | optional | User permissions in this session | -| **metadata** | `Record` | optional | Additional user state metadata | - - ---- - -## CRDTMergeResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **state** | `Object \| Object \| Object \| Object \| Object` | ✅ | Merged CRDT state | -| **conflicts** | `Object[]` | optional | Conflicts encountered during merge | - - ---- - -## CRDTState - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `lww-register` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **value** | `any` | optional | 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 | - ---- - -#### Option 2 - -**Type:** `g-counter` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **counts** | `Record` | ✅ | Map of replica ID to count | - ---- - -#### Option 3 - -**Type:** `pn-counter` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **positive** | `Record` | ✅ | Positive increments per replica | -| **negative** | `Record` | ✅ | Negative increments per replica | - ---- - -#### Option 4 - -**Type:** `or-set` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **elements** | `Object[]` | ✅ | Set elements with metadata | - ---- - -#### Option 5 - -**Type:** `text` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **documentId** | `string` | ✅ | Document identifier | -| **content** | `string` | ✅ | Current text content | -| **operations** | `Object[]` | ✅ | History of operations | -| **lamportClock** | `integer` | ✅ | Current Lamport clock value | -| **vectorClock** | `Object` | ✅ | Vector clock for causality | - ---- - - ---- - -## CRDTType - -### Allowed Values - -* `lww-register` -* `g-counter` -* `pn-counter` -* `g-set` -* `or-set` -* `lww-map` -* `text` -* `tree` -* `json` - - ---- - -## CollaborationMode - -### Allowed Values - -* `ot` -* `crdt` -* `lock` -* `hybrid` - - ---- - -## CollaborationSession - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sessionId** | `string` | ✅ | Session identifier | -| **documentId** | `string` | ✅ | Document identifier | -| **config** | `Object` | ✅ | Session configuration | -| **users** | `Object[]` | ✅ | Active users | -| **cursors** | `Object[]` | ✅ | Active cursors | -| **version** | `integer` | ✅ | Current document version | -| **operations** | `Object \| Object[]` | 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 | - - ---- - -## CollaborationSessionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **mode** | `Enum<'ot' \| 'crdt' \| 'lock' \| 'hybrid'>` | ✅ | Collaboration mode to use | -| **enableCursorSharing** | `boolean` | optional | Enable cursor sharing | -| **enablePresence** | `boolean` | optional | Enable presence tracking | -| **enableAwareness** | `boolean` | optional | Enable awareness state | -| **maxUsers** | `integer` | optional | Maximum concurrent users | -| **idleTimeout** | `integer` | optional | Idle timeout in milliseconds | -| **conflictResolution** | `Enum<'ot' \| 'crdt' \| 'manual'>` | optional | Conflict resolution strategy | -| **persistence** | `boolean` | optional | Enable operation persistence | -| **snapshot** | `Object` | optional | Snapshot configuration | - - ---- - -## CollaborativeCursor - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **userId** | `string` | ✅ | User identifier | -| **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 | -| **isTyping** | `boolean` | optional | Whether user is currently typing | -| **lastUpdate** | `string` | ✅ | ISO 8601 datetime of last cursor update | -| **metadata** | `Record` | optional | Additional cursor metadata | - - ---- - -## CounterOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **replicaId** | `string` | ✅ | Replica identifier | -| **delta** | `integer` | ✅ | Change amount (positive for increment, negative for decrement) | -| **timestamp** | `string` | ✅ | ISO 8601 datetime of operation | - - ---- - -## CursorColorPreset - -### Allowed Values - -* `blue` -* `green` -* `red` -* `yellow` -* `purple` -* `orange` -* `pink` -* `teal` -* `indigo` -* `cyan` - - ---- - -## CursorSelection - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **anchor** | `Object` | ✅ | Selection anchor (start point) | -| **focus** | `Object` | ✅ | Selection focus (end point) | -| **direction** | `Enum<'forward' \| 'backward'>` | optional | Selection direction | - - ---- - -## CursorStyle - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **color** | `Enum<'blue' \| 'green' \| 'red' \| 'yellow' \| 'purple' \| 'orange' \| 'pink' \| 'teal' \| 'indigo' \| 'cyan'> \| string` | ✅ | Cursor color (preset or custom hex) | -| **opacity** | `number` | optional | Cursor opacity (0-1) | -| **label** | `string` | optional | Label to display with cursor (usually username) | -| **showLabel** | `boolean` | optional | Whether to show label | -| **pulseOnUpdate** | `boolean` | optional | Whether to pulse when cursor moves | - - ---- - -## CursorUpdate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **position** | `Object` | optional | Updated cursor position | -| **selection** | `Object` | optional | Updated selection | -| **isTyping** | `boolean` | optional | Updated typing state | -| **metadata** | `Record` | optional | Updated metadata | - - ---- - -## GCounter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **counts** | `Record` | ✅ | Map of replica ID to count | - - ---- - -## LWWRegister - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **value** | `any` | optional | 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 | - - ---- - -## ORSet - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **elements** | `Object[]` | ✅ | Set elements with metadata | - - ---- - -## ORSetElement - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `any` | optional | Element value | -| **timestamp** | `string` | ✅ | Addition timestamp | -| **replicaId** | `string` | ✅ | Replica that added the element | -| **uid** | `string` | ✅ | Unique identifier for this addition | -| **removed** | `boolean` | optional | Whether element has been removed | - - ---- - -## OTComponent - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `insert` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **text** | `string` | ✅ | Text to insert | -| **attributes** | `Record` | optional | Text formatting attributes (e.g., bold, italic) | - ---- - -#### Option 2 - -**Type:** `delete` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **count** | `integer` | ✅ | Number of characters to delete | - ---- - -#### Option 3 - -**Type:** `retain` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **count** | `integer` | ✅ | Number of characters to retain | -| **attributes** | `Record` | optional | Attribute changes to apply | - ---- - - ---- - -## OTOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operationId** | `string` | ✅ | Unique operation identifier | -| **documentId** | `string` | ✅ | Document identifier | -| **userId** | `string` | ✅ | User who created the operation | -| **sessionId** | `string` | ✅ | Session identifier | -| **components** | `Object \| Object \| Object[]` | ✅ | 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 | - - ---- - -## OTOperationType - -### Allowed Values - -* `insert` -* `delete` -* `retain` - - ---- - -## OTTransformResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operation** | `Object` | ✅ | Transformed operation | -| **transformed** | `boolean` | ✅ | Whether transformation was applied | -| **conflicts** | `string[]` | optional | Conflict descriptions if any | - - ---- - -## PNCounter - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **positive** | `Record` | ✅ | Positive increments per replica | -| **negative** | `Record` | ✅ | Negative increments per replica | - - ---- - -## TextCRDTOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operationId** | `string` | ✅ | Unique operation identifier | -| **replicaId** | `string` | ✅ | Replica identifier | -| **position** | `integer` | ✅ | Position in document | -| **insert** | `string` | optional | Text to insert | -| **delete** | `integer` | optional | Number of characters to delete | -| **timestamp** | `string` | ✅ | ISO 8601 datetime of operation | -| **lamportTimestamp** | `integer` | ✅ | Lamport timestamp for ordering | - - ---- - -## TextCRDTState - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **documentId** | `string` | ✅ | Document identifier | -| **content** | `string` | ✅ | Current text content | -| **operations** | `Object[]` | ✅ | History of operations | -| **lamportClock** | `integer` | ✅ | Current Lamport clock value | -| **vectorClock** | `Object` | ✅ | Vector clock for causality | - - ---- - -## UserActivityStatus - -### Allowed Values - -* `active` -* `idle` -* `viewing` -* `disconnected` - - ---- - -## VectorClock - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **clock** | `Record` | ✅ | Map of replica ID to logical timestamp | - - ---- - diff --git a/content/docs/references/system/compliance.mdx b/content/docs/references/system/compliance.mdx deleted file mode 100644 index 1b401e048..000000000 --- a/content/docs/references/system/compliance.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Compliance -description: Compliance protocol schemas ---- - -Compliance protocol for GDPR, CCPA, HIPAA, SOX, PCI-DSS - - -**Source:** `packages/spec/src/system/compliance.zod.ts` - - -## TypeScript Usage - -```typescript -import { AuditLogConfig, ComplianceConfig, GDPRConfig, HIPAAConfig, PCIDSSConfig } from '@objectstack/spec/system'; -import type { AuditLogConfig, ComplianceConfig, GDPRConfig, HIPAAConfig, PCIDSSConfig } from '@objectstack/spec/system'; - -// Validate data -const result = AuditLogConfig.parse(data); -``` - ---- - -## AuditLogConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **retentionDays** | `number` | optional | | -| **immutable** | `boolean` | optional | | -| **signLogs** | `boolean` | optional | | -| **events** | `Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'export' \| 'permission-change' \| 'login' \| 'logout' \| 'failed-login'>[]` | ✅ | | - - ---- - -## ComplianceConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **gdpr** | `Object` | optional | | -| **hipaa** | `Object` | optional | | -| **pciDss** | `Object` | optional | | -| **auditLog** | `Object` | ✅ | | - - ---- - -## GDPRConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | | -| **dataSubjectRights** | `Object` | ✅ | | -| **legalBasis** | `Enum<'consent' \| 'contract' \| 'legal-obligation' \| 'vital-interests' \| 'public-task' \| 'legitimate-interests'>` | ✅ | | -| **consentTracking** | `boolean` | optional | | -| **dataRetentionDays** | `number` | optional | | -| **dataProcessingAgreement** | `string` | optional | | - - ---- - -## HIPAAConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | | -| **phi** | `Object` | ✅ | | -| **businessAssociateAgreement** | `boolean` | optional | | - - ---- - -## PCIDSSConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | ✅ | | -| **level** | `Enum<'1' \| '2' \| '3' \| '4'>` | ✅ | | -| **cardDataFields** | `string[]` | ✅ | | -| **tokenization** | `boolean` | optional | | -| **encryptionInTransit** | `boolean` | optional | | -| **encryptionAtRest** | `boolean` | optional | | - - ---- - diff --git a/content/docs/references/system/encryption.mdx b/content/docs/references/system/encryption.mdx deleted file mode 100644 index d158264c2..000000000 --- a/content/docs/references/system/encryption.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Encryption -description: Encryption protocol schemas ---- - -Field-level encryption protocol - -GDPR/HIPAA/PCI-DSS compliant - - -**Source:** `packages/spec/src/system/encryption.zod.ts` - - -## TypeScript Usage - -```typescript -import { EncryptionAlgorithm, EncryptionConfig, FieldEncryption, KeyManagementProvider, KeyRotationPolicy } from '@objectstack/spec/system'; -import type { EncryptionAlgorithm, EncryptionConfig, FieldEncryption, KeyManagementProvider, KeyRotationPolicy } from '@objectstack/spec/system'; - -// Validate data -const result = EncryptionAlgorithm.parse(data); -``` - ---- - -## EncryptionAlgorithm - -### Allowed Values - -* `aes-256-gcm` -* `aes-256-cbc` -* `chacha20-poly1305` - - ---- - -## EncryptionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **algorithm** | `Enum<'aes-256-gcm' \| 'aes-256-cbc' \| 'chacha20-poly1305'>` | optional | | -| **keyManagement** | `Object` | ✅ | | -| **scope** | `Enum<'field' \| 'record' \| 'table' \| 'database'>` | ✅ | | -| **deterministicEncryption** | `boolean` | optional | Allows equality queries on encrypted data | -| **searchableEncryption** | `boolean` | optional | Allows search on encrypted data | - - ---- - -## FieldEncryption - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fieldName** | `string` | ✅ | | -| **encryptionConfig** | `Object` | ✅ | | -| **indexable** | `boolean` | optional | | - - ---- - -## KeyManagementProvider - -### Allowed Values - -* `local` -* `aws-kms` -* `azure-key-vault` -* `gcp-kms` -* `hashicorp-vault` - - ---- - -## KeyRotationPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **frequencyDays** | `number` | optional | | -| **retainOldVersions** | `number` | optional | | -| **autoRotate** | `boolean` | optional | | - - ---- - diff --git a/content/docs/references/system/http-server.mdx b/content/docs/references/system/http-server.mdx deleted file mode 100644 index 597805643..000000000 --- a/content/docs/references/system/http-server.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Http Server -description: Http Server protocol schemas ---- - -HTTP Server Protocol - -Defines the runtime HTTP server configuration and capabilities. - -Provides abstractions for HTTP server implementations (Express, Fastify, Hono, etc.) - -Architecture alignment: - -- Kubernetes: Service and Ingress resources - -- AWS: API Gateway configuration - -- Spring Boot: Application properties - - -**Source:** `packages/spec/src/system/http-server.zod.ts` - - -## TypeScript Usage - -```typescript -import { HttpServerConfig, MiddlewareConfig, MiddlewareType, RouteHandlerMetadata, ServerCapabilities, ServerEvent, ServerEventType, ServerStatus } from '@objectstack/spec/system'; -import type { HttpServerConfig, MiddlewareConfig, MiddlewareType, RouteHandlerMetadata, ServerCapabilities, ServerEvent, ServerEventType, ServerStatus } from '@objectstack/spec/system'; - -// Validate data -const result = HttpServerConfig.parse(data); -``` - ---- - -## HttpServerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **port** | `integer` | optional | Port number to listen on | -| **host** | `string` | optional | Host address to bind to | -| **cors** | `Object` | optional | CORS configuration | -| **requestTimeout** | `integer` | optional | Request timeout in milliseconds | -| **bodyLimit** | `string` | optional | Maximum request body size | -| **compression** | `boolean` | optional | Enable response compression | -| **security** | `Object` | optional | Security configuration | -| **static** | `Object[]` | optional | Static file serving configuration | -| **trustProxy** | `boolean` | optional | Trust X-Forwarded-* headers | - - ---- - -## MiddlewareConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Middleware name (snake_case) | -| **type** | `Enum<'authentication' \| 'authorization' \| 'logging' \| 'validation' \| 'transformation' \| 'error' \| 'custom'>` | ✅ | Middleware type | -| **enabled** | `boolean` | optional | Whether middleware is enabled | -| **order** | `integer` | optional | Execution order priority | -| **config** | `Record` | optional | Middleware configuration object | -| **paths** | `Object` | optional | Path filtering | - - ---- - -## MiddlewareType - -### Allowed Values - -* `authentication` -* `authorization` -* `logging` -* `validation` -* `transformation` -* `error` -* `custom` - - ---- - -## RouteHandlerMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | | - - ---- - -## ServerCapabilities - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **httpVersions** | `Enum<'1.0' \| '1.1' \| '2.0' \| '3.0'>[]` | optional | Supported HTTP versions | -| **websocket** | `boolean` | optional | WebSocket support | -| **sse** | `boolean` | optional | Server-Sent Events support | -| **serverPush** | `boolean` | optional | HTTP/2 Server Push support | -| **streaming** | `boolean` | optional | Response streaming support | -| **middleware** | `boolean` | optional | Middleware chain support | -| **routeParams** | `boolean` | optional | URL parameter support (/users/:id) | -| **compression** | `boolean` | optional | Built-in compression support | - - ---- - -## ServerEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'starting' \| 'started' \| 'stopping' \| 'stopped' \| 'request' \| 'response' \| 'error'>` | ✅ | Event type | -| **timestamp** | `string` | ✅ | Event timestamp (ISO 8601) | -| **data** | `Record` | optional | Event-specific data | - - ---- - -## ServerEventType - -### Allowed Values - -* `starting` -* `started` -* `stopping` -* `stopped` -* `request` -* `response` -* `error` - - ---- - -## ServerStatus - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | | - - ---- - diff --git a/content/docs/references/system/index.mdx b/content/docs/references/system/index.mdx index 99a87f62b..786b78ea2 100644 --- a/content/docs/references/system/index.mdx +++ b/content/docs/references/system/index.mdx @@ -12,9 +12,11 @@ This section contains all protocol schemas for the system layer of ObjectStack. + + @@ -23,8 +25,9 @@ This section contains all protocol schemas for the system layer of ObjectStack. + - + diff --git a/content/docs/references/system/job.mdx b/content/docs/references/system/job.mdx deleted file mode 100644 index bfb9a69b7..000000000 --- a/content/docs/references/system/job.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Job -description: Job protocol schemas ---- - -Cron Schedule Schema - -Schedule jobs using cron expressions - - -**Source:** `packages/spec/src/system/job.zod.ts` - - -## TypeScript Usage - -```typescript -import { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; -import type { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; - -// Validate data -const result = CronSchedule.parse(data); -``` - ---- - -## CronSchedule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string` | ✅ | Cron expression (e.g., "0 0 * * *" for daily at midnight) | -| **timezone** | `string` | optional | Timezone for cron execution (e.g., "America/New_York") | - - ---- - -## IntervalSchedule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **intervalMs** | `integer` | ✅ | Interval in milliseconds | - - ---- - -## Job - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique job identifier | -| **name** | `string` | ✅ | Job name (snake_case) | -| **schedule** | `Object \| Object \| Object` | ✅ | Job schedule configuration | -| **handler** | `string` | ✅ | Handler path (e.g. "path/to/file:functionName") or script ID | -| **retryPolicy** | `Object` | optional | Retry policy configuration | -| **timeout** | `integer` | optional | Timeout in milliseconds | -| **enabled** | `boolean` | optional | Whether the job is enabled | - - ---- - -## JobExecution - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **jobId** | `string` | ✅ | Job identifier | -| **startedAt** | `string` | ✅ | ISO 8601 datetime when execution started | -| **completedAt** | `string` | optional | ISO 8601 datetime when execution completed | -| **status** | `Enum<'running' \| 'success' \| 'failed' \| 'timeout'>` | ✅ | Execution status | -| **error** | `string` | optional | Error message if failed | -| **duration** | `integer` | optional | Execution duration in milliseconds | - - ---- - -## JobExecutionStatus - -### Allowed Values - -* `running` -* `success` -* `failed` -* `timeout` - - ---- - -## OnceSchedule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **at** | `string` | ✅ | ISO 8601 datetime when to execute | - - ---- - -## RetryPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxRetries** | `integer` | optional | Maximum number of retry attempts | -| **backoffMs** | `integer` | optional | Initial backoff delay in milliseconds | -| **backoffMultiplier** | `number` | optional | Multiplier for exponential backoff | - - ---- - -## Schedule - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `cron` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **expression** | `string` | ✅ | Cron expression (e.g., "0 0 * * *" for daily at midnight) | -| **timezone** | `string` | optional | Timezone for cron execution (e.g., "America/New_York") | - ---- - -#### Option 2 - -**Type:** `interval` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **intervalMs** | `integer` | ✅ | Interval in milliseconds | - ---- - -#### Option 3 - -**Type:** `once` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **at** | `string` | ✅ | ISO 8601 datetime when to execute | - ---- - - ---- - diff --git a/content/docs/references/system/license.mdx b/content/docs/references/system/license.mdx deleted file mode 100644 index b73fd94a6..000000000 --- a/content/docs/references/system/license.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: License -description: License protocol schemas ---- - -Metric Type Classification - - -**Source:** `packages/spec/src/system/license.zod.ts` - - -## TypeScript Usage - -```typescript -import { Feature, License, Plan } from '@objectstack/spec/system'; -import type { Feature, License, Plan } from '@objectstack/spec/system'; - -// Validate data -const result = Feature.parse(data); -``` - ---- - -## Feature - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **code** | `string` | ✅ | Feature code (e.g. core.api_access) | -| **label** | `string` | ✅ | | -| **description** | `string` | optional | | -| **type** | `Enum<'boolean' \| 'counter' \| 'gauge'>` | optional | | -| **unit** | `Enum<'count' \| 'bytes' \| 'seconds' \| 'percent'>` | optional | | -| **requires** | `string[]` | optional | | - - ---- - -## License - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **spaceId** | `string` | ✅ | Target Space ID | -| **planCode** | `string` | ✅ | | -| **issuedAt** | `string` | ✅ | | -| **expiresAt** | `string` | optional | | -| **status** | `Enum<'active' \| 'expired' \| 'suspended' \| 'trial'>` | ✅ | | -| **customFeatures** | `string[]` | optional | | -| **customLimits** | `Record` | optional | | -| **plugins** | `string[]` | optional | List of enabled plugin package IDs | -| **signature** | `string` | optional | Cryptographic signature of the license | - - ---- - -## Plan - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **code** | `string` | ✅ | Plan code (e.g. pro_v1) | -| **label** | `string` | ✅ | | -| **active** | `boolean` | optional | | -| **features** | `string[]` | ✅ | List of enabled boolean features | -| **limits** | `Record` | ✅ | Map of metric codes to limit values (e.g. `{ storage_gb: 10 }`) | -| **currency** | `string` | optional | | -| **priceMonthly** | `number` | optional | | -| **priceYearly** | `number` | optional | | - - ---- - diff --git a/content/docs/references/system/logging.mdx b/content/docs/references/system/logging.mdx deleted file mode 100644 index ae4c16e08..000000000 --- a/content/docs/references/system/logging.mdx +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: Logging -description: Logging protocol schemas ---- - -Logging Protocol - Comprehensive Observability Logging - -Unified logging protocol that combines: - -- Basic kernel logging (LoggerConfig) - -- Enterprise-grade features (LoggingConfig) - -- Multiple log destinations (file, console, external services) - -- Structured logging with enrichment - -- Log aggregation and forwarding - -- Integration with external log management systems - - -**Source:** `packages/spec/src/system/logging.zod.ts` - - -## TypeScript Usage - -```typescript -import { ConsoleDestinationConfig, ExtendedLogLevel, ExternalServiceDestinationConfig, FileDestinationConfig, HttpDestinationConfig, LogDestination, LogDestinationType, LogEnrichmentConfig, LogEntry, LogFormat, LogLevel, LoggerConfig, LoggingConfig, StructuredLogEntry } from '@objectstack/spec/system'; -import type { ConsoleDestinationConfig, ExtendedLogLevel, ExternalServiceDestinationConfig, FileDestinationConfig, HttpDestinationConfig, LogDestination, LogDestinationType, LogEnrichmentConfig, LogEntry, LogFormat, LogLevel, LoggerConfig, LoggingConfig, StructuredLogEntry } from '@objectstack/spec/system'; - -// Validate data -const result = ConsoleDestinationConfig.parse(data); -``` - ---- - -## ConsoleDestinationConfig - -Console destination configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **stream** | `Enum<'stdout' \| 'stderr'>` | optional | | -| **colors** | `boolean` | optional | | -| **prettyPrint** | `boolean` | optional | | - - ---- - -## ExtendedLogLevel - -Extended log severity level - -### Allowed Values - -* `trace` -* `debug` -* `info` -* `warn` -* `error` -* `fatal` - - ---- - -## ExternalServiceDestinationConfig - -External service destination configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **endpoint** | `string` | optional | | -| **region** | `string` | optional | | -| **credentials** | `Object` | optional | | -| **logGroup** | `string` | optional | | -| **logStream** | `string` | optional | | -| **index** | `string` | optional | | -| **config** | `Record` | optional | | - - ---- - -## FileDestinationConfig - -File destination configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **path** | `string` | ✅ | Log file path | -| **rotation** | `Object` | optional | | -| **encoding** | `string` | optional | | -| **append** | `boolean` | optional | | - - ---- - -## HttpDestinationConfig - -HTTP destination configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | ✅ | HTTP endpoint URL | -| **method** | `Enum<'POST' \| 'PUT'>` | optional | | -| **headers** | `Record` | optional | | -| **auth** | `Object` | optional | | -| **batch** | `Object` | optional | | -| **retry** | `Object` | optional | | -| **timeout** | `integer` | optional | | - - ---- - -## LogDestination - -Log destination configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Destination name (snake_case) | -| **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'>` | optional | Extended log severity level | -| **enabled** | `boolean` | optional | | -| **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 | -| **format** | `Enum<'json' \| 'text' \| 'pretty'>` | optional | | -| **filterId** | `string` | optional | Filter function identifier | - - ---- - -## LogDestinationType - -Log destination type - -### Allowed Values - -* `console` -* `file` -* `syslog` -* `elasticsearch` -* `cloudwatch` -* `stackdriver` -* `azure_monitor` -* `datadog` -* `splunk` -* `loki` -* `http` -* `kafka` -* `redis` -* `custom` - - ---- - -## LogEnrichmentConfig - -Log enrichment configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **staticFields** | `Record` | optional | Static fields added to every log | -| **dynamicEnrichers** | `string[]` | optional | Dynamic enricher function IDs | -| **addHostname** | `boolean` | optional | | -| **addProcessId** | `boolean` | optional | | -| **addEnvironment** | `boolean` | optional | | -| **addTimestampFormats** | `Object` | optional | | -| **addCaller** | `boolean` | optional | | -| **addCorrelationIds** | `boolean` | optional | | - - ---- - -## LogEntry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **level** | `Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>` | ✅ | Log severity level | -| **message** | `string` | ✅ | Log message | -| **context** | `Record` | optional | Structured context data | -| **error** | `Record` | optional | Error object if present | -| **traceId** | `string` | optional | Distributed trace ID | -| **spanId** | `string` | optional | Span ID | -| **service** | `string` | optional | Service name | -| **component** | `string` | optional | Component name (e.g. plugin id) | - - ---- - -## LogFormat - -Log output format - -### Allowed Values - -* `json` -* `text` -* `pretty` - - ---- - -## LogLevel - -Log severity level - -### Allowed Values - -* `debug` -* `info` -* `warn` -* `error` -* `fatal` -* `silent` - - ---- - -## LoggerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Logger name identifier | -| **level** | `Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>` | optional | Log severity level | -| **format** | `Enum<'json' \| 'text' \| 'pretty'>` | optional | Log output format | -| **redact** | `string[]` | optional | Keys to redact from log context | -| **sourceLocation** | `boolean` | optional | Include file and line number | -| **file** | `string` | optional | Path to log file | -| **rotation** | `Object` | optional | | - - ---- - -## LoggingConfig - -Logging configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | -| **label** | `string` | ✅ | Display label | -| **enabled** | `boolean` | optional | | -| **level** | `Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | optional | 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 | -| **redact** | `string[]` | optional | Fields to redact | -| **sampling** | `Object` | optional | | -| **buffer** | `Object` | optional | | -| **performance** | `Object` | optional | | - - ---- - -## StructuredLogEntry - -Structured log entry - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **timestamp** | `string` | ✅ | ISO 8601 timestamp | -| **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 | -| **environment** | `string` | optional | Environment (e.g., production, staging) | -| **user** | `Object` | optional | User context | -| **request** | `Object` | optional | Request context | -| **labels** | `Record` | optional | Custom labels | -| **metadata** | `Record` | optional | Additional metadata | - - ---- - diff --git a/content/docs/references/system/masking.mdx b/content/docs/references/system/masking.mdx deleted file mode 100644 index 2c22f7b86..000000000 --- a/content/docs/references/system/masking.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Masking -description: Masking protocol schemas ---- - -Data masking protocol for PII protection - - -**Source:** `packages/spec/src/system/masking.zod.ts` - - -## TypeScript Usage - -```typescript -import { MaskingConfig, MaskingRule, MaskingStrategy } from '@objectstack/spec/system'; -import type { MaskingConfig, MaskingRule, MaskingStrategy } from '@objectstack/spec/system'; - -// Validate data -const result = MaskingConfig.parse(data); -``` - ---- - -## MaskingConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **rules** | `Object[]` | ✅ | | -| **auditUnmasking** | `boolean` | optional | | - - ---- - -## MaskingRule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | | -| **strategy** | `Enum<'redact' \| 'partial' \| 'hash' \| 'tokenize' \| 'randomize' \| 'nullify' \| 'substitute'>` | ✅ | | -| **pattern** | `string` | optional | Regex pattern for partial masking | -| **preserveFormat** | `boolean` | optional | | -| **preserveLength** | `boolean` | optional | | -| **roles** | `string[]` | optional | Roles that see masked data | -| **exemptRoles** | `string[]` | optional | Roles that see unmasked data | - - ---- - -## MaskingStrategy - -### Allowed Values - -* `redact` -* `partial` -* `hash` -* `tokenize` -* `randomize` -* `nullify` -* `substitute` - - ---- - diff --git a/content/docs/references/system/message-queue.mdx b/content/docs/references/system/message-queue.mdx deleted file mode 100644 index 40cd4af38..000000000 --- a/content/docs/references/system/message-queue.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Message Queue -description: Message Queue protocol schemas ---- - -Message queue protocol for async communication - -Supports Kafka, RabbitMQ, AWS SQS, Redis Pub/Sub - - -**Source:** `packages/spec/src/system/message-queue.zod.ts` - - -## TypeScript Usage - -```typescript -import { ConsumerConfig, DeadLetterQueue, MessageQueueConfig, MessageQueueProvider, TopicConfig } from '@objectstack/spec/system'; -import type { ConsumerConfig, DeadLetterQueue, MessageQueueConfig, MessageQueueProvider, TopicConfig } from '@objectstack/spec/system'; - -// Validate data -const result = ConsumerConfig.parse(data); -``` - ---- - -## ConsumerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **groupId** | `string` | ✅ | | -| **autoOffsetReset** | `Enum<'earliest' \| 'latest'>` | optional | | -| **enableAutoCommit** | `boolean` | optional | | -| **maxPollRecords** | `number` | optional | | - - ---- - -## DeadLetterQueue - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | | -| **maxRetries** | `number` | optional | | -| **queueName** | `string` | ✅ | | - - ---- - -## MessageQueueConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'kafka' \| 'rabbitmq' \| 'aws-sqs' \| 'redis-pubsub' \| 'google-pubsub' \| 'azure-service-bus'>` | ✅ | | -| **topics** | `Object[]` | ✅ | | -| **consumers** | `Object[]` | optional | | -| **deadLetterQueue** | `Object` | optional | | -| **ssl** | `boolean` | optional | | -| **sasl** | `Object` | optional | | - - ---- - -## MessageQueueProvider - -### Allowed Values - -* `kafka` -* `rabbitmq` -* `aws-sqs` -* `redis-pubsub` -* `google-pubsub` -* `azure-service-bus` - - ---- - -## TopicConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **partitions** | `number` | optional | | -| **replicationFactor** | `number` | optional | | -| **retentionMs** | `number` | optional | | -| **compressionType** | `Enum<'none' \| 'gzip' \| 'snappy' \| 'lz4'>` | optional | | - - ---- - diff --git a/content/docs/references/system/meta.json b/content/docs/references/system/meta.json deleted file mode 100644 index ffa015100..000000000 --- a/content/docs/references/system/meta.json +++ /dev/null @@ -1,30 +0,0 @@ -{ - "title": "System Protocol", - "pages": [ - "audit", - "auth-config", - "cache", - "change-management", - "collaboration", - "compliance", - "encryption", - "http-server", - "job", - "logging", - "masking", - "message-queue", - "metadata-persistence", - "metrics", - "migration", - "notification", - "object-storage", - "search-engine", - "service-registry", - "tracing", - "translation", - "worker", - "tenant", - "license", - "registry-config" - ] -} \ No newline at end of file diff --git a/content/docs/references/system/metadata-persistence.mdx b/content/docs/references/system/metadata-persistence.mdx deleted file mode 100644 index be1d9fbd5..000000000 --- a/content/docs/references/system/metadata-persistence.mdx +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: Metadata Persistence -description: Metadata Persistence protocol schemas ---- - -Metadata Scope Enum - -Defines the lifecycle and mutability of a metadata item. - - -**Source:** `packages/spec/src/system/metadata-persistence.zod.ts` - - -## TypeScript Usage - -```typescript -import { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataState, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system'; -import type { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataState, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system'; - -// Validate data -const result = MetadataCollectionInfo.parse(data); -``` - ---- - -## MetadataCollectionInfo - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **count** | `number` | ✅ | | -| **namespaces** | `string[]` | ✅ | | - - ---- - -## MetadataExportOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **types** | `string[]` | optional | | -| **namespaces** | `string[]` | optional | | -| **output** | `string` | ✅ | Output directory or file | -| **format** | `Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>` | optional | | - - ---- - -## MetadataFormat - -### Allowed Values - -* `json` -* `yaml` -* `yml` -* `ts` -* `js` -* `typescript` -* `javascript` - - ---- - -## MetadataImportOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **source** | `string` | ✅ | Input directory or file | -| **strategy** | `Enum<'merge' \| 'replace' \| 'skip'>` | optional | | -| **validate** | `boolean` | optional | | - - ---- - -## MetadataLoadOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **scope** | `Enum<'system' \| 'platform' \| 'user'>` | optional | | -| **namespace** | `string` | optional | | -| **raw** | `boolean` | optional | Return raw file content instead of parsed JSON | -| **cache** | `boolean` | optional | | -| **useCache** | `boolean` | optional | | -| **validate** | `boolean` | optional | | -| **ifNoneMatch** | `string` | optional | | -| **recursive** | `boolean` | optional | | -| **limit** | `number` | optional | | -| **patterns** | `string[]` | optional | | -| **loader** | `string` | optional | Specific loader to use (e.g. filesystem, database) | - - ---- - -## MetadataLoadResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **data** | `any` | optional | | -| **stats** | `Object` | optional | | -| **format** | `Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>` | optional | | -| **source** | `string` | optional | | -| **fromCache** | `boolean` | optional | | -| **etag** | `string` | optional | | -| **notModified** | `boolean` | optional | | -| **loadTime** | `number` | optional | | - - ---- - -## MetadataLoaderContract - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **protocol** | `string` | ✅ | | -| **description** | `string` | optional | | -| **supportedFormats** | `string[]` | optional | | -| **supportsWatch** | `boolean` | optional | | -| **supportsWrite** | `boolean` | optional | | -| **supportsCache** | `boolean` | optional | | -| **capabilities** | `Object` | ✅ | | - - ---- - -## MetadataManagerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **loaders** | `any[]` | optional | | -| **watch** | `boolean` | optional | | -| **cache** | `boolean` | optional | | -| **basePath** | `string` | optional | | -| **rootDir** | `string` | optional | | -| **formats** | `Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>[]` | optional | | -| **watchOptions** | `any` | optional | | - - ---- - -## MetadataRecord - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **_id** | `string` | ✅ | | -| **name** | `string` | ✅ | | -| **type** | `string` | ✅ | | -| **namespace** | `string` | optional | | -| **scope** | `Enum<'system' \| 'platform' \| 'user'>` | optional | | -| **metadata** | `Record` | ✅ | | -| **extends** | `string` | optional | Name of the parent metadata to extend/override | -| **strategy** | `Enum<'merge' \| 'replace'>` | optional | | -| **owner** | `string` | optional | | -| **state** | `Enum<'draft' \| 'active' \| 'archived' \| 'deprecated'>` | optional | | -| **created_by** | `string` | optional | | -| **created_at** | `string` | optional | | -| **updated_by** | `string` | optional | | -| **updated_at** | `string` | optional | | - - ---- - -## MetadataSaveOptions - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **format** | `Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>` | optional | | -| **create** | `boolean` | optional | | -| **overwrite** | `boolean` | optional | | -| **path** | `string` | optional | | -| **prettify** | `boolean` | optional | | -| **indent** | `number` | optional | | -| **sortKeys** | `boolean` | optional | | -| **backup** | `boolean` | optional | | -| **atomic** | `boolean` | optional | | -| **loader** | `string` | optional | Specific loader to use (e.g. filesystem, database) | - - ---- - -## MetadataSaveResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **success** | `boolean` | ✅ | | -| **path** | `string` | optional | | -| **stats** | `Object` | optional | | -| **etag** | `string` | optional | | -| **size** | `number` | optional | | -| **saveTime** | `number` | optional | | -| **backupPath** | `string` | optional | | - - ---- - -## MetadataScope - -### Allowed Values - -* `system` -* `platform` -* `user` - - ---- - -## MetadataState - -### Allowed Values - -* `draft` -* `active` -* `archived` -* `deprecated` - - ---- - -## MetadataStats - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **path** | `string` | optional | | -| **size** | `number` | optional | | -| **mtime** | `string` | optional | | -| **hash** | `string` | optional | | -| **etag** | `string` | optional | | -| **modifiedAt** | `string` | optional | | -| **format** | `Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>` | optional | | - - ---- - -## MetadataWatchEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'add' \| 'change' \| 'unlink' \| 'added' \| 'changed' \| 'deleted'>` | ✅ | | -| **path** | `string` | ✅ | | -| **name** | `string` | optional | | -| **stats** | `Object` | optional | | -| **metadataType** | `string` | optional | | -| **data** | `any` | optional | | -| **timestamp** | `string` | optional | | - - ---- - diff --git a/content/docs/references/system/metrics.mdx b/content/docs/references/system/metrics.mdx deleted file mode 100644 index 5149c8ba5..000000000 --- a/content/docs/references/system/metrics.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Metrics -description: Metrics protocol schemas ---- - - -**Source:** `packages/spec/src/system/metrics.zod.ts` - - -## TypeScript Usage - -```typescript -import { MetricType } from '@objectstack/spec/system'; -import type { MetricType } from '@objectstack/spec/system'; - -// Validate data -const result = MetricType.parse(data); -``` - ---- - -## MetricType - -### Allowed Values - -* `boolean` -* `counter` -* `gauge` - - ---- - diff --git a/content/docs/references/system/migration.mdx b/content/docs/references/system/migration.mdx deleted file mode 100644 index 699fc9210..000000000 --- a/content/docs/references/system/migration.mdx +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Migration -description: Migration protocol schemas ---- - - -**Source:** `packages/spec/src/system/migration.zod.ts` - - -## TypeScript Usage - -```typescript -import { AddFieldOperation, ChangeSet, CreateObjectOperation, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; -import type { AddFieldOperation, ChangeSet, CreateObjectOperation, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; - -// Validate data -const result = AddFieldOperation.parse(data); -``` - ---- - -## AddFieldOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | -| **fieldName** | `string` | ✅ | | -| **field** | `Object` | ✅ | | - - ---- - -## ChangeSet - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this change set | -| **name** | `string` | ✅ | Human readable name for the migration | -| **description** | `string` | optional | | -| **author** | `string` | optional | | -| **createdAt** | `string` | optional | | -| **dependencies** | `Object[]` | optional | | -| **operations** | `Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | ✅ | | -| **rollback** | `Object \| Object \| Object \| Object \| Object \| Object \| Object[]` | optional | | - - ---- - -## CreateObjectOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **object** | `Object` | ✅ | | - - ---- - -## DeleteObjectOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | - - ---- - -## ExecuteSqlOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **sql** | `string` | ✅ | | -| **description** | `string` | optional | | - - ---- - -## MigrationDependency - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **migrationId** | `string` | ✅ | | -| **package** | `string` | optional | | - - ---- - -## MigrationOperation - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `add_field` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | -| **fieldName** | `string` | ✅ | | -| **field** | `Object` | ✅ | | - ---- - -#### Option 2 - -**Type:** `modify_field` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | -| **fieldName** | `string` | ✅ | | -| **changes** | `Record` | ✅ | | - ---- - -#### Option 3 - -**Type:** `remove_field` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | -| **fieldName** | `string` | ✅ | | - ---- - -#### Option 4 - -**Type:** `create_object` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **object** | `Object` | ✅ | | - ---- - -#### Option 5 - -**Type:** `rename_object` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **oldName** | `string` | ✅ | | -| **newName** | `string` | ✅ | | - ---- - -#### Option 6 - -**Type:** `delete_object` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | - ---- - -#### Option 7 - -**Type:** `execute_sql` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **sql** | `string` | ✅ | | -| **description** | `string` | optional | | - ---- - - ---- - -## ModifyFieldOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | -| **fieldName** | `string` | ✅ | | -| **changes** | `Record` | ✅ | | - - ---- - -## RemoveFieldOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | | -| **fieldName** | `string` | ✅ | | - - ---- - -## RenameObjectOperation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **oldName** | `string` | ✅ | | -| **newName** | `string` | ✅ | | - - ---- - diff --git a/content/docs/references/system/notification.mdx b/content/docs/references/system/notification.mdx deleted file mode 100644 index 3d86d708c..000000000 --- a/content/docs/references/system/notification.mdx +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Notification -description: Notification protocol schemas ---- - -Email Template Schema - -Defines the structure and content of email notifications. - -Supports variables for personalization and file attachments. - -@example - -```json - -{ - -"id": "welcome-email", - -"subject": "Welcome to {{company_name}}", - -"body": "

Welcome {{user_name}}!

", - -"bodyType": "html", - -"variables": ["company_name", "user_name"], - -"attachments": [ - -{ - -"name": "guide.pdf", - -"url": "https://example.com/guide.pdf" - -} - -] - -} - -``` - - -**Source:** `packages/spec/src/system/notification.zod.ts` - - -## TypeScript Usage - -```typescript -import { EmailTemplate, InAppNotification, NotificationChannel, NotificationConfig, PushNotification, SMSTemplate } from '@objectstack/spec/system'; -import type { EmailTemplate, InAppNotification, NotificationChannel, NotificationConfig, PushNotification, SMSTemplate } from '@objectstack/spec/system'; - -// Validate data -const result = EmailTemplate.parse(data); -``` - ---- - -## EmailTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Template identifier | -| **subject** | `string` | ✅ | Email subject | -| **body** | `string` | ✅ | Email body content | -| **bodyType** | `Enum<'text' \| 'html' \| 'markdown'>` | optional | Body content type | -| **variables** | `string[]` | optional | Template variables | -| **attachments** | `Object[]` | optional | Email attachments | - - ---- - -## InAppNotification - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | ✅ | Notification title | -| **message** | `string` | ✅ | Notification message | -| **type** | `Enum<'info' \| 'success' \| 'warning' \| 'error'>` | ✅ | Notification type | -| **actionUrl** | `string` | optional | Action URL | -| **dismissible** | `boolean` | optional | User dismissible | -| **expiresAt** | `number` | optional | Expiration timestamp | - - ---- - -## NotificationChannel - -### Allowed Values - -* `email` -* `sms` -* `push` -* `in-app` -* `slack` -* `teams` -* `webhook` - - ---- - -## NotificationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Notification ID | -| **name** | `string` | ✅ | Notification name | -| **channel** | `Enum<'email' \| 'sms' \| 'push' \| 'in-app' \| 'slack' \| 'teams' \| 'webhook'>` | ✅ | Notification channel | -| **template** | `Object \| Object \| Object \| Object` | ✅ | Notification template | -| **recipients** | `Object` | ✅ | Recipients | -| **schedule** | `Object` | optional | Scheduling | -| **retryPolicy** | `Object` | optional | Retry policy | -| **tracking** | `Object` | optional | Tracking configuration | - - ---- - -## PushNotification - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | ✅ | Notification title | -| **body** | `string` | ✅ | Notification body | -| **icon** | `string` | optional | Notification icon URL | -| **badge** | `number` | optional | Badge count | -| **data** | `Record` | optional | Custom data | -| **actions** | `Object[]` | optional | Notification actions | - - ---- - -## SMSTemplate - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Template identifier | -| **message** | `string` | ✅ | SMS message content | -| **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 deleted file mode 100644 index bd592220f..000000000 --- a/content/docs/references/system/object-storage.mdx +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Object Storage -description: Object Storage protocol schemas ---- - -Object Storage Protocol - -Unified storage protocol that combines: - -- Object storage systems (S3, Azure Blob, GCS, MinIO) - -- Scoped storage configuration (temp, cache, data, logs, config, public) - -- Multi-cloud storage providers - -- Bucket/container configuration - -- Access control and permissions - -- Lifecycle policies for data retention - -- Presigned URLs for secure direct access - -- Multipart uploads for large files - - -**Source:** `packages/spec/src/system/object-storage.zod.ts` - - -## TypeScript Usage - -```typescript -import { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system'; -import type { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system'; - -// Validate data -const result = AccessControlConfig.parse(data); -``` - ---- - -## AccessControlConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **acl** | `Enum<'private' \| 'public_read' \| 'public_read_write' \| 'authenticated_read' \| 'bucket_owner_read' \| 'bucket_owner_full_control'>` | optional | Default access control level | -| **allowedOrigins** | `string[]` | optional | CORS allowed origins | -| **allowedMethods** | `Enum<'GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD'>[]` | optional | CORS allowed HTTP methods | -| **allowedHeaders** | `string[]` | optional | CORS allowed headers | -| **exposeHeaders** | `string[]` | optional | CORS exposed headers | -| **maxAge** | `number` | optional | CORS preflight cache duration in seconds | -| **corsEnabled** | `boolean` | optional | Enable CORS configuration | -| **publicAccess** | `Object` | optional | Public access control | -| **allowedIps** | `string[]` | optional | Allowed IP addresses/CIDR blocks | -| **blockedIps** | `string[]` | optional | Blocked IP addresses/CIDR blocks | - - ---- - -## BucketConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Bucket identifier in ObjectStack (snake_case) | -| **label** | `string` | ✅ | Display label | -| **bucketName** | `string` | ✅ | Actual bucket/container name in storage provider | -| **region** | `string` | optional | Storage region (e.g., us-east-1, westus) | -| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>` | ✅ | Storage provider | -| **endpoint** | `string` | optional | Custom endpoint URL (for S3-compatible providers) | -| **pathStyle** | `boolean` | optional | Use path-style URLs (for S3-compatible providers) | -| **versioning** | `boolean` | optional | 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 | -| **tags** | `Record` | optional | Bucket tags for organization | -| **description** | `string` | optional | Bucket description | -| **enabled** | `boolean` | optional | Enable this bucket | - - ---- - -## FileMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **path** | `string` | ✅ | File path | -| **name** | `string` | ✅ | File name | -| **size** | `integer` | ✅ | File size in bytes | -| **mimeType** | `string` | ✅ | MIME type | -| **lastModified** | `string` | ✅ | Last modified timestamp | -| **created** | `string` | ✅ | Creation timestamp | -| **etag** | `string` | optional | Entity tag | - - ---- - -## LifecycleAction - -Lifecycle policy action type - -### Allowed Values - -* `transition` -* `delete` -* `abort` - - ---- - -## LifecyclePolicyConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable lifecycle policies | -| **rules** | `Object[]` | optional | Lifecycle rules | - - ---- - -## LifecyclePolicyRule - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Rule identifier | -| **enabled** | `boolean` | optional | Enable this rule | -| **action** | `Enum<'transition' \| 'delete' \| 'abort'>` | ✅ | Action to perform | -| **prefix** | `string` | optional | Object key prefix filter (e.g., "uploads/") | -| **tags** | `Record` | optional | Object tag filters | -| **daysAfterCreation** | `number` | optional | Days after object creation | -| **daysAfterModification** | `number` | optional | Days after last modification | -| **targetStorageClass** | `Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>` | optional | Target storage class for transition action | - - ---- - -## MultipartUploadConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **enabled** | `boolean` | optional | Enable multipart uploads | -| **partSize** | `number` | optional | Part size in bytes (min 5MB, max 5GB) | -| **maxParts** | `number` | optional | Maximum number of parts (max 10,000) | -| **threshold** | `number` | optional | File size threshold to trigger multipart upload (bytes) | -| **maxConcurrent** | `number` | optional | Maximum concurrent part uploads | -| **abortIncompleteAfterDays** | `number` | optional | Auto-abort incomplete uploads after N days | - - ---- - -## ObjectMetadata - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **contentType** | `string` | ✅ | MIME type (e.g., image/jpeg, application/pdf) | -| **contentLength** | `number` | ✅ | File size in bytes | -| **contentEncoding** | `string` | optional | Content encoding (e.g., gzip) | -| **contentDisposition** | `string` | optional | Content disposition header | -| **contentLanguage** | `string` | optional | Content language | -| **cacheControl** | `string` | optional | Cache control directives | -| **etag** | `string` | optional | Entity tag for versioning/caching | -| **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 | -| **custom** | `Record` | optional | Custom user-defined metadata | - - ---- - -## ObjectStorageConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Storage configuration identifier | -| **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'>` | optional | Storage scope | -| **connection** | `Object` | ✅ | Connection credentials | -| **buckets** | `Object[]` | optional | 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 | -| **options** | `Record` | optional | Provider-specific configuration options | -| **enabled** | `boolean` | optional | Enable this storage configuration | -| **description** | `string` | optional | Configuration description | - - ---- - -## PresignedUrlConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **operation** | `Enum<'get' \| 'put' \| 'delete' \| 'head'>` | ✅ | Allowed operation | -| **expiresIn** | `number` | ✅ | Expiration time in seconds (max 7 days) | -| **contentType** | `string` | optional | Required content type for PUT operations | -| **maxSize** | `number` | optional | Maximum file size in bytes for PUT operations | -| **responseContentType** | `string` | optional | Override content-type for GET operations | -| **responseContentDisposition** | `string` | optional | Override content-disposition for GET operations | - - ---- - -## StorageAcl - -Storage access control level - -### Allowed Values - -* `private` -* `public_read` -* `public_read_write` -* `authenticated_read` -* `bucket_owner_read` -* `bucket_owner_full_control` - - ---- - -## StorageClass - -Storage class/tier for cost optimization - -### Allowed Values - -* `standard` -* `intelligent` -* `infrequent_access` -* `glacier` -* `deep_archive` - - ---- - -## StorageConnection - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **accessKeyId** | `string` | optional | AWS access key ID or MinIO access key | -| **secretAccessKey** | `string` | optional | AWS secret access key or MinIO secret key | -| **sessionToken** | `string` | optional | AWS session token for temporary credentials | -| **accountName** | `string` | optional | Azure storage account name | -| **accountKey** | `string` | optional | Azure storage account key | -| **sasToken** | `string` | optional | Azure SAS token | -| **projectId** | `string` | optional | GCP project ID | -| **credentials** | `string` | optional | GCP service account credentials JSON | -| **endpoint** | `string` | optional | Custom endpoint URL | -| **region** | `string` | optional | Default region | -| **useSSL** | `boolean` | optional | Use SSL/TLS for connections | -| **timeout** | `number` | optional | Connection timeout in milliseconds | - - ---- - -## StorageProvider - -Storage provider type - -### Allowed Values - -* `s3` -* `azure_blob` -* `gcs` -* `minio` -* `r2` -* `spaces` -* `wasabi` -* `backblaze` -* `local` - - ---- - -## StorageScope - -Storage scope classification - -### Allowed Values - -* `global` -* `tenant` -* `user` -* `session` -* `temp` -* `cache` -* `data` -* `logs` -* `config` -* `public` - - ---- - diff --git a/content/docs/references/system/registry-config.mdx b/content/docs/references/system/registry-config.mdx deleted file mode 100644 index 8aab59ce9..000000000 --- a/content/docs/references/system/registry-config.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Registry Config -description: Registry Config protocol schemas ---- - -# Registry Configuration Protocol - -Defines the configuration for the ObjectStack Registry Service. - -Includes federation, synchronization, and storage settings. - - -**Source:** `packages/spec/src/system/registry-config.zod.ts` - - -## TypeScript Usage - -```typescript -import { RegistryConfig, RegistrySyncPolicy, RegistryUpstream } from '@objectstack/spec/system'; -import type { RegistryConfig, RegistrySyncPolicy, RegistryUpstream } from '@objectstack/spec/system'; - -// Validate data -const result = RegistryConfig.parse(data); -``` - ---- - -## RegistryConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'public' \| 'private' \| 'hybrid'>` | ✅ | Registry deployment type | -| **upstream** | `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 | | -| **visibility** | `Enum<'public' \| 'private' \| 'internal'>` | optional | Who can access this registry | -| **accessControl** | `Object` | optional | | -| **cache** | `Object` | optional | | -| **mirrors** | `Object[]` | optional | Mirror registries for redundancy | - - ---- - -## RegistrySyncPolicy - -Registry synchronization strategy - -### Allowed Values - -* `manual` -* `auto` -* `proxy` - - ---- - -## RegistryUpstream - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | ✅ | Upstream registry endpoint | -| **syncPolicy** | `Enum<'manual' \| 'auto' \| 'proxy'>` | optional | Registry synchronization strategy | -| **syncInterval** | `integer` | optional | Auto-sync interval in seconds | -| **auth** | `Object` | optional | | -| **tls** | `Object` | optional | | -| **timeout** | `integer` | optional | Request timeout in milliseconds | -| **retry** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/system/search-engine.mdx b/content/docs/references/system/search-engine.mdx deleted file mode 100644 index 0033d352e..000000000 --- a/content/docs/references/system/search-engine.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Search Engine -description: Search Engine protocol schemas ---- - -Full-text search protocol - -Supports Elasticsearch, Algolia, Meilisearch, Typesense - - -**Source:** `packages/spec/src/system/search-engine.zod.ts` - - -## TypeScript Usage - -```typescript -import { AnalyzerConfig, FacetConfig, SearchConfig, SearchIndexConfig, SearchProvider } from '@objectstack/spec/system'; -import type { AnalyzerConfig, FacetConfig, SearchConfig, SearchIndexConfig, SearchProvider } from '@objectstack/spec/system'; - -// Validate data -const result = AnalyzerConfig.parse(data); -``` - ---- - -## AnalyzerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'standard' \| 'simple' \| 'whitespace' \| 'keyword' \| 'pattern' \| 'language'>` | ✅ | | -| **language** | `string` | optional | | -| **stopwords** | `string[]` | optional | | -| **customFilters** | `string[]` | optional | | - - ---- - -## FacetConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | | -| **maxValues** | `number` | optional | | -| **sort** | `Enum<'count' \| 'alpha'>` | optional | | - - ---- - -## SearchConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `Enum<'elasticsearch' \| 'algolia' \| 'meilisearch' \| 'typesense' \| 'opensearch'>` | ✅ | | -| **indexes** | `Object[]` | ✅ | | -| **analyzers** | `Record` | optional | | -| **facets** | `Object[]` | optional | | -| **typoTolerance** | `boolean` | optional | | -| **synonyms** | `Record` | optional | | -| **ranking** | `Enum<'typo' \| 'geo' \| 'words' \| 'filters' \| 'proximity' \| 'attribute' \| 'exact' \| 'custom'>[]` | optional | | - - ---- - -## SearchIndexConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **indexName** | `string` | ✅ | | -| **objectName** | `string` | ✅ | Source ObjectQL object | -| **fields** | `Object[]` | ✅ | | -| **replicas** | `number` | optional | | -| **shards** | `number` | optional | | - - ---- - -## SearchProvider - -### Allowed Values - -* `elasticsearch` -* `algolia` -* `meilisearch` -* `typesense` -* `opensearch` - - ---- - diff --git a/content/docs/references/system/service-registry.mdx b/content/docs/references/system/service-registry.mdx deleted file mode 100644 index 699eae4e4..000000000 --- a/content/docs/references/system/service-registry.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Service Registry -description: Service Registry protocol schemas ---- - -# Service Registry Protocol - -Defines the standard built-in services that constitute the ObjectStack Kernel. - -This registry is used by the `ObjectKernel` and `HttpDispatcher` to: - -1. Verify service availability. - -2. Route requests to the correct service handler. - -3. Type-check service interactions. - - -**Source:** `packages/spec/src/system/service-registry.zod.ts` - - -## TypeScript Usage - -```typescript -import { CoreServiceName, KernelServiceMap, ServiceConfig, ServiceCriticality, ServiceStatus } from '@objectstack/spec/system'; -import type { CoreServiceName, KernelServiceMap, ServiceConfig, ServiceCriticality, ServiceStatus } from '@objectstack/spec/system'; - -// Validate data -const result = CoreServiceName.parse(data); -``` - ---- - -## CoreServiceName - -### Allowed Values - -* `metadata` -* `data` -* `auth` -* `file-storage` -* `search` -* `cache` -* `queue` -* `automation` -* `graphql` -* `analytics` -* `hub` -* `realtime` -* `job` -* `notification` - - ---- - -## KernelServiceMap - - ---- - -## ServiceConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | | -| **name** | `Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'graphql' \| 'analytics' \| 'hub' \| 'realtime' \| 'job' \| 'notification'>` | ✅ | | -| **options** | `Record` | optional | | - - ---- - -## ServiceCriticality - -### Allowed Values - -* `required` -* `core` -* `optional` - - ---- - -## ServiceStatus - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'graphql' \| 'analytics' \| 'hub' \| 'realtime' \| 'job' \| 'notification'>` | ✅ | | -| **enabled** | `boolean` | ✅ | | -| **status** | `Enum<'running' \| 'stopped' \| 'degraded' \| 'initializing'>` | ✅ | | -| **version** | `string` | optional | | -| **provider** | `string` | optional | Implementation provider (e.g. "s3" for storage) | -| **features** | `string[]` | optional | List of supported sub-features | - - ---- - diff --git a/content/docs/references/system/tenant.mdx b/content/docs/references/system/tenant.mdx deleted file mode 100644 index 5f43f16cb..000000000 --- a/content/docs/references/system/tenant.mdx +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Tenant -description: Tenant protocol schemas ---- - -Tenant Schema (Multi-Tenant Architecture) - -Defines the tenant/tenancy model for ObjectStack SaaS deployments. - -Supports different levels of data isolation to meet varying security, - -performance, and compliance requirements. - -Isolation Levels: - -- shared_schema: All tenants share the same database and schema (row-level isolation) - -- isolated_schema: Tenants have separate schemas within a shared database - -- isolated_db: Each tenant has a completely separate database - - -**Source:** `packages/spec/src/system/tenant.zod.ts` - - -## TypeScript Usage - -```typescript -import { DatabaseLevelIsolationStrategy, LevelIsolationStrategySchema, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/hub'; -import type { DatabaseLevelIsolationStrategy, LevelIsolationStrategy, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/hub'; - -// Validate data -const result = DatabaseLevelIsolationStrategy.parse(data); -``` - ---- - -## DatabaseLevelIsolationStrategy - -### Properties - -| 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 | - - ---- - -## LevelIsolationStrategySchema - -### Properties - -| 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 | - - ---- - -## RowLevelIsolationStrategy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Row-level isolation strategy | -| **database** | `Object` | optional | Database configuration | -| **performance** | `Object` | optional | Performance settings | - - ---- - -## Tenant - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique tenant identifier | -| **name** | `string` | ✅ | Tenant display name | -| **isolationLevel** | `Enum<'shared_schema' \| 'isolated_schema' \| 'isolated_db'>` | ✅ | | -| **customizations** | `Record` | optional | Custom configuration values | -| **quotas** | `Object` | optional | | - - ---- - -## TenantIsolationConfig - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **strategy** | `string` | ✅ | Row-level isolation strategy | -| **database** | `Object` | optional | Database configuration | -| **performance** | `Object` | optional | Performance settings | - ---- - -#### Option 2 - -### Properties - -| 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 | - ---- - -#### Option 3 - -### Properties - -| 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 | - ---- - - ---- - -## TenantIsolationLevel - -### Allowed Values - -* `shared_schema` -* `isolated_schema` -* `isolated_db` - - ---- - -## TenantQuota - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxUsers** | `integer` | optional | Maximum number of users | -| **maxStorage** | `integer` | optional | Maximum storage in bytes | -| **apiRateLimit** | `integer` | optional | API requests per minute | - - ---- - -## TenantSecurityPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **encryption** | `Object` | optional | Encryption requirements | -| **accessControl** | `Object` | optional | Access control requirements | -| **compliance** | `Object` | optional | Compliance requirements | - - ---- - diff --git a/content/docs/references/system/tracing.mdx b/content/docs/references/system/tracing.mdx deleted file mode 100644 index 049ef465b..000000000 --- a/content/docs/references/system/tracing.mdx +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: Tracing -description: Tracing protocol schemas ---- - -Tracing Protocol - Distributed Tracing & Observability - -Comprehensive distributed tracing based on OpenTelemetry standards: - -- Trace context propagation - -- Span creation and management - -- Sampling strategies - -- Integration with tracing backends (Jaeger, Zipkin, etc.) - -- W3C Trace Context standard compliance - - -**Source:** `packages/spec/src/system/tracing.zod.ts` - - -## TypeScript Usage - -```typescript -import { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system'; -import type { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system'; - -// Validate data -const result = OpenTelemetryCompatibility.parse(data); -``` - ---- - -## OpenTelemetryCompatibility - -OpenTelemetry compatibility configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **sdkVersion** | `string` | optional | OTel SDK version | -| **exporter** | `Object` | ✅ | Exporter configuration | -| **resource** | `Object` | ✅ | Resource attributes | -| **instrumentation** | `Object` | optional | | -| **semanticConventionsVersion** | `string` | optional | Semantic conventions version | - - ---- - -## OtelExporterType - -OpenTelemetry exporter type - -### Allowed Values - -* `otlp_http` -* `otlp_grpc` -* `jaeger` -* `zipkin` -* `console` -* `datadog` -* `honeycomb` -* `lightstep` -* `newrelic` -* `custom` - - ---- - -## SamplingDecision - -Sampling decision - -### Allowed Values - -* `drop` -* `record_only` -* `record_and_sample` - - ---- - -## SamplingStrategyType - -Sampling strategy type - -### Allowed Values - -* `always_on` -* `always_off` -* `trace_id_ratio` -* `rate_limiting` -* `parent_based` -* `probability` -* `composite` -* `custom` - - ---- - -## Span - -OpenTelemetry span - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **context** | `Object` | ✅ | Trace context | -| **name** | `string` | ✅ | Span name | -| **kind** | `Enum<'internal' \| 'server' \| 'client' \| 'producer' \| 'consumer'>` | optional | Span kind | -| **startTime** | `string` | ✅ | Span start time | -| **endTime** | `string` | optional | Span end time | -| **duration** | `number` | optional | Duration in milliseconds | -| **status** | `Object` | optional | | -| **attributes** | `Record` | optional | Span attributes | -| **events** | `Object[]` | optional | | -| **links** | `Object[]` | optional | | -| **resource** | `Record` | optional | Resource attributes | -| **instrumentationLibrary** | `Object` | optional | | - - ---- - -## SpanAttributeValue - -Span attribute value - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -Type: `string` - ---- - -#### Option 2 - -Type: `number` - ---- - -#### Option 3 - -Type: `boolean` - ---- - -#### Option 4 - -Type: `string[]` - ---- - -#### Option 5 - -Type: `number[]` - ---- - -#### Option 6 - -Type: `boolean[]` - ---- - - ---- - -## SpanAttributes - -Span attributes - - ---- - -## SpanEvent - -Span event - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Event name | -| **timestamp** | `string` | ✅ | Event timestamp | -| **attributes** | `Record` | optional | Event attributes | - - ---- - -## SpanKind - -Span kind - -### Allowed Values - -* `internal` -* `server` -* `client` -* `producer` -* `consumer` - - ---- - -## SpanLink - -Span link - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **context** | `Object` | ✅ | Linked trace context | -| **attributes** | `Record` | optional | Link attributes | - - ---- - -## SpanStatus - -Span status - -### Allowed Values - -* `unset` -* `ok` -* `error` - - ---- - -## TraceContext - -Trace context (W3C Trace Context) - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **traceId** | `string` | ✅ | Trace ID (32 hex chars) | -| **spanId** | `string` | ✅ | Span ID (16 hex chars) | -| **traceFlags** | `integer` | optional | Trace flags bitmap | -| **traceState** | `Object` | optional | Trace state | -| **parentSpanId** | `string` | optional | Parent span ID (16 hex chars) | -| **sampled** | `boolean` | optional | | -| **remote** | `boolean` | optional | | - - ---- - -## TraceContextPropagation - -Trace context propagation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **formats** | `Enum<'w3c' \| 'b3' \| 'b3_multi' \| 'jaeger' \| 'xray' \| 'ottrace' \| 'custom'>[]` | optional | | -| **extract** | `boolean` | optional | | -| **inject** | `boolean` | optional | | -| **headers** | `Object` | optional | | -| **baggage** | `Object` | optional | | - - ---- - -## TraceFlags - -Trace flags bitmap - - ---- - -## TracePropagationFormat - -Trace propagation format - -### Allowed Values - -* `w3c` -* `b3` -* `b3_multi` -* `jaeger` -* `xray` -* `ottrace` -* `custom` - - ---- - -## TraceSamplingConfig - -Trace sampling configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>` | ✅ | Sampling strategy | -| **ratio** | `number` | optional | Sample ratio (0-1) | -| **rateLimit** | `number` | optional | Traces per second | -| **parentBased** | `Object` | optional | | -| **composite** | `Object[]` | optional | | -| **rules** | `Object[]` | optional | | -| **customSamplerId** | `string` | optional | Custom sampler identifier | - - ---- - -## TraceState - -Trace state - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **entries** | `Record` | ✅ | Trace state entries | - - ---- - -## TracingConfig - -Tracing configuration - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) | -| **label** | `string` | ✅ | Display label | -| **enabled** | `boolean` | optional | | -| **sampling** | `Object` | optional | Trace sampling configuration | -| **propagation** | `Object` | optional | Trace context propagation | -| **openTelemetry** | `Object` | optional | OpenTelemetry compatibility configuration | -| **spanLimits** | `Object` | optional | | -| **traceIdGenerator** | `Enum<'random' \| 'uuid' \| 'custom'>` | optional | | -| **customTraceIdGeneratorId** | `string` | optional | Custom generator identifier | -| **performance** | `Object` | optional | | - - ---- - diff --git a/content/docs/references/system/translation.mdx b/content/docs/references/system/translation.mdx deleted file mode 100644 index d9dc0af0d..000000000 --- a/content/docs/references/system/translation.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Translation -description: Translation protocol schemas ---- - -Translation Schema - -Supports i18n for labels, messages, and options. - -Example structure: - -```json - -{ - -"en": { "objects": { "account": { "label": "Account" } } }, - -"zh-CN": { "objects": { "account": { "label": "客户" } } } - -} - -``` - - -**Source:** `packages/spec/src/system/translation.zod.ts` - - -## TypeScript Usage - -```typescript -import { Locale, TranslationBundle, TranslationData } from '@objectstack/spec/system'; -import type { Locale, TranslationBundle, TranslationData } from '@objectstack/spec/system'; - -// Validate data -const result = Locale.parse(data); -``` - ---- - -## Locale - -BCP-47 Language Tag (e.g. en-US, zh-CN) - - ---- - -## TranslationBundle - - ---- - -## TranslationData - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **objects** | `Record` | optional | | -| **apps** | `Record` | optional | | -| **messages** | `Record` | optional | | - - ---- - diff --git a/content/docs/references/system/worker.mdx b/content/docs/references/system/worker.mdx deleted file mode 100644 index f889c5649..000000000 --- a/content/docs/references/system/worker.mdx +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Worker -description: Worker protocol schemas ---- - -Worker System Protocol - -Background task processing system with queues, priorities, and retry logic. - -Provides a robust foundation for async task execution similar to: - -- Sidekiq (Ruby) - -- Celery (Python) - -- Bull/BullMQ (Node.js) - -- AWS SQS/Lambda - -Features: - -- Task queues with priorities - -- Task scheduling and retry logic - -- Batch processing - -- Dead letter queues - -- Task monitoring and logging - -@example Basic task - -```typescript - -const task: Task = { - -id: 'task-123', - -type: 'send_email', - -payload: { to: 'user@example.com', subject: 'Welcome' }, - -queue: 'notifications', - -priority: 5 - -}; - -``` - - -**Source:** `packages/spec/src/system/worker.zod.ts` - - -## TypeScript Usage - -```typescript -import { BatchProgress, BatchTask, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerConfig, WorkerStats } from '@objectstack/spec/system'; -import type { BatchProgress, BatchTask, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerConfig, WorkerStats } from '@objectstack/spec/system'; - -// Validate data -const result = BatchProgress.parse(data); -``` - ---- - -## BatchProgress - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **batchId** | `string` | ✅ | Batch job identifier | -| **total** | `integer` | ✅ | Total number of items | -| **processed** | `integer` | optional | Items processed | -| **succeeded** | `integer` | optional | Items succeeded | -| **failed** | `integer` | optional | Items failed | -| **percentage** | `number` | ✅ | Progress percentage | -| **status** | `Enum<'pending' \| 'running' \| 'completed' \| 'failed' \| 'cancelled'>` | ✅ | Batch status | -| **startedAt** | `string` | optional | When batch started | -| **completedAt** | `string` | optional | When batch completed | - - ---- - -## BatchTask - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique batch job identifier | -| **type** | `string` | ✅ | Task type (snake_case) | -| **items** | `any[]` | ✅ | Array of items to process | -| **batchSize** | `integer` | optional | Number of items per batch | -| **queue** | `string` | optional | Queue for batch tasks | -| **priority** | `Enum<'critical' \| 'high' \| 'normal' \| 'low' \| 'background'>` | optional | Batch task priority | -| **parallel** | `boolean` | optional | Process batches in parallel | -| **stopOnError** | `boolean` | optional | Stop batch if any item fails | - - ---- - -## QueueConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Queue name (snake_case) | -| **concurrency** | `integer` | optional | Max concurrent task executions | -| **rateLimit** | `Object` | optional | Rate limit configuration | -| **defaultRetryPolicy** | `Object` | optional | Default retry policy for tasks | -| **deadLetterQueue** | `string` | optional | Dead letter queue name | -| **priority** | `integer` | optional | Queue priority (lower = higher priority) | -| **autoScale** | `Object` | optional | Auto-scaling configuration | - - ---- - -## Task - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique task identifier | -| **type** | `string` | ✅ | Task type (snake_case) | -| **payload** | `any` | optional | Task payload data | -| **queue** | `string` | optional | Queue name | -| **priority** | `Enum<'critical' \| 'high' \| 'normal' \| 'low' \| 'background'>` | optional | Task priority level | -| **retryPolicy** | `Object` | optional | Retry policy configuration | -| **timeoutMs** | `integer` | optional | Task timeout in milliseconds | -| **scheduledAt** | `string` | optional | ISO 8601 datetime to execute task | -| **attempts** | `integer` | optional | Number of execution attempts | -| **status** | `Enum<'pending' \| 'queued' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'timeout' \| 'dead'>` | optional | Current task status | -| **metadata** | `Object` | optional | Task metadata | - - ---- - -## TaskExecutionResult - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **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 | -| **durationMs** | `integer` | optional | Execution duration in milliseconds | -| **startedAt** | `string` | ✅ | When execution started | -| **completedAt** | `string` | optional | When execution completed | -| **attempt** | `integer` | ✅ | Attempt number (1-indexed) | -| **willRetry** | `boolean` | ✅ | Whether task will be retried | - - ---- - -## TaskPriority - -### Allowed Values - -* `critical` -* `high` -* `normal` -* `low` -* `background` - - ---- - -## TaskRetryPolicy - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **maxRetries** | `integer` | optional | Maximum retry attempts | -| **backoffStrategy** | `Enum<'fixed' \| 'linear' \| 'exponential'>` | optional | Backoff strategy between retries | -| **initialDelayMs** | `integer` | optional | Initial retry delay in milliseconds | -| **maxDelayMs** | `integer` | optional | Maximum retry delay in milliseconds | -| **backoffMultiplier** | `number` | optional | Multiplier for exponential backoff | - - ---- - -## TaskStatus - -### Allowed Values - -* `pending` -* `queued` -* `processing` -* `completed` -* `failed` -* `cancelled` -* `timeout` -* `dead` - - ---- - -## WorkerConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Worker name | -| **queues** | `string[]` | ✅ | Queue names to process | -| **queueConfigs** | `Object[]` | optional | Queue configurations | -| **pollIntervalMs** | `integer` | optional | Queue polling interval in milliseconds | -| **visibilityTimeoutMs** | `integer` | optional | How long a task is invisible after being claimed | -| **defaultTimeoutMs** | `integer` | optional | Default task timeout in milliseconds | -| **shutdownTimeoutMs** | `integer` | optional | Graceful shutdown timeout in milliseconds | -| **handlers** | `Record` | optional | Task type handlers | - - ---- - -## WorkerStats - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **workerName** | `string` | ✅ | Worker name | -| **totalProcessed** | `integer` | ✅ | Total tasks processed | -| **succeeded** | `integer` | ✅ | Successful tasks | -| **failed** | `integer` | ✅ | Failed tasks | -| **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 | - - ---- - diff --git a/content/docs/references/ui/action.mdx b/content/docs/references/ui/action.mdx deleted file mode 100644 index b6848f180..000000000 --- a/content/docs/references/ui/action.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Action -description: Action protocol schemas ---- - -Action Parameter Schema - -Defines inputs required before executing an action. - - -**Source:** `packages/spec/src/ui/action.zod.ts` - - -## TypeScript Usage - -```typescript -import { Action, ActionParam } from '@objectstack/spec/ui'; -import type { Action, ActionParam } from '@objectstack/spec/ui'; - -// Validate data -const result = Action.parse(data); -``` - ---- - -## Action - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Machine name (lowercase snake_case) | -| **label** | `string` | ✅ | Display label | -| **icon** | `string` | optional | Icon name | -| **locations** | `Enum<'list_toolbar' \| 'list_item' \| 'record_header' \| 'record_more' \| 'record_related' \| 'global_nav'>[]` | optional | Locations where this action is visible | -| **component** | `Enum<'action:button' \| 'action:icon' \| 'action:menu' \| 'action:group'>` | optional | Visual component override | -| **location** | `any` | optional | | -| **type** | `Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>` | optional | Action functionality type | -| **target** | `string` | optional | URL, Script Name, Flow ID, or API Endpoint | -| **execute** | `string` | optional | Legacy execution logic | -| **params** | `Object[]` | optional | Input parameters required from user | -| **confirmText** | `string` | optional | Confirmation message before execution | -| **successMessage** | `string` | optional | Success message to show after execution | -| **refreshAfter** | `boolean` | optional | Refresh view after execution | -| **visible** | `string` | optional | Formula returning boolean | - - ---- - -## ActionParam - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | | -| **label** | `string` | ✅ | | -| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | ✅ | | -| **required** | `boolean` | optional | | -| **options** | `Object[]` | optional | | - - ---- - diff --git a/content/docs/references/ui/app.mdx b/content/docs/references/ui/app.mdx deleted file mode 100644 index 9d71f1e24..000000000 --- a/content/docs/references/ui/app.mdx +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: App -description: App protocol schemas ---- - -Base Navigation Item Schema - -Shared properties for all navigation types. - -**NAMING CONVENTION:** - -Navigation item IDs are used in URLs and configuration and must be lowercase snake_case. - -@example Good IDs - -- 'menu_accounts' - -- 'page_dashboard' - -- 'nav_settings' - -@example Bad IDs (will be rejected) - -- 'MenuAccounts' (PascalCase) - -- 'Page Dashboard' (spaces) - - -**Source:** `packages/spec/src/ui/app.zod.ts` - - -## TypeScript Usage - -```typescript -import { App, AppBranding, DashboardNavItem, GroupNavItem, NavigationItem, ObjectNavItem, PageNavItem, UrlNavItem } from '@objectstack/spec/ui'; -import type { App, AppBranding, DashboardNavItem, GroupNavItem, NavigationItem, ObjectNavItem, PageNavItem, UrlNavItem } from '@objectstack/spec/ui'; - -// Validate data -const result = App.parse(data); -``` - ---- - -## App - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | App unique machine name (lowercase snake_case) | -| **label** | `string` | ✅ | App display label | -| **version** | `string` | optional | App version | -| **description** | `string` | optional | App description | -| **icon** | `string` | optional | App icon used in the App Launcher | -| **branding** | `Object` | optional | App-specific branding | -| **active** | `boolean` | optional | Whether the app is enabled | -| **isDefault** | `boolean` | optional | Is default app | -| **navigation** | `Object \| Object \| Object \| Object \| Object[]` | optional | Structured navigation menu tree | -| **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 | - - ---- - -## AppBranding - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **primaryColor** | `string` | optional | Primary theme color hex code | -| **logo** | `string` | optional | Custom logo URL for this app | -| **favicon** | `string` | optional | Custom favicon URL for this app | - - ---- - -## DashboardNavItem - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **dashboardName** | `string` | ✅ | Target dashboard name | - - ---- - -## GroupNavItem - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **expanded** | `boolean` | optional | Default expansion state in sidebar | - - ---- - -## NavigationItem - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `object` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | Target object name | -| **viewName** | `string` | optional | Default list view to open. Defaults to "all" | -| **children** | `any[]` | optional | Child navigation items (e.g. specific views) | - ---- - -#### Option 2 - -**Type:** `dashboard` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **dashboardName** | `string` | ✅ | Target dashboard name | - ---- - -#### Option 3 - -**Type:** `page` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **pageName** | `string` | ✅ | Target custom page component name | -| **params** | `Record` | optional | Parameters passed to the page context | - ---- - -#### Option 4 - -**Type:** `url` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Target external URL | -| **target** | `Enum<'_self' \| '_blank'>` | optional | Link target window | - ---- - -#### Option 5 - -**Type:** `group` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **expanded** | `boolean` | optional | Default expansion state in sidebar | -| **children** | `any[]` | ✅ | Child navigation items | - ---- - - ---- - -## ObjectNavItem - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **objectName** | `string` | ✅ | Target object name | -| **viewName** | `string` | optional | Default list view to open. Defaults to "all" | - - ---- - -## PageNavItem - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **pageName** | `string` | ✅ | Target custom page component name | -| **params** | `Record` | optional | Parameters passed to the page context | - - ---- - -## UrlNavItem - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **id** | `string` | ✅ | Unique identifier for this navigation item (lowercase snake_case) | -| **label** | `string` | ✅ | Display proper label | -| **icon** | `string` | optional | Icon name | -| **visible** | `string` | optional | Visibility formula condition | -| **type** | `string` | ✅ | | -| **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 deleted file mode 100644 index 1f6334d15..000000000 --- a/content/docs/references/ui/chart.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Chart -description: Chart protocol schemas ---- - -Unified Chart Type Taxonomy - -Shared by Dashboard and Report widgets. - -Provides a comprehensive set of chart types for data visualization. - - -**Source:** `packages/spec/src/ui/chart.zod.ts` - - -## TypeScript Usage - -```typescript -import { ChartAnnotation, ChartAxis, ChartConfig, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui'; -import type { ChartAnnotation, ChartAxis, ChartConfig, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui'; - -// Validate data -const result = ChartAnnotation.parse(data); -``` - ---- - -## ChartAnnotation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'line' \| 'region'>` | optional | | -| **axis** | `Enum<'x' \| 'y'>` | optional | | -| **value** | `number \| string` | ✅ | Start value | -| **endValue** | `number \| string` | optional | End value for regions | -| **color** | `string` | optional | | -| **label** | `string` | optional | | -| **style** | `Enum<'solid' \| 'dashed' \| 'dotted'>` | optional | | - - ---- - -## ChartAxis - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Data field key | -| **title** | `string` | optional | Axis display title | -| **format** | `string` | optional | Value format string (e.g., "$0,0.00") | -| **min** | `number` | optional | Minimum value | -| **max** | `number` | optional | Maximum value | -| **stepSize** | `number` | optional | Step size for ticks | -| **showGridLines** | `boolean` | optional | | -| **position** | `Enum<'left' \| 'right' \| 'top' \| 'bottom'>` | optional | Axis position | -| **logarithmic** | `boolean` | optional | | - - ---- - -## ChartConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'bi-polar-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'spline' \| 'pie' \| 'donut' \| 'funnel' \| 'pyramid' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'word-cloud' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'choropleth' \| 'bubble-map' \| 'gl-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'candlestick' \| 'stock' \| 'table' \| 'pivot'>` | ✅ | | -| **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 | -| **colors** | `string[]` | optional | Color palette | -| **height** | `number` | optional | Fixed height in pixels | -| **showLegend** | `boolean` | optional | Display legend | -| **showDataLabels** | `boolean` | optional | Display data labels | -| **annotations** | `Object[]` | optional | | -| **interaction** | `Object` | optional | | - - ---- - -## ChartInteraction - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **tooltips** | `boolean` | optional | | -| **zoom** | `boolean` | optional | | -| **brush** | `boolean` | optional | | -| **clickAction** | `string` | optional | Action ID to trigger on click | - - ---- - -## ChartSeries - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Field name or series identifier | -| **label** | `string` | optional | Series display label | -| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'bi-polar-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'spline' \| 'pie' \| 'donut' \| 'funnel' \| 'pyramid' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'word-cloud' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'choropleth' \| 'bubble-map' \| 'gl-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'candlestick' \| 'stock' \| 'table' \| 'pivot'>` | optional | Override chart type for this series | -| **color** | `string` | optional | Series color (hex/rgb/token) | -| **stack** | `string` | optional | Stack identifier to group series | -| **yAxis** | `Enum<'left' \| 'right'>` | optional | Bind to specific Y-Axis | - - ---- - -## ChartType - -### Allowed Values - -* `bar` -* `horizontal-bar` -* `column` -* `grouped-bar` -* `stacked-bar` -* `bi-polar-bar` -* `line` -* `area` -* `stacked-area` -* `step-line` -* `spline` -* `pie` -* `donut` -* `funnel` -* `pyramid` -* `scatter` -* `bubble` -* `treemap` -* `sunburst` -* `sankey` -* `word-cloud` -* `gauge` -* `solid-gauge` -* `metric` -* `kpi` -* `bullet` -* `choropleth` -* `bubble-map` -* `gl-map` -* `heatmap` -* `radar` -* `waterfall` -* `box-plot` -* `violin` -* `candlestick` -* `stock` -* `table` -* `pivot` - - ---- - diff --git a/content/docs/references/ui/component.mdx b/content/docs/references/ui/component.mdx deleted file mode 100644 index 85d9a2236..000000000 --- a/content/docs/references/ui/component.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Component -description: Component protocol schemas ---- - -Empty Properties Schema - - -**Source:** `packages/spec/src/ui/component.zod.ts` - - -## TypeScript Usage - -```typescript -import { PageCardProps, PageHeaderProps, PageTabsProps, RecordDetailsProps, RecordHighlightsProps, RecordRelatedListProps } from '@objectstack/spec/ui'; -import type { PageCardProps, PageHeaderProps, PageTabsProps, RecordDetailsProps, RecordHighlightsProps, RecordRelatedListProps } from '@objectstack/spec/ui'; - -// Validate data -const result = PageCardProps.parse(data); -``` - ---- - -## PageCardProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | optional | | -| **bordered** | `boolean` | optional | | -| **actions** | `string[]` | optional | | -| **body** | `any[]` | optional | Card content components (slot) | -| **footer** | `any[]` | optional | Card footer components (slot) | - - ---- - -## PageHeaderProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | ✅ | Page title | -| **subtitle** | `string` | optional | Page subtitle | -| **icon** | `string` | optional | Icon name | -| **breadcrumb** | `boolean` | optional | Show breadcrumb | -| **actions** | `string[]` | optional | Action IDs to show in header | - - ---- - -## PageTabsProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | | -| **position** | `Enum<'top' \| 'left'>` | optional | | -| **items** | `Object[]` | ✅ | | - - ---- - -## RecordDetailsProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | | -| **layout** | `Enum<'auto' \| 'custom'>` | optional | | -| **sections** | `string[]` | optional | Section IDs to show | - - ---- - -## RecordHighlightsProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fields** | `string[]` | ✅ | Key fields to highlights (max 7) | - - ---- - -## RecordRelatedListProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **objectName** | `string` | ✅ | Related object name | -| **relationshipField** | `string` | ✅ | Field on related object that points to this record | -| **columns** | `string[]` | ✅ | Fields to display | -| **sort** | `string` | optional | | -| **limit** | `number` | optional | | - - ---- - diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx deleted file mode 100644 index 76d20ff91..000000000 --- a/content/docs/references/ui/dashboard.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Dashboard -description: Dashboard protocol schemas ---- - -Dashboard Widget Schema - -A single component on the dashboard grid. - - -**Source:** `packages/spec/src/ui/dashboard.zod.ts` - - -## TypeScript Usage - -```typescript -import { Dashboard, DashboardWidget } from '@objectstack/spec/ui'; -import type { Dashboard, DashboardWidget } from '@objectstack/spec/ui'; - -// Validate data -const result = Dashboard.parse(data); -``` - ---- - -## Dashboard - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Dashboard unique name | -| **label** | `string` | ✅ | Dashboard label | -| **description** | `string` | optional | Dashboard description | -| **widgets** | `Object[]` | ✅ | Widgets to display | - - ---- - -## DashboardWidget - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **title** | `string` | optional | Widget title | -| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'bi-polar-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'spline' \| 'pie' \| 'donut' \| 'funnel' \| 'pyramid' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'word-cloud' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'choropleth' \| 'bubble-map' \| 'gl-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'candlestick' \| 'stock' \| 'table' \| 'pivot'>` | optional | Visualization type | -| **chartConfig** | `Object` | optional | Chart visualization configuration | -| **object** | `string` | optional | Data source object name | -| **filter** | `any` | optional | Data filter criteria | -| **categoryField** | `string` | optional | Field for grouping (X-Axis) | -| **valueField** | `string` | optional | Field for values (Y-Axis) | -| **aggregate** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>` | optional | Aggregate function | -| **layout** | `Object` | ✅ | Grid layout position | -| **options** | `any` | optional | Widget specific configuration | - - ---- - diff --git a/content/docs/references/ui/meta.json b/content/docs/references/ui/meta.json deleted file mode 100644 index d177bd776..000000000 --- a/content/docs/references/ui/meta.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "title": "UI Protocol", - "pages": [ - "action", - "app", - "chart", - "component", - "dashboard", - "page", - "report", - "theme", - "view", - "widget" - ] -} \ No newline at end of file diff --git a/content/docs/references/ui/page.mdx b/content/docs/references/ui/page.mdx deleted file mode 100644 index 19dc6bc1e..000000000 --- a/content/docs/references/ui/page.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Page -description: Page protocol schemas ---- - -Page Region Schema - -A named region in the template where components are dropped. - - -**Source:** `packages/spec/src/ui/page.zod.ts` - - -## TypeScript Usage - -```typescript -import { Page, PageComponent, PageComponentType, PageRegion, PageVariable } from '@objectstack/spec/ui'; -import type { Page, PageComponent, PageComponentType, PageRegion, PageVariable } from '@objectstack/spec/ui'; - -// Validate data -const result = Page.parse(data); -``` - ---- - -## Page - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Page unique name (lowercase snake_case) | -| **label** | `string` | ✅ | | -| **description** | `string` | optional | | -| **type** | `Enum<'record' \| 'home' \| 'app' \| 'utility'>` | optional | | -| **variables** | `Object[]` | optional | Local page state variables | -| **object** | `string` | optional | Bound object (for Record pages) | -| **template** | `string` | optional | Layout template name (e.g. "header-sidebar-main") | -| **regions** | `Object[]` | ✅ | Defined regions with components | -| **isDefault** | `boolean` | optional | | -| **assignedProfiles** | `string[]` | optional | | - - ---- - -## PageComponent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'page:header' \| 'page:footer' \| 'page:sidebar' \| 'page:tabs' \| 'page:accordion' \| 'page:card' \| 'page:section' \| 'record:details' \| 'record:highlights' \| 'record:related_list' \| 'record:activity' \| 'record:chatter' \| 'record:path' \| 'app:launcher' \| 'nav:menu' \| 'nav:breadcrumb' \| 'global:search' \| 'global:notifications' \| 'user:profile' \| 'ai:chat_window' \| 'ai:suggestion'> \| string` | ✅ | Component Type (Standard enum or custom string) | -| **id** | `string` | optional | Unique instance ID | -| **label** | `string` | optional | | -| **properties** | `Record` | ✅ | Component props passed to the widget. See component.zod.ts for schemas. | -| **events** | `Record` | optional | Event handlers map | -| **style** | `Record` | optional | Inline styles or utility classes | -| **className** | `string` | optional | CSS class names | -| **visibility** | `string` | optional | Visibility filter/formula | - - ---- - -## PageComponentType - -### Allowed Values - -* `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` -* `app:launcher` -* `nav:menu` -* `nav:breadcrumb` -* `global:search` -* `global:notifications` -* `user:profile` -* `ai:chat_window` -* `ai:suggestion` - - ---- - -## PageRegion - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Region name (e.g. "sidebar", "main", "header") | -| **width** | `Enum<'small' \| 'medium' \| 'large' \| 'full'>` | optional | | -| **components** | `Object[]` | ✅ | Components in this region | - - ---- - -## PageVariable - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Variable name | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>` | optional | | -| **defaultValue** | `any` | optional | | - - ---- - diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx deleted file mode 100644 index 7b31c0941..000000000 --- a/content/docs/references/ui/report.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Report -description: Report protocol schemas ---- - -Report Type Enum - - -**Source:** `packages/spec/src/ui/report.zod.ts` - - -## TypeScript Usage - -```typescript -import { Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui'; -import type { Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui'; - -// Validate data -const result = Report.parse(data); -``` - ---- - -## Report - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Report unique name | -| **label** | `string` | ✅ | Report label | -| **description** | `string` | optional | | -| **objectName** | `string` | ✅ | Primary object | -| **type** | `Enum<'tabular' \| 'summary' \| 'matrix' \| 'joined'>` | optional | Report format type | -| **columns** | `Object[]` | ✅ | Columns to display | -| **groupingsDown** | `Object[]` | optional | Row groupings | -| **groupingsAcross** | `Object[]` | optional | Column groupings (Matrix only) | -| **filter** | `any` | optional | Filter criteria | -| **chart** | `Object` | optional | Embedded chart configuration | - - ---- - -## ReportChart - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'grouped-bar' \| 'stacked-bar' \| 'bi-polar-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'spline' \| 'pie' \| 'donut' \| 'funnel' \| 'pyramid' \| 'scatter' \| 'bubble' \| 'treemap' \| 'sunburst' \| 'sankey' \| 'word-cloud' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'choropleth' \| 'bubble-map' \| 'gl-map' \| 'heatmap' \| 'radar' \| 'waterfall' \| 'box-plot' \| 'violin' \| 'candlestick' \| 'stock' \| 'table' \| 'pivot'>` | ✅ | | -| **title** | `string` | optional | Chart title | -| **subtitle** | `string` | optional | Chart subtitle | -| **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 | -| **colors** | `string[]` | optional | Color palette | -| **height** | `number` | optional | Fixed height in pixels | -| **showLegend** | `boolean` | optional | Display legend | -| **showDataLabels** | `boolean` | optional | Display data labels | -| **annotations** | `Object[]` | optional | | -| **interaction** | `Object` | optional | | -| **groupBy** | `string` | optional | Additional grouping field | - - ---- - -## ReportColumn - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name | -| **label** | `string` | optional | Override label | -| **aggregate** | `Enum<'sum' \| 'avg' \| 'max' \| 'min' \| 'count' \| 'unique'>` | optional | Aggregation function | - - ---- - -## ReportGrouping - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field to group by | -| **sortOrder** | `Enum<'asc' \| 'desc'>` | optional | | -| **dateGranularity** | `Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional | For date fields | - - ---- - -## ReportType - -### Allowed Values - -* `tabular` -* `summary` -* `matrix` -* `joined` - - ---- - diff --git a/content/docs/references/ui/theme.mdx b/content/docs/references/ui/theme.mdx deleted file mode 100644 index 61bbe4574..000000000 --- a/content/docs/references/ui/theme.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Theme -description: Theme protocol schemas ---- - -Color Palette Schema - -Defines brand colors and their variants. - - -**Source:** `packages/spec/src/ui/theme.zod.ts` - - -## TypeScript Usage - -```typescript -import { Animation, BorderRadius, Breakpoints, ColorPalette, Shadow, Spacing, Theme, ThemeMode, Typography, ZIndex } from '@objectstack/spec/ui'; -import type { Animation, BorderRadius, Breakpoints, ColorPalette, Shadow, Spacing, Theme, ThemeMode, Typography, ZIndex } from '@objectstack/spec/ui'; - -// Validate data -const result = Animation.parse(data); -``` - ---- - -## Animation - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **duration** | `Object` | optional | | -| **timing** | `Object` | optional | | - - ---- - -## BorderRadius - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **none** | `string` | optional | No border radius (0) | -| **sm** | `string` | optional | Small border radius (e.g., 0.125rem) | -| **base** | `string` | optional | Base border radius (e.g., 0.25rem) | -| **md** | `string` | optional | Medium border radius (e.g., 0.375rem) | -| **lg** | `string` | optional | Large border radius (e.g., 0.5rem) | -| **xl** | `string` | optional | Extra large border radius (e.g., 0.75rem) | -| **2xl** | `string` | optional | 2X large border radius (e.g., 1rem) | -| **full** | `string` | optional | Full border radius (50%) | - - ---- - -## Breakpoints - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **xs** | `string` | optional | Extra small breakpoint (e.g., 480px) | -| **sm** | `string` | optional | Small breakpoint (e.g., 640px) | -| **md** | `string` | optional | Medium breakpoint (e.g., 768px) | -| **lg** | `string` | optional | Large breakpoint (e.g., 1024px) | -| **xl** | `string` | optional | Extra large breakpoint (e.g., 1280px) | -| **2xl** | `string` | optional | 2X large breakpoint (e.g., 1536px) | - - ---- - -## ColorPalette - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **primary** | `string` | ✅ | Primary brand color (hex, rgb, or hsl) | -| **secondary** | `string` | optional | Secondary brand color | -| **accent** | `string` | optional | Accent color for highlights | -| **success** | `string` | optional | Success state color (default: green) | -| **warning** | `string` | optional | Warning state color (default: yellow) | -| **error** | `string` | optional | Error state color (default: red) | -| **info** | `string` | optional | Info state color (default: blue) | -| **background** | `string` | optional | Background color | -| **surface** | `string` | optional | Surface/card background color | -| **text** | `string` | optional | Primary text color | -| **textSecondary** | `string` | optional | Secondary text color | -| **border** | `string` | optional | Border color | -| **disabled** | `string` | optional | Disabled state color | -| **primaryLight** | `string` | optional | Lighter shade of primary | -| **primaryDark** | `string` | optional | Darker shade of primary | -| **secondaryLight** | `string` | optional | Lighter shade of secondary | -| **secondaryDark** | `string` | optional | Darker shade of secondary | - - ---- - -## Shadow - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **none** | `string` | optional | No shadow | -| **sm** | `string` | optional | Small shadow | -| **base** | `string` | optional | Base shadow | -| **md** | `string` | optional | Medium shadow | -| **lg** | `string` | optional | Large shadow | -| **xl** | `string` | optional | Extra large shadow | -| **2xl** | `string` | optional | 2X large shadow | -| **inner** | `string` | optional | Inner shadow (inset) | - - ---- - -## Spacing - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **0** | `string` | optional | 0 spacing (0) | -| **1** | `string` | optional | Spacing unit 1 (e.g., 0.25rem) | -| **2** | `string` | optional | Spacing unit 2 (e.g., 0.5rem) | -| **3** | `string` | optional | Spacing unit 3 (e.g., 0.75rem) | -| **4** | `string` | optional | Spacing unit 4 (e.g., 1rem) | -| **5** | `string` | optional | Spacing unit 5 (e.g., 1.25rem) | -| **6** | `string` | optional | Spacing unit 6 (e.g., 1.5rem) | -| **8** | `string` | optional | Spacing unit 8 (e.g., 2rem) | -| **10** | `string` | optional | Spacing unit 10 (e.g., 2.5rem) | -| **12** | `string` | optional | Spacing unit 12 (e.g., 3rem) | -| **16** | `string` | optional | Spacing unit 16 (e.g., 4rem) | -| **20** | `string` | optional | Spacing unit 20 (e.g., 5rem) | -| **24** | `string` | optional | Spacing unit 24 (e.g., 6rem) | - - ---- - -## Theme - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Unique theme identifier (snake_case) | -| **label** | `string` | ✅ | Human-readable theme name | -| **description** | `string` | optional | Theme description | -| **mode** | `Enum<'light' \| 'dark' \| 'auto'>` | optional | 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 | -| **customVars** | `Record` | optional | Custom CSS variables (key-value pairs) | -| **logo** | `Object` | optional | Logo assets | -| **extends** | `string` | optional | Base theme to extend from | - - ---- - -## ThemeMode - -### Allowed Values - -* `light` -* `dark` -* `auto` - - ---- - -## Typography - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **fontFamily** | `Object` | optional | | -| **fontSize** | `Object` | optional | | -| **fontWeight** | `Object` | optional | | -| **lineHeight** | `Object` | optional | | -| **letterSpacing** | `Object` | optional | | - - ---- - -## ZIndex - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **base** | `number` | optional | Base z-index (e.g., 0) | -| **dropdown** | `number` | optional | Dropdown z-index (e.g., 1000) | -| **sticky** | `number` | optional | Sticky z-index (e.g., 1020) | -| **fixed** | `number` | optional | Fixed z-index (e.g., 1030) | -| **modalBackdrop** | `number` | optional | Modal backdrop z-index (e.g., 1040) | -| **modal** | `number` | optional | Modal z-index (e.g., 1050) | -| **popover** | `number` | optional | Popover z-index (e.g., 1060) | -| **tooltip** | `number` | optional | Tooltip z-index (e.g., 1070) | - - ---- - diff --git a/content/docs/references/ui/view.mdx b/content/docs/references/ui/view.mdx deleted file mode 100644 index d83a0b0c6..000000000 --- a/content/docs/references/ui/view.mdx +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: View -description: View protocol schemas ---- - -HTTP Method Enum - - -**Source:** `packages/spec/src/ui/view.zod.ts` - - -## TypeScript Usage - -```typescript -import { CalendarConfig, FormField, FormSection, FormView, GanttConfig, HttpMethod, HttpRequest, KanbanConfig, ListColumn, ListView, NavigationConfig, NavigationMode, PaginationConfig, SelectionConfig, View, ViewData } from '@objectstack/spec/ui'; -import type { CalendarConfig, FormField, FormSection, FormView, GanttConfig, HttpMethod, HttpRequest, KanbanConfig, ListColumn, ListView, NavigationConfig, NavigationMode, PaginationConfig, SelectionConfig, View, ViewData } from '@objectstack/spec/ui'; - -// Validate data -const result = CalendarConfig.parse(data); -``` - ---- - -## CalendarConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **startDateField** | `string` | ✅ | | -| **endDateField** | `string` | optional | | -| **titleField** | `string` | ✅ | | -| **colorField** | `string` | optional | | - - ---- - -## FormField - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name (snake_case) | -| **label** | `string` | optional | Display label override | -| **placeholder** | `string` | optional | Placeholder text | -| **helpText** | `string` | optional | Help/hint text | -| **readonly** | `boolean` | optional | Read-only override | -| **required** | `boolean` | optional | Required override | -| **hidden** | `boolean` | optional | Hidden override | -| **colSpan** | `integer` | optional | Column span in grid layout (1-4) | -| **widget** | `string` | optional | Custom widget/component name | -| **dependsOn** | `string` | optional | Parent field name for cascading | -| **visibleOn** | `string` | optional | Visibility condition expression | - - ---- - -## FormSection - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **label** | `string` | optional | | -| **collapsible** | `boolean` | optional | | -| **collapsed** | `boolean` | optional | | -| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | | -| **fields** | `string \| Object[]` | ✅ | | - - ---- - -## FormView - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>` | optional | | -| **data** | `Object \| Object \| Object` | optional | Data source configuration (defaults to "object" provider) | -| **sections** | `Object[]` | optional | | -| **groups** | `Object[]` | optional | | - - ---- - -## GanttConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **startDateField** | `string` | ✅ | | -| **endDateField** | `string` | ✅ | | -| **titleField** | `string` | ✅ | | -| **progressField** | `string` | optional | | -| **dependenciesField** | `string` | optional | | - - ---- - -## HttpMethod - -### Allowed Values - -* `GET` -* `POST` -* `PUT` -* `PATCH` -* `DELETE` - - ---- - -## HttpRequest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **url** | `string` | ✅ | API endpoint URL | -| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>` | optional | HTTP method | -| **headers** | `Record` | optional | Custom HTTP headers | -| **params** | `Record` | optional | Query parameters | -| **body** | `any` | optional | Request body for POST/PUT/PATCH | - - ---- - -## KanbanConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **groupByField** | `string` | ✅ | Field to group columns by (usually status/select) | -| **summarizeField** | `string` | optional | Field to sum at top of column (e.g. amount) | -| **columns** | `string[]` | ✅ | Fields to show on cards | - - ---- - -## ListColumn - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **field** | `string` | ✅ | Field name (snake_case) | -| **label** | `string` | optional | Display label override | -| **width** | `number` | optional | Column width in pixels | -| **align** | `Enum<'left' \| 'center' \| 'right'>` | optional | Text alignment | -| **hidden** | `boolean` | optional | Hide column by default | -| **sortable** | `boolean` | optional | Allow sorting by this column | -| **resizable** | `boolean` | optional | Allow resizing this column | -| **wrap** | `boolean` | optional | Allow text wrapping | -| **type** | `string` | optional | Renderer type override (e.g., "currency", "date") | -| **link** | `boolean` | optional | Functions as the primary navigation link (triggers View navigation) | -| **action** | `string` | optional | Registered Action ID to execute when clicked | - - ---- - -## ListView - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | optional | Internal view name (lowercase snake_case) | -| **label** | `string` | optional | | -| **type** | `Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map'>` | optional | | -| **data** | `Object \| Object \| Object` | optional | Data source configuration (defaults to "object" provider) | -| **columns** | `string[] \| Object[]` | ✅ | Fields to display as columns | -| **filter** | `any[]` | optional | Filter criteria (JSON Rules) | -| **sort** | `string \| Object[]` | optional | | -| **searchableFields** | `string[]` | optional | Fields enabled for search | -| **filterableFields** | `string[]` | optional | Fields enabled for end-user filtering in the top bar | -| **resizable** | `boolean` | optional | Enable column resizing | -| **striped** | `boolean` | optional | Striped row styling | -| **bordered** | `boolean` | optional | Show borders | -| **selection** | `Object` | optional | Row selection configuration | -| **navigation** | `Object` | optional | Configuration for item click navigation (page, drawer, modal, etc.) | -| **pagination** | `Object` | optional | Pagination configuration | -| **kanban** | `Object` | optional | | -| **calendar** | `Object` | optional | | -| **gantt** | `Object` | optional | | - - ---- - -## NavigationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **mode** | `Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>` | optional | | -| **view** | `string` | optional | Name of the form view to use for details (e.g. "summary_view", "edit_form") | -| **preventNavigation** | `boolean` | optional | Disable standard navigation entirely | -| **openNewTab** | `boolean` | optional | Force open in new tab (applies to page mode) | -| **width** | `string \| number` | optional | Width of the drawer/modal (e.g. "600px", "50%") | - - ---- - -## NavigationMode - -### Allowed Values - -* `page` -* `drawer` -* `modal` -* `split` -* `popover` -* `new_window` -* `none` - - ---- - -## PaginationConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **pageSize** | `integer` | optional | Number of records per page | -| **pageSizeOptions** | `integer[]` | optional | Available page size options | - - ---- - -## SelectionConfig - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `Enum<'none' \| 'single' \| 'multiple'>` | optional | Selection mode | - - ---- - -## View - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **list** | `Object` | optional | | -| **form** | `Object` | optional | | -| **listViews** | `Record` | optional | Additional named list views | -| **formViews** | `Record` | optional | Additional named form views | - - ---- - -## ViewData - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | -| **object** | `string` | ✅ | Target object name | - ---- - -#### Option 2 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | -| **read** | `Object` | optional | Configuration for fetching data | -| **write** | `Object` | optional | Configuration for submitting data (for forms/editable tables) | - ---- - -#### Option 3 - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **provider** | `string` | ✅ | | -| **items** | `any[]` | ✅ | Static data array | - ---- - - ---- - diff --git a/content/docs/references/ui/widget.mdx b/content/docs/references/ui/widget.mdx deleted file mode 100644 index f19324b0f..000000000 --- a/content/docs/references/ui/widget.mdx +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Widget -description: Widget protocol schemas ---- - -Widget Lifecycle Hooks Schema - -Defines lifecycle callbacks for custom widgets inspired by Web Components and React. - -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 https://react.dev/reference/react/Component#component-lifecycle - -@example - -```typescript - -const widget = { - -lifecycle: { - -onMount: "console.log('Widget mounted')", - -onUpdate: "if (prevProps.value !== props.value) { updateUI() }", - -onUnmount: "cleanup()", - -onValidate: "return value.length > 0 ? null : 'Required field'" - -} - -} - -``` - - -**Source:** `packages/spec/src/ui/widget.zod.ts` - - -## TypeScript Usage - -```typescript -import { FieldWidgetProps, WidgetEvent, WidgetLifecycle, WidgetManifest, WidgetProperty, WidgetSource } from '@objectstack/spec/ui'; -import type { FieldWidgetProps, WidgetEvent, WidgetLifecycle, WidgetManifest, WidgetProperty, WidgetSource } from '@objectstack/spec/ui'; - -// Validate data -const result = FieldWidgetProps.parse(data); -``` - ---- - -## FieldWidgetProps - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **value** | `any` | optional | Current field value | -| **readonly** | `boolean` | optional | Read-only mode flag | -| **required** | `boolean` | optional | Required field flag | -| **error** | `string` | optional | Validation error message | -| **field** | `Object` | ✅ | Field schema definition | -| **record** | `Record` | optional | Complete record data | -| **options** | `Record` | optional | Custom widget options | - - ---- - -## WidgetEvent - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Event name | -| **label** | `string` | optional | Human-readable event label | -| **description** | `string` | optional | Event description and usage | -| **bubbles** | `boolean` | optional | Whether event bubbles | -| **cancelable** | `boolean` | optional | Whether event is cancelable | -| **payload** | `Record` | optional | Event payload schema | - - ---- - -## WidgetLifecycle - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **onMount** | `string` | optional | Initialization code when widget mounts | -| **onUpdate** | `string` | optional | Code to run when props change | -| **onUnmount** | `string` | optional | Cleanup code when widget unmounts | -| **onValidate** | `string` | optional | Custom validation logic | -| **onFocus** | `string` | optional | Code to run on focus | -| **onBlur** | `string` | optional | Code to run on blur | -| **onError** | `string` | optional | Error handling code | - - ---- - -## WidgetManifest - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Widget identifier (snake_case) | -| **label** | `string` | ✅ | Widget display name | -| **description** | `string` | optional | Widget description | -| **version** | `string` | optional | Widget version (semver) | -| **author** | `string` | optional | Widget author | -| **icon** | `string` | optional | Widget icon | -| **fieldTypes** | `string[]` | optional | Supported field types | -| **category** | `Enum<'input' \| 'display' \| 'picker' \| 'editor' \| 'custom'>` | optional | 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 | -| **screenshots** | `string[]` | optional | Screenshot URLs | -| **documentation** | `string` | optional | Documentation URL | -| **license** | `string` | optional | License (SPDX identifier) | -| **tags** | `string[]` | optional | Tags for categorization | - - ---- - -## WidgetProperty - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **name** | `string` | ✅ | Property name (camelCase) | -| **label** | `string` | optional | Human-readable label | -| **type** | `Enum<'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'function' \| 'any'>` | ✅ | TypeScript type | -| **required** | `boolean` | optional | Whether property is required | -| **default** | `any` | optional | Default value | -| **description** | `string` | optional | Property description | -| **validation** | `Record` | optional | Validation rules | -| **category** | `string` | optional | Property category | - - ---- - -## WidgetSource - -### Union Options - -This schema accepts one of the following structures: - -#### Option 1 - -**Type:** `npm` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **packageName** | `string` | ✅ | NPM package name | -| **version** | `string` | optional | | -| **exportName** | `string` | optional | Named export (default: default) | - ---- - -#### Option 2 - -**Type:** `remote` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **url** | `string` | ✅ | Remote entry URL (.js) | -| **moduleName** | `string` | ✅ | Exposed module name | -| **scope** | `string` | ✅ | Remote scope name | - ---- - -#### Option 3 - -**Type:** `inline` - -### Properties - -| Property | Type | Required | Description | -| :--- | :--- | :--- | :--- | -| **type** | `string` | ✅ | | -| **code** | `string` | ✅ | JavaScript code body | - ---- - - ---- - diff --git a/packages/spec/scripts/build-docs.ts b/packages/spec/scripts/build-docs.ts index ffd6425b4..b709b84f2 100644 --- a/packages/spec/scripts/build-docs.ts +++ b/packages/spec/scripts/build-docs.ts @@ -329,7 +329,11 @@ Object.entries(CATEGORIES).forEach(([category, title]) => { // BUT 'index' must be in 'meta.json' pages? No, index is implicit usually. // However, Fumadocs often treats folder/index.mdx as the page for the folder. - fs.writeFileSync(path.join(DOCS_ROOT, category, 'index.mdx'), mdx); + // Ensure directory exists before writing + const categoryDir = path.join(DOCS_ROOT, category); + if (!fs.existsSync(categoryDir)) fs.mkdirSync(categoryDir, { recursive: true }); + + fs.writeFileSync(path.join(categoryDir, 'index.mdx'), mdx); console.log(`✓ Generated ${category}/index.mdx`); }); From 466df4b7311ec67d3ba328d8fe5dbabb6d621b9c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 02:28:11 +0000 Subject: [PATCH 3/6] fix: ensure category directories exist before writing index.mdx and run gen:schema before gen:docs Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- apps/docs/package.json | 2 +- content/docs/references/ai/mcp.mdx | 149 +++++++++++++++ content/docs/references/api/dispatcher.mdx | 55 ++++++ content/docs/references/api/object.mdx | 26 +++ .../docs/references/api/plugin-rest-api.mdx | 170 ++++++++++++++++++ content/docs/references/api/versioning.mdx | 59 ++++++ content/docs/references/hub/license.mdx | 41 +++++ content/docs/references/hub/meta.json | 10 ++ .../docs/references/hub/plugin-registry.mdx | 51 ++++++ .../docs/references/hub/plugin-security.mdx | 86 +++++++++ .../docs/references/hub/registry-config.mdx | 36 ++++ content/docs/references/hub/tenant.mdx | 61 +++++++ .../docs/references/kernel/plugin-runtime.mdx | 87 +++++++++ content/docs/references/shared/enums.mdx | 48 +++++ .../shared/metadata-persistence.mdx | 26 +++ .../docs/references/shared/metadata-types.mdx | 28 +++ content/docs/references/studio/meta.json | 6 + content/docs/references/studio/plugin.mdx | 169 +++++++++++++++++ .../docs/references/system/core-services.mdx | 58 ++++++ 19 files changed, 1167 insertions(+), 1 deletion(-) create mode 100644 content/docs/references/ai/mcp.mdx create mode 100644 content/docs/references/api/dispatcher.mdx create mode 100644 content/docs/references/api/object.mdx create mode 100644 content/docs/references/api/plugin-rest-api.mdx create mode 100644 content/docs/references/api/versioning.mdx create mode 100644 content/docs/references/hub/license.mdx create mode 100644 content/docs/references/hub/meta.json create mode 100644 content/docs/references/hub/plugin-registry.mdx create mode 100644 content/docs/references/hub/plugin-security.mdx create mode 100644 content/docs/references/hub/registry-config.mdx create mode 100644 content/docs/references/hub/tenant.mdx create mode 100644 content/docs/references/kernel/plugin-runtime.mdx create mode 100644 content/docs/references/shared/enums.mdx create mode 100644 content/docs/references/shared/metadata-persistence.mdx create mode 100644 content/docs/references/shared/metadata-types.mdx create mode 100644 content/docs/references/studio/meta.json create mode 100644 content/docs/references/studio/plugin.mdx create mode 100644 content/docs/references/system/core-services.mdx diff --git a/apps/docs/package.json b/apps/docs/package.json index f8995f3b4..060a5af56 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -6,7 +6,7 @@ "license": "Apache-2.0", "scripts": { "dev": "next dev", - "build": "pnpm --filter @objectstack/spec gen:docs && next build", + "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && next build", "site:start": "next start", "site:lint": "next lint" }, diff --git a/content/docs/references/ai/mcp.mdx b/content/docs/references/ai/mcp.mdx new file mode 100644 index 000000000..8fd5b9c4f --- /dev/null +++ b/content/docs/references/ai/mcp.mdx @@ -0,0 +1,149 @@ +--- +title: Mcp +description: Mcp protocol schemas +--- + +Model Context Protocol (MCP) + +Defines the protocol for connecting AI assistants to external tools, data sources, + +and resources. MCP enables AI models to access contextual information, invoke + +functions, and interact with external systems in a standardized way. + +Architecture Alignment: + +- Anthropic Model Context Protocol (MCP) + +- OpenAI Function Calling / Tools + +- LangChain Tool Interface + +- Microsoft Semantic Kernel Plugins + +Use Cases: + +- Connect AI agents to ObjectStack data (Objects, Views, Reports) + +- Expose business logic as callable tools (Workflows, Flows, Actions) + +- Provide dynamic context to AI models (User profile, Recent activity) + +- Enable AI to read and modify data through standardized interfaces + + +**Source:** `packages/spec/src/ai/mcp.zod.ts` + + +## TypeScript Usage + +```typescript +import { MCPCapability, MCPClientConfig, MCPPrompt, MCPPromptArgument, MCPPromptMessage, MCPPromptRequest, MCPPromptResponse, MCPResource, MCPResourceRequest, MCPResourceResponse, MCPResourceTemplate, MCPResourceType, MCPServerConfig, MCPServerInfo, MCPTool, MCPToolCallRequest, MCPToolCallResponse, MCPToolParameter, MCPTransportConfig, MCPTransportType } from '@objectstack/spec/ai'; +import type { MCPCapability, MCPClientConfig, MCPPrompt, MCPPromptArgument, MCPPromptMessage, MCPPromptRequest, MCPPromptResponse, MCPResource, MCPResourceRequest, MCPResourceResponse, MCPResourceTemplate, MCPResourceType, MCPServerConfig, MCPServerInfo, MCPTool, MCPToolCallRequest, MCPToolCallResponse, MCPToolParameter, MCPTransportConfig, MCPTransportType } from '@objectstack/spec/ai'; + +// Validate data +const result = MCPCapability.parse(data); +``` + +--- + +## MCPCapability + + +--- + +## MCPClientConfig + + +--- + +## MCPPrompt + + +--- + +## MCPPromptArgument + + +--- + +## MCPPromptMessage + + +--- + +## MCPPromptRequest + + +--- + +## MCPPromptResponse + + +--- + +## MCPResource + + +--- + +## MCPResourceRequest + + +--- + +## MCPResourceResponse + + +--- + +## MCPResourceTemplate + + +--- + +## MCPResourceType + + +--- + +## MCPServerConfig + + +--- + +## MCPServerInfo + + +--- + +## MCPTool + + +--- + +## MCPToolCallRequest + + +--- + +## MCPToolCallResponse + + +--- + +## MCPToolParameter + + +--- + +## MCPTransportConfig + + +--- + +## MCPTransportType + + +--- + diff --git a/content/docs/references/api/dispatcher.mdx b/content/docs/references/api/dispatcher.mdx new file mode 100644 index 000000000..75b55e3c3 --- /dev/null +++ b/content/docs/references/api/dispatcher.mdx @@ -0,0 +1,55 @@ +--- +title: Dispatcher +description: Dispatcher protocol schemas +--- + +# HttpDispatcher Protocol + +Defines how the ObjectStack HttpDispatcher routes incoming API requests + +to the correct kernel service based on URL prefix matching. + +The dispatcher is the central routing component that: + +1. Matches incoming request URLs against registered route prefixes + +2. Delegates to the corresponding CoreService implementation + +3. Returns 503 Service Unavailable when a service is not registered + +4. Supports dynamic route registration from plugins via contributes.routes + +Architecture alignment: + +- Kubernetes: API server aggregation layer + +- Eclipse: Extension registry routing + +- VS Code: Command palette routing + + +**Source:** `packages/spec/src/api/dispatcher.zod.ts` + + +## TypeScript Usage + +```typescript +import { DispatcherConfig, DispatcherRoute } from '@objectstack/spec/api'; +import type { DispatcherConfig, DispatcherRoute } from '@objectstack/spec/api'; + +// Validate data +const result = DispatcherConfig.parse(data); +``` + +--- + +## DispatcherConfig + + +--- + +## DispatcherRoute + + +--- + diff --git a/content/docs/references/api/object.mdx b/content/docs/references/api/object.mdx new file mode 100644 index 000000000..00dab6880 --- /dev/null +++ b/content/docs/references/api/object.mdx @@ -0,0 +1,26 @@ +--- +title: Object +description: Object protocol schemas +--- + + +**Source:** `packages/spec/src/api/object.zod.ts` + + +## TypeScript Usage + +```typescript +import { VersioningConfig } from '@objectstack/spec/api'; +import type { VersioningConfig } from '@objectstack/spec/api'; + +// Validate data +const result = VersioningConfig.parse(data); +``` + +--- + +## VersioningConfig + + +--- + diff --git a/content/docs/references/api/plugin-rest-api.mdx b/content/docs/references/api/plugin-rest-api.mdx new file mode 100644 index 000000000..fabbeefee --- /dev/null +++ b/content/docs/references/api/plugin-rest-api.mdx @@ -0,0 +1,170 @@ +--- +title: Plugin Rest Api +description: Plugin Rest Api protocol schemas +--- + +REST API Plugin Protocol + +Defines the schema for REST API plugins that register Discovery, Metadata, + +Data CRUD, Batch, and Permission routes with the HTTP Dispatcher. + +This plugin type implements Phase 2 of the API Protocol implementation plan, + +providing standardized REST endpoints with: + +- Request validation middleware using Zod schemas + +- Response envelope wrapping with BaseResponseSchema + +- Error handling using ApiErrorSchema + +- OpenAPI documentation auto-generation + +Features: + +- Route registration for core API endpoints + +- Automatic schema-based validation + +- Standardized request/response envelopes + +- OpenAPI/Swagger documentation generation + +Architecture Alignment: + +- Salesforce: REST API with metadata and data CRUD + +- Microsoft Dynamics: Web API with entity operations + +- Strapi: Auto-generated REST endpoints from schemas + +@example Plugin Manifest + +```typescript + +{ + +"name": "rest_api", + +"version": "1.0.0", + +"type": "server", + +"contributes": { + +"routes": [ + +{ + +"prefix": "/api/v1/discovery", + +"service": "metadata", + +"methods": ["getDiscovery"], + +"middleware": [ + +{ "name": "response_envelope", "type": "transformation", "enabled": true } + +] + +}, + +{ + +"prefix": "/api/v1/meta", + +"service": "metadata", + +"methods": ["getMetaTypes", "getMetaItems", "getMetaItem", "saveMetaItem"], + +"middleware": [ + +{ "name": "auth", "type": "authentication", "enabled": true }, + +{ "name": "request_validation", "type": "validation", "enabled": true } + +] + +}, + +{ + +"prefix": "/api/v1/data", + +"service": "data", + +"methods": ["findData", "getData", "createData", "updateData", "deleteData"] + +} + +] + +} + +} + +``` + + +**Source:** `packages/spec/src/api/plugin-rest-api.zod.ts` + + +## TypeScript Usage + +```typescript +import { ErrorHandlingConfig, OpenApiGenerationConfig, RequestValidationConfig, ResponseEnvelopeConfig, RestApiEndpoint, RestApiPluginConfig, RestApiRouteCategory, RestApiRouteRegistration, ValidationMode } from '@objectstack/spec/api'; +import type { ErrorHandlingConfig, OpenApiGenerationConfig, RequestValidationConfig, ResponseEnvelopeConfig, RestApiEndpoint, RestApiPluginConfig, RestApiRouteCategory, RestApiRouteRegistration, ValidationMode } from '@objectstack/spec/api'; + +// Validate data +const result = ErrorHandlingConfig.parse(data); +``` + +--- + +## ErrorHandlingConfig + + +--- + +## OpenApiGenerationConfig + + +--- + +## RequestValidationConfig + + +--- + +## ResponseEnvelopeConfig + + +--- + +## RestApiEndpoint + + +--- + +## RestApiPluginConfig + + +--- + +## RestApiRouteCategory + + +--- + +## RestApiRouteRegistration + + +--- + +## ValidationMode + + +--- + diff --git a/content/docs/references/api/versioning.mdx b/content/docs/references/api/versioning.mdx new file mode 100644 index 000000000..26e668587 --- /dev/null +++ b/content/docs/references/api/versioning.mdx @@ -0,0 +1,59 @@ +--- +title: Versioning +description: Versioning protocol schemas +--- + +# API Versioning Protocol + +Defines how API versions are negotiated between client and server. + +Supports multiple versioning strategies and deprecation lifecycle management. + +Architecture Alignment: + +- Salesforce: URL path versioning (v57.0, v58.0) + +- Stripe: Date-based versioning (2024-01-01) + +- Kubernetes: API group versioning (v1, v1beta1) + +- GitHub: Accept header versioning (application/vnd.github.v3+json) + +- Microsoft Graph: URL path versioning (v1.0, beta) + + +**Source:** `packages/spec/src/api/versioning.zod.ts` + + +## TypeScript Usage + +```typescript +import { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningStrategy } from '@objectstack/spec/api'; +import type { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningStrategy } from '@objectstack/spec/api'; + +// Validate data +const result = VersionDefinition.parse(data); +``` + +--- + +## VersionDefinition + + +--- + +## VersionNegotiationResponse + + +--- + +## VersionStatus + + +--- + +## VersioningStrategy + + +--- + diff --git a/content/docs/references/hub/license.mdx b/content/docs/references/hub/license.mdx new file mode 100644 index 000000000..e6c3d763e --- /dev/null +++ b/content/docs/references/hub/license.mdx @@ -0,0 +1,41 @@ +--- +title: License +description: License protocol schemas +--- + + +**Source:** `packages/spec/src/hub/license.zod.ts` + + +## TypeScript Usage + +```typescript +import { Feature, License, LicenseMetricType, Plan } from '@objectstack/spec/hub'; +import type { Feature, License, LicenseMetricType, Plan } from '@objectstack/spec/hub'; + +// Validate data +const result = Feature.parse(data); +``` + +--- + +## Feature + + +--- + +## License + + +--- + +## LicenseMetricType + + +--- + +## Plan + + +--- + diff --git a/content/docs/references/hub/meta.json b/content/docs/references/hub/meta.json new file mode 100644 index 000000000..631a94902 --- /dev/null +++ b/content/docs/references/hub/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Hub Protocol", + "pages": [ + "license", + "plugin-registry", + "plugin-security", + "registry-config", + "tenant" + ] +} \ No newline at end of file diff --git a/content/docs/references/hub/plugin-registry.mdx b/content/docs/references/hub/plugin-registry.mdx new file mode 100644 index 000000000..dca231b56 --- /dev/null +++ b/content/docs/references/hub/plugin-registry.mdx @@ -0,0 +1,51 @@ +--- +title: Plugin Registry +description: Plugin Registry protocol schemas +--- + + +**Source:** `packages/spec/src/hub/plugin-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { PluginInstallConfig, PluginQualityMetrics, PluginRegistryEntry, PluginSearchFilters, PluginStatistics, PluginVendor } from '@objectstack/spec/hub'; +import type { PluginInstallConfig, PluginQualityMetrics, PluginRegistryEntry, PluginSearchFilters, PluginStatistics, PluginVendor } from '@objectstack/spec/hub'; + +// Validate data +const result = PluginInstallConfig.parse(data); +``` + +--- + +## PluginInstallConfig + + +--- + +## PluginQualityMetrics + + +--- + +## PluginRegistryEntry + + +--- + +## PluginSearchFilters + + +--- + +## PluginStatistics + + +--- + +## PluginVendor + + +--- + diff --git a/content/docs/references/hub/plugin-security.mdx b/content/docs/references/hub/plugin-security.mdx new file mode 100644 index 000000000..93821daf6 --- /dev/null +++ b/content/docs/references/hub/plugin-security.mdx @@ -0,0 +1,86 @@ +--- +title: Plugin Security +description: Plugin Security protocol schemas +--- + + +**Source:** `packages/spec/src/hub/plugin-security.zod.ts` + + +## TypeScript Usage + +```typescript +import { DependencyGraph, DependencyGraphNode, PackageDependency, PackageDependencyConflict, PackageDependencyResolutionResult, PluginProvenance, PluginTrustScore, SBOM, SBOMEntry, SecurityPolicy, SecurityScanResult, SecurityVulnerability, VulnerabilitySeverity } from '@objectstack/spec/hub'; +import type { DependencyGraph, DependencyGraphNode, PackageDependency, PackageDependencyConflict, PackageDependencyResolutionResult, PluginProvenance, PluginTrustScore, SBOM, SBOMEntry, SecurityPolicy, SecurityScanResult, SecurityVulnerability, VulnerabilitySeverity } from '@objectstack/spec/hub'; + +// Validate data +const result = DependencyGraph.parse(data); +``` + +--- + +## DependencyGraph + + +--- + +## DependencyGraphNode + + +--- + +## PackageDependency + + +--- + +## PackageDependencyConflict + + +--- + +## PackageDependencyResolutionResult + + +--- + +## PluginProvenance + + +--- + +## PluginTrustScore + + +--- + +## SBOM + + +--- + +## SBOMEntry + + +--- + +## SecurityPolicy + + +--- + +## SecurityScanResult + + +--- + +## SecurityVulnerability + + +--- + +## VulnerabilitySeverity + + +--- + diff --git a/content/docs/references/hub/registry-config.mdx b/content/docs/references/hub/registry-config.mdx new file mode 100644 index 000000000..a6ee4caab --- /dev/null +++ b/content/docs/references/hub/registry-config.mdx @@ -0,0 +1,36 @@ +--- +title: Registry Config +description: Registry Config protocol schemas +--- + + +**Source:** `packages/spec/src/hub/registry-config.zod.ts` + + +## TypeScript Usage + +```typescript +import { RegistryConfig, RegistrySyncPolicy, RegistryUpstream } from '@objectstack/spec/hub'; +import type { RegistryConfig, RegistrySyncPolicy, RegistryUpstream } from '@objectstack/spec/hub'; + +// Validate data +const result = RegistryConfig.parse(data); +``` + +--- + +## RegistryConfig + + +--- + +## RegistrySyncPolicy + + +--- + +## RegistryUpstream + + +--- + diff --git a/content/docs/references/hub/tenant.mdx b/content/docs/references/hub/tenant.mdx new file mode 100644 index 000000000..82f9407b4 --- /dev/null +++ b/content/docs/references/hub/tenant.mdx @@ -0,0 +1,61 @@ +--- +title: Tenant +description: Tenant protocol schemas +--- + + +**Source:** `packages/spec/src/hub/tenant.zod.ts` + + +## TypeScript Usage + +```typescript +import { DatabaseLevelIsolationStrategy, LevelIsolationStrategySchema, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/hub'; +import type { DatabaseLevelIsolationStrategy, LevelIsolationStrategy, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/hub'; + +// Validate data +const result = DatabaseLevelIsolationStrategy.parse(data); +``` + +--- + +## DatabaseLevelIsolationStrategy + + +--- + +## LevelIsolationStrategySchema + + +--- + +## RowLevelIsolationStrategy + + +--- + +## Tenant + + +--- + +## TenantIsolationConfig + + +--- + +## TenantIsolationLevel + + +--- + +## TenantQuota + + +--- + +## TenantSecurityPolicy + + +--- + diff --git a/content/docs/references/kernel/plugin-runtime.mdx b/content/docs/references/kernel/plugin-runtime.mdx new file mode 100644 index 000000000..61e61e34a --- /dev/null +++ b/content/docs/references/kernel/plugin-runtime.mdx @@ -0,0 +1,87 @@ +--- +title: Plugin Runtime +description: Plugin Runtime protocol schemas +--- + +# Plugin Runtime Management Protocol + +Defines the protocol for dynamic plugin loading, unloading, and discovery + +at runtime. Addresses the "Dynamic Loading" gap in the microkernel architecture + +by enabling plugins to be loaded and unloaded without restarting the kernel. + +Inspired by: + +- OSGi Dynamic Module System (bundle lifecycle) + +- Kubernetes Operator pattern (reconciliation loop) + +- VS Code Extension Host (activation events) + +This protocol enables: + +- Runtime load/unload of plugins without kernel restart + +- Plugin discovery from registries and local filesystem + +- Activation events (load plugin only when needed) + +- Safe unload with dependency awareness + + +**Source:** `packages/spec/src/kernel/plugin-runtime.zod.ts` + + +## TypeScript Usage + +```typescript +import { DynamicLoadRequest, DynamicLoadingConfig, DynamicPluginOperation, DynamicPluginResult, DynamicUnloadRequest, PluginDiscoveryConfig, PluginDiscoverySource, PluginSource } from '@objectstack/spec/kernel'; +import type { DynamicLoadRequest, DynamicLoadingConfig, DynamicPluginOperation, DynamicPluginResult, DynamicUnloadRequest, PluginDiscoveryConfig, PluginDiscoverySource, PluginSource } from '@objectstack/spec/kernel'; + +// Validate data +const result = DynamicLoadRequest.parse(data); +``` + +--- + +## DynamicLoadRequest + + +--- + +## DynamicLoadingConfig + + +--- + +## DynamicPluginOperation + + +--- + +## DynamicPluginResult + + +--- + +## DynamicUnloadRequest + + +--- + +## PluginDiscoveryConfig + + +--- + +## PluginDiscoverySource + + +--- + +## PluginSource + + +--- + diff --git a/content/docs/references/shared/enums.mdx b/content/docs/references/shared/enums.mdx new file mode 100644 index 000000000..4d41e5571 --- /dev/null +++ b/content/docs/references/shared/enums.mdx @@ -0,0 +1,48 @@ +--- +title: Enums +description: Enums protocol schemas +--- + +Aggregation functions used across query, data-engine, analytics, field + + +**Source:** `packages/spec/src/shared/enums.zod.ts` + + +## TypeScript Usage + +```typescript +import { AggregationFunctionEnum, CacheStrategyEnum, IsolationLevelEnum, MutationEventEnum, SortDirectionEnum } from '@objectstack/spec/shared'; +import type { AggregationFunctionEnum, CacheStrategyEnum, IsolationLevelEnum, MutationEventEnum, SortDirectionEnum } from '@objectstack/spec/shared'; + +// Validate data +const result = AggregationFunctionEnum.parse(data); +``` + +--- + +## AggregationFunctionEnum + + +--- + +## CacheStrategyEnum + + +--- + +## IsolationLevelEnum + + +--- + +## MutationEventEnum + + +--- + +## SortDirectionEnum + + +--- + diff --git a/content/docs/references/shared/metadata-persistence.mdx b/content/docs/references/shared/metadata-persistence.mdx new file mode 100644 index 000000000..e91071b4e --- /dev/null +++ b/content/docs/references/shared/metadata-persistence.mdx @@ -0,0 +1,26 @@ +--- +title: Metadata Persistence +description: Metadata Persistence protocol schemas +--- + + +**Source:** `packages/spec/src/shared/metadata-persistence.zod.ts` + + +## TypeScript Usage + +```typescript +import { MetadataFormat } from '@objectstack/spec/shared'; +import type { MetadataFormat } from '@objectstack/spec/shared'; + +// Validate data +const result = MetadataFormat.parse(data); +``` + +--- + +## MetadataFormat + + +--- + diff --git a/content/docs/references/shared/metadata-types.mdx b/content/docs/references/shared/metadata-types.mdx new file mode 100644 index 000000000..f7d62379c --- /dev/null +++ b/content/docs/references/shared/metadata-types.mdx @@ -0,0 +1,28 @@ +--- +title: Metadata Types +description: Metadata Types protocol schemas +--- + +Supported metadata file formats + + +**Source:** `packages/spec/src/shared/metadata-types.zod.ts` + + +## TypeScript Usage + +```typescript +import { BaseMetadataRecord } from '@objectstack/spec/shared'; +import type { BaseMetadataRecord } from '@objectstack/spec/shared'; + +// Validate data +const result = BaseMetadataRecord.parse(data); +``` + +--- + +## BaseMetadataRecord + + +--- + diff --git a/content/docs/references/studio/meta.json b/content/docs/references/studio/meta.json new file mode 100644 index 000000000..0c82b1dd8 --- /dev/null +++ b/content/docs/references/studio/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Studio Protocol", + "pages": [ + "plugin" + ] +} \ No newline at end of file diff --git a/content/docs/references/studio/plugin.mdx b/content/docs/references/studio/plugin.mdx new file mode 100644 index 000000000..e75e77793 --- /dev/null +++ b/content/docs/references/studio/plugin.mdx @@ -0,0 +1,169 @@ +--- +title: Plugin +description: Plugin protocol schemas +--- + +@module studio/plugin + +Studio Plugin Protocol + +Defines the specification for Studio plugins — a VS Code-like extension model + +that allows each metadata type to contribute custom viewers, designers, + +sidebar groups, actions, and commands. + +## Architecture + +Like VS Code extensions, Studio plugins have two layers: + +1. **Manifest (Declarative)** — JSON-serializable contribution points + +2. **Activation (Imperative)** — Runtime registration of React components & handlers + +``` + +┌─────────────────────────────────────────────────────────┐ + +│ Studio Host │ + +│ ┌───────────────────────────────────────────────────┐ │ + +│ │ Plugin Registry │ │ + +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ + +│ │ │ Object │ │ Flow │ │ Agent │ ... │ │ + +│ │ │ Plugin │ │ Plugin │ │ Plugin │ │ │ + +│ │ └──────────┘ └──────────┘ └──────────┘ │ │ + +│ └───────────────────────────────────────────────────┘ │ + +│ │ + +│ ┌─── Sidebar ───┐ ┌──── Main Panel ────────────────┐ │ + +│ │ [plugin icons] │ │ PluginHost renders viewer │ │ + +│ │ [plugin groups]│ │ from highest-priority plugin │ │ + +│ └────────────────┘ └────────────────────────────────┘ │ + +└─────────────────────────────────────────────────────────┘ + +``` + +@example + +```typescript + +import { StudioPluginManifestSchema } from '@objectstack/spec/studio'; + +const manifest = StudioPluginManifestSchema.parse({ + +id: 'objectstack.object-designer', + +name: 'Object Designer', + +version: '1.0.0', + +contributes: { + +metadataViewers: [{ + +id: 'object-explorer', + +metadataTypes: ['object', 'objects'], + +label: 'Object Explorer', + +priority: 100, + +modes: ['preview', 'design', 'data'], + +}], + +}, + +}); + +``` + + +**Source:** `packages/spec/src/studio/plugin.zod.ts` + + +## TypeScript Usage + +```typescript +import { ActionContribution, ActionLocation, ActivationEvent, CommandContribution, MetadataIconContribution, MetadataViewerContribution, PanelContribution, PanelLocation, SidebarGroupContribution, StudioPluginContributions, StudioPluginManifest, ViewMode } from '@objectstack/spec/studio'; +import type { ActionContribution, ActionLocation, ActivationEvent, CommandContribution, MetadataIconContribution, MetadataViewerContribution, PanelContribution, PanelLocation, SidebarGroupContribution, StudioPluginContributions, StudioPluginManifest, ViewMode } from '@objectstack/spec/studio'; + +// Validate data +const result = ActionContribution.parse(data); +``` + +--- + +## ActionContribution + + +--- + +## ActionLocation + + +--- + +## ActivationEvent + + +--- + +## CommandContribution + + +--- + +## MetadataIconContribution + + +--- + +## MetadataViewerContribution + + +--- + +## PanelContribution + + +--- + +## PanelLocation + + +--- + +## SidebarGroupContribution + + +--- + +## StudioPluginContributions + + +--- + +## StudioPluginManifest + + +--- + +## ViewMode + + +--- + diff --git a/content/docs/references/system/core-services.mdx b/content/docs/references/system/core-services.mdx new file mode 100644 index 000000000..3a1101961 --- /dev/null +++ b/content/docs/references/system/core-services.mdx @@ -0,0 +1,58 @@ +--- +title: Core Services +description: Core Services protocol schemas +--- + +# Service Registry Protocol + +Defines the standard built-in services that constitute the ObjectStack Kernel. + +This registry is used by the `ObjectKernel` and `HttpDispatcher` to: + +1. Verify service availability. + +2. Route requests to the correct service handler. + +3. Type-check service interactions. + + +**Source:** `packages/spec/src/system/core-services.zod.ts` + + +## TypeScript Usage + +```typescript +import { CoreServiceName, KernelServiceMap, ServiceConfig, ServiceCriticality, ServiceStatus } from '@objectstack/spec/system'; +import type { CoreServiceName, KernelServiceMap, ServiceConfig, ServiceCriticality, ServiceStatus } from '@objectstack/spec/system'; + +// Validate data +const result = CoreServiceName.parse(data); +``` + +--- + +## CoreServiceName + + +--- + +## KernelServiceMap + + +--- + +## ServiceConfig + + +--- + +## ServiceCriticality + + +--- + +## ServiceStatus + + +--- + From 6fc272b42fc09447bc71f5394dfbb897847d2bd0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 02:29:51 +0000 Subject: [PATCH 4/6] Final verification - all changes complete Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- content/docs/references/ai/agent-action.mdx | 172 ++++++ content/docs/references/ai/agent.mdx | 43 ++ content/docs/references/ai/conversation.mdx | 117 ++++ content/docs/references/ai/cost.mdx | 107 ++++ content/docs/references/ai/devops-agent.mdx | 185 ++++++ content/docs/references/ai/feedback-loop.mdx | 41 ++ content/docs/references/ai/meta.json | 19 + content/docs/references/ai/model-registry.mdx | 77 +++ content/docs/references/ai/nlq.mdx | 92 +++ content/docs/references/ai/orchestration.mdx | 86 +++ .../docs/references/ai/plugin-development.mdx | 75 +++ content/docs/references/ai/predictive.mdx | 90 +++ content/docs/references/ai/rag-pipeline.mdx | 107 ++++ content/docs/references/ai/runtime-ops.mdx | 75 +++ content/docs/references/api/analytics.mdx | 57 ++ content/docs/references/api/auth.mdx | 67 +++ content/docs/references/api/batch.mdx | 84 +++ content/docs/references/api/connector.mdx | 26 + content/docs/references/api/contract.mdx | 88 +++ content/docs/references/api/discovery.mdx | 45 ++ content/docs/references/api/documentation.mdx | 132 ++++ content/docs/references/api/endpoint.mdx | 40 ++ content/docs/references/api/errors.mdx | 64 ++ content/docs/references/api/graphql.mdx | 205 +++++++ content/docs/references/api/http-cache.mdx | 107 ++++ content/docs/references/api/identity.mdx | 26 + content/docs/references/api/meta.json | 32 + content/docs/references/api/metadata.mdx | 42 ++ content/docs/references/api/odata.mdx | 156 +++++ .../docs/references/api/package-registry.mdx | 81 +++ content/docs/references/api/protocol.mdx | 565 ++++++++++++++++++ content/docs/references/api/realtime.mdx | 70 +++ content/docs/references/api/registry.mdx | 142 +++++ content/docs/references/api/rest-server.mdx | 97 +++ content/docs/references/api/router.mdx | 40 ++ content/docs/references/api/storage.mdx | 49 ++ content/docs/references/api/view.mdx | 26 + content/docs/references/api/websocket.mdx | 179 ++++++ .../docs/references/automation/approval.mdx | 48 ++ .../docs/references/automation/connector.mdx | 41 ++ content/docs/references/automation/etl.mdx | 192 ++++++ content/docs/references/automation/events.mdx | 26 + content/docs/references/automation/flow.mdx | 48 ++ content/docs/references/automation/meta.json | 15 + .../references/automation/state-machine.mdx | 52 ++ content/docs/references/automation/sync.mdx | 181 ++++++ .../automation/trigger-registry.mdx | 160 +++++ .../docs/references/automation/webhook.mdx | 40 ++ .../docs/references/automation/workflow.mdx | 78 +++ content/docs/references/contracts/meta.json | 4 + content/docs/references/data/analytics.mdx | 71 +++ content/docs/references/data/data-engine.mdx | 133 +++++ content/docs/references/data/dataset.mdx | 35 ++ content/docs/references/data/datasource.mdx | 45 ++ content/docs/references/data/document.mdx | 71 +++ content/docs/references/data/driver-nosql.mdx | 95 +++ content/docs/references/data/driver-sql.mdx | 45 ++ content/docs/references/data/driver.mdx | 50 ++ .../docs/references/data/external-lookup.mdx | 76 +++ content/docs/references/data/field.mdx | 78 +++ content/docs/references/data/filter.mdx | 106 ++++ content/docs/references/data/hook.mdx | 40 ++ content/docs/references/data/mapping.mdx | 40 ++ content/docs/references/data/meta.json | 22 + content/docs/references/data/object.mdx | 78 +++ content/docs/references/data/query.mdx | 85 +++ .../docs/references/data/search-engine.mdx | 26 + content/docs/references/data/validation.mdx | 139 +++++ content/docs/references/identity/identity.mdx | 51 ++ content/docs/references/identity/meta.json | 9 + .../docs/references/identity/organization.mdx | 49 ++ content/docs/references/identity/role.mdx | 64 ++ content/docs/references/identity/scim.mdx | 161 +++++ .../docs/references/integration/connector.mdx | 181 ++++++ content/docs/references/integration/http.mdx | 26 + .../docs/references/integration/mapping.mdx | 26 + .../references/integration/message-queue.mdx | 31 + content/docs/references/integration/meta.json | 11 + content/docs/references/integration/misc.mdx | 241 ++++++++ .../references/integration/object-storage.mdx | 26 + content/docs/references/kernel/context.mdx | 35 ++ content/docs/references/kernel/events.mdx | 107 ++++ content/docs/references/kernel/feature.mdx | 33 + content/docs/references/kernel/manifest.mdx | 58 ++ content/docs/references/kernel/meta.json | 26 + .../kernel/metadata-persistence.mdx | 81 +++ .../references/kernel/package-registry.mdx | 121 ++++ content/docs/references/kernel/permission.mdx | 26 + .../references/kernel/plugin-capability.mdx | 80 +++ .../kernel/plugin-lifecycle-advanced.mdx | 82 +++ .../kernel/plugin-lifecycle-events.mdx | 96 +++ .../docs/references/kernel/plugin-loading.mdx | 112 ++++ .../references/kernel/plugin-registry.mdx | 59 ++ .../kernel/plugin-security-advanced.mdx | 94 +++ .../references/kernel/plugin-security.mdx | 106 ++++ .../references/kernel/plugin-structure.mdx | 44 ++ .../references/kernel/plugin-validator.mdx | 51 ++ .../references/kernel/plugin-versioning.mdx | 92 +++ content/docs/references/kernel/plugin.mdx | 45 ++ .../references/kernel/service-registry.mdx | 67 +++ .../kernel/startup-orchestrator.mdx | 51 ++ content/docs/references/qa/meta.json | 6 + content/docs/references/qa/testing.mdx | 61 ++ content/docs/references/security/meta.json | 10 + .../docs/references/security/permission.mdx | 48 ++ content/docs/references/security/policy.mdx | 48 ++ content/docs/references/security/rls.mdx | 178 ++++++ content/docs/references/security/sharing.mdx | 60 ++ .../docs/references/security/territory.mdx | 58 ++ content/docs/references/shared/http.mdx | 42 ++ .../docs/references/shared/identifiers.mdx | 108 ++++ content/docs/references/shared/mapping.mdx | 81 +++ content/docs/references/shared/meta.json | 12 + content/docs/references/shared/view.mdx | 26 + content/docs/references/system/audit.mdx | 94 +++ .../docs/references/system/auth-config.mdx | 42 ++ content/docs/references/system/cache.mdx | 75 +++ .../references/system/change-management.mdx | 57 ++ .../docs/references/system/collaboration.mdx | 176 ++++++ content/docs/references/system/compliance.mdx | 48 ++ content/docs/references/system/encryption.mdx | 50 ++ .../docs/references/system/http-server.mdx | 75 +++ content/docs/references/system/job.mdx | 65 ++ content/docs/references/system/license.mdx | 43 ++ content/docs/references/system/logging.mdx | 107 ++++ content/docs/references/system/masking.mdx | 38 ++ .../docs/references/system/message-queue.mdx | 50 ++ content/docs/references/system/meta.json | 30 + .../system/metadata-persistence.mdx | 100 ++++ content/docs/references/system/metrics.mdx | 105 ++++ content/docs/references/system/migration.mdx | 71 +++ .../docs/references/system/notification.mdx | 89 +++ .../docs/references/system/object-storage.mdx | 116 ++++ .../references/system/registry-config.mdx | 42 ++ .../docs/references/system/search-engine.mdx | 50 ++ content/docs/references/system/tenant.mdx | 77 +++ content/docs/references/system/tracing.mdx | 125 ++++ .../docs/references/system/translation.mdx | 54 ++ content/docs/references/system/worker.mdx | 117 ++++ content/docs/references/ui/action.mdx | 35 ++ content/docs/references/ui/app.mdx | 83 +++ content/docs/references/ui/chart.mdx | 57 ++ content/docs/references/ui/component.mdx | 53 ++ content/docs/references/ui/dashboard.mdx | 35 ++ content/docs/references/ui/meta.json | 15 + content/docs/references/ui/page.mdx | 50 ++ content/docs/references/ui/report.mdx | 48 ++ content/docs/references/ui/theme.mdx | 75 +++ content/docs/references/ui/view.mdx | 103 ++++ content/docs/references/ui/widget.mdx | 83 +++ 150 files changed, 11439 insertions(+) create mode 100644 content/docs/references/ai/agent-action.mdx create mode 100644 content/docs/references/ai/agent.mdx create mode 100644 content/docs/references/ai/conversation.mdx create mode 100644 content/docs/references/ai/cost.mdx create mode 100644 content/docs/references/ai/devops-agent.mdx create mode 100644 content/docs/references/ai/feedback-loop.mdx create mode 100644 content/docs/references/ai/meta.json create mode 100644 content/docs/references/ai/model-registry.mdx create mode 100644 content/docs/references/ai/nlq.mdx create mode 100644 content/docs/references/ai/orchestration.mdx create mode 100644 content/docs/references/ai/plugin-development.mdx create mode 100644 content/docs/references/ai/predictive.mdx create mode 100644 content/docs/references/ai/rag-pipeline.mdx create mode 100644 content/docs/references/ai/runtime-ops.mdx create mode 100644 content/docs/references/api/analytics.mdx create mode 100644 content/docs/references/api/auth.mdx create mode 100644 content/docs/references/api/batch.mdx create mode 100644 content/docs/references/api/connector.mdx create mode 100644 content/docs/references/api/contract.mdx create mode 100644 content/docs/references/api/discovery.mdx create mode 100644 content/docs/references/api/documentation.mdx create mode 100644 content/docs/references/api/endpoint.mdx create mode 100644 content/docs/references/api/errors.mdx create mode 100644 content/docs/references/api/graphql.mdx create mode 100644 content/docs/references/api/http-cache.mdx create mode 100644 content/docs/references/api/identity.mdx create mode 100644 content/docs/references/api/meta.json create mode 100644 content/docs/references/api/metadata.mdx create mode 100644 content/docs/references/api/odata.mdx create mode 100644 content/docs/references/api/package-registry.mdx create mode 100644 content/docs/references/api/protocol.mdx create mode 100644 content/docs/references/api/realtime.mdx create mode 100644 content/docs/references/api/registry.mdx create mode 100644 content/docs/references/api/rest-server.mdx create mode 100644 content/docs/references/api/router.mdx create mode 100644 content/docs/references/api/storage.mdx create mode 100644 content/docs/references/api/view.mdx create mode 100644 content/docs/references/api/websocket.mdx create mode 100644 content/docs/references/automation/approval.mdx create mode 100644 content/docs/references/automation/connector.mdx create mode 100644 content/docs/references/automation/etl.mdx create mode 100644 content/docs/references/automation/events.mdx create mode 100644 content/docs/references/automation/flow.mdx create mode 100644 content/docs/references/automation/meta.json create mode 100644 content/docs/references/automation/state-machine.mdx create mode 100644 content/docs/references/automation/sync.mdx create mode 100644 content/docs/references/automation/trigger-registry.mdx create mode 100644 content/docs/references/automation/webhook.mdx create mode 100644 content/docs/references/automation/workflow.mdx create mode 100644 content/docs/references/contracts/meta.json create mode 100644 content/docs/references/data/analytics.mdx create mode 100644 content/docs/references/data/data-engine.mdx create mode 100644 content/docs/references/data/dataset.mdx create mode 100644 content/docs/references/data/datasource.mdx create mode 100644 content/docs/references/data/document.mdx create mode 100644 content/docs/references/data/driver-nosql.mdx create mode 100644 content/docs/references/data/driver-sql.mdx create mode 100644 content/docs/references/data/driver.mdx create mode 100644 content/docs/references/data/external-lookup.mdx create mode 100644 content/docs/references/data/field.mdx create mode 100644 content/docs/references/data/filter.mdx create mode 100644 content/docs/references/data/hook.mdx create mode 100644 content/docs/references/data/mapping.mdx create mode 100644 content/docs/references/data/meta.json create mode 100644 content/docs/references/data/object.mdx create mode 100644 content/docs/references/data/query.mdx create mode 100644 content/docs/references/data/search-engine.mdx create mode 100644 content/docs/references/data/validation.mdx create mode 100644 content/docs/references/identity/identity.mdx create mode 100644 content/docs/references/identity/meta.json create mode 100644 content/docs/references/identity/organization.mdx create mode 100644 content/docs/references/identity/role.mdx create mode 100644 content/docs/references/identity/scim.mdx create mode 100644 content/docs/references/integration/connector.mdx create mode 100644 content/docs/references/integration/http.mdx create mode 100644 content/docs/references/integration/mapping.mdx create mode 100644 content/docs/references/integration/message-queue.mdx create mode 100644 content/docs/references/integration/meta.json create mode 100644 content/docs/references/integration/misc.mdx create mode 100644 content/docs/references/integration/object-storage.mdx create mode 100644 content/docs/references/kernel/context.mdx create mode 100644 content/docs/references/kernel/events.mdx create mode 100644 content/docs/references/kernel/feature.mdx create mode 100644 content/docs/references/kernel/manifest.mdx create mode 100644 content/docs/references/kernel/meta.json create mode 100644 content/docs/references/kernel/metadata-persistence.mdx create mode 100644 content/docs/references/kernel/package-registry.mdx create mode 100644 content/docs/references/kernel/permission.mdx create mode 100644 content/docs/references/kernel/plugin-capability.mdx create mode 100644 content/docs/references/kernel/plugin-lifecycle-advanced.mdx create mode 100644 content/docs/references/kernel/plugin-lifecycle-events.mdx create mode 100644 content/docs/references/kernel/plugin-loading.mdx create mode 100644 content/docs/references/kernel/plugin-registry.mdx create mode 100644 content/docs/references/kernel/plugin-security-advanced.mdx create mode 100644 content/docs/references/kernel/plugin-security.mdx create mode 100644 content/docs/references/kernel/plugin-structure.mdx create mode 100644 content/docs/references/kernel/plugin-validator.mdx create mode 100644 content/docs/references/kernel/plugin-versioning.mdx create mode 100644 content/docs/references/kernel/plugin.mdx create mode 100644 content/docs/references/kernel/service-registry.mdx create mode 100644 content/docs/references/kernel/startup-orchestrator.mdx create mode 100644 content/docs/references/qa/meta.json create mode 100644 content/docs/references/qa/testing.mdx create mode 100644 content/docs/references/security/meta.json create mode 100644 content/docs/references/security/permission.mdx create mode 100644 content/docs/references/security/policy.mdx create mode 100644 content/docs/references/security/rls.mdx create mode 100644 content/docs/references/security/sharing.mdx create mode 100644 content/docs/references/security/territory.mdx create mode 100644 content/docs/references/shared/http.mdx create mode 100644 content/docs/references/shared/identifiers.mdx create mode 100644 content/docs/references/shared/mapping.mdx create mode 100644 content/docs/references/shared/meta.json create mode 100644 content/docs/references/shared/view.mdx create mode 100644 content/docs/references/system/audit.mdx create mode 100644 content/docs/references/system/auth-config.mdx create mode 100644 content/docs/references/system/cache.mdx create mode 100644 content/docs/references/system/change-management.mdx create mode 100644 content/docs/references/system/collaboration.mdx create mode 100644 content/docs/references/system/compliance.mdx create mode 100644 content/docs/references/system/encryption.mdx create mode 100644 content/docs/references/system/http-server.mdx create mode 100644 content/docs/references/system/job.mdx create mode 100644 content/docs/references/system/license.mdx create mode 100644 content/docs/references/system/logging.mdx create mode 100644 content/docs/references/system/masking.mdx create mode 100644 content/docs/references/system/message-queue.mdx create mode 100644 content/docs/references/system/meta.json create mode 100644 content/docs/references/system/metadata-persistence.mdx create mode 100644 content/docs/references/system/metrics.mdx create mode 100644 content/docs/references/system/migration.mdx create mode 100644 content/docs/references/system/notification.mdx create mode 100644 content/docs/references/system/object-storage.mdx create mode 100644 content/docs/references/system/registry-config.mdx create mode 100644 content/docs/references/system/search-engine.mdx create mode 100644 content/docs/references/system/tenant.mdx create mode 100644 content/docs/references/system/tracing.mdx create mode 100644 content/docs/references/system/translation.mdx create mode 100644 content/docs/references/system/worker.mdx create mode 100644 content/docs/references/ui/action.mdx create mode 100644 content/docs/references/ui/app.mdx create mode 100644 content/docs/references/ui/chart.mdx create mode 100644 content/docs/references/ui/component.mdx create mode 100644 content/docs/references/ui/dashboard.mdx create mode 100644 content/docs/references/ui/meta.json create mode 100644 content/docs/references/ui/page.mdx create mode 100644 content/docs/references/ui/report.mdx create mode 100644 content/docs/references/ui/theme.mdx create mode 100644 content/docs/references/ui/view.mdx create mode 100644 content/docs/references/ui/widget.mdx diff --git a/content/docs/references/ai/agent-action.mdx b/content/docs/references/ai/agent-action.mdx new file mode 100644 index 000000000..d3eb6f76a --- /dev/null +++ b/content/docs/references/ai/agent-action.mdx @@ -0,0 +1,172 @@ +--- +title: Agent Action +description: Agent Action protocol schemas +--- + +AI Agent Action Protocol + +Defines how AI agents can interact with the UI by mapping natural language intents + +to structured UI actions. This enables agents to not only query data but also + +manipulate the interface, navigate between views, and trigger workflows. + +Architecture Alignment: + +- Salesforce Einstein: Action recommendations and automated UI interactions + +- ServiceNow Virtual Agent: UI action automation + +- Microsoft Power Virtual Agents: Bot actions and UI integration + +Use Cases: + +- "Open the new account form" → Navigate to form view + +- "Show me all active opportunities" → Navigate to list view with filter + +- "Create a new task for John" → Open form with pre-filled data + +- "Switch to the kanban view" → Change view mode + + +**Source:** `packages/spec/src/ai/agent-action.zod.ts` + + +## TypeScript Usage + +```typescript +import { AgentAction, AgentActionResult, AgentActionSequence, AgentActionSequenceResult, ComponentActionParams, ComponentActionType, ComponentAgentAction, DataActionParams, DataActionType, DataAgentAction, FormActionParams, FormActionType, FormAgentAction, IntentActionMapping, NavigationActionParams, NavigationActionType, NavigationAgentAction, TypedAgentAction, UIActionType, ViewActionParams, ViewActionType, ViewAgentAction, WorkflowActionParams, WorkflowActionType, WorkflowAgentAction } from '@objectstack/spec/ai'; +import type { AgentAction, AgentActionResult, AgentActionSequence, AgentActionSequenceResult, ComponentActionParams, ComponentActionType, ComponentAgentAction, DataActionParams, DataActionType, DataAgentAction, FormActionParams, FormActionType, FormAgentAction, IntentActionMapping, NavigationActionParams, NavigationActionType, NavigationAgentAction, TypedAgentAction, UIActionType, ViewActionParams, ViewActionType, ViewAgentAction, WorkflowActionParams, WorkflowActionType, WorkflowAgentAction } from '@objectstack/spec/ai'; + +// Validate data +const result = AgentAction.parse(data); +``` + +--- + +## AgentAction + + +--- + +## AgentActionResult + + +--- + +## AgentActionSequence + + +--- + +## AgentActionSequenceResult + + +--- + +## ComponentActionParams + + +--- + +## ComponentActionType + + +--- + +## ComponentAgentAction + + +--- + +## DataActionParams + + +--- + +## DataActionType + + +--- + +## DataAgentAction + + +--- + +## FormActionParams + + +--- + +## FormActionType + + +--- + +## FormAgentAction + + +--- + +## IntentActionMapping + + +--- + +## NavigationActionParams + + +--- + +## NavigationActionType + + +--- + +## NavigationAgentAction + + +--- + +## TypedAgentAction + + +--- + +## UIActionType + + +--- + +## ViewActionParams + + +--- + +## ViewActionType + + +--- + +## ViewAgentAction + + +--- + +## WorkflowActionParams + + +--- + +## WorkflowActionType + + +--- + +## WorkflowAgentAction + + +--- + diff --git a/content/docs/references/ai/agent.mdx b/content/docs/references/ai/agent.mdx new file mode 100644 index 000000000..3ed63868d --- /dev/null +++ b/content/docs/references/ai/agent.mdx @@ -0,0 +1,43 @@ +--- +title: Agent +description: Agent protocol schemas +--- + +AI Model Configuration + + +**Source:** `packages/spec/src/ai/agent.zod.ts` + + +## TypeScript Usage + +```typescript +import { AIKnowledge, AIModelConfig, AITool, Agent } from '@objectstack/spec/ai'; +import type { AIKnowledge, AIModelConfig, AITool, Agent } from '@objectstack/spec/ai'; + +// Validate data +const result = AIKnowledge.parse(data); +``` + +--- + +## AIKnowledge + + +--- + +## AIModelConfig + + +--- + +## AITool + + +--- + +## Agent + + +--- + diff --git a/content/docs/references/ai/conversation.mdx b/content/docs/references/ai/conversation.mdx new file mode 100644 index 000000000..2525d4a37 --- /dev/null +++ b/content/docs/references/ai/conversation.mdx @@ -0,0 +1,117 @@ +--- +title: Conversation +description: Conversation protocol schemas +--- + +AI Conversation Memory Protocol + +Multi-turn AI conversations with token budget management. + +Enables context preservation, conversation history, and token optimization. + + +**Source:** `packages/spec/src/ai/conversation.zod.ts` + + +## TypeScript Usage + +```typescript +import { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai'; +import type { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai'; + +// Validate data +const result = CodeContent.parse(data); +``` + +--- + +## CodeContent + + +--- + +## ConversationAnalytics + + +--- + +## ConversationContext + + +--- + +## ConversationMessage + + +--- + +## ConversationSession + + +--- + +## ConversationSummary + + +--- + +## FileContent + + +--- + +## FunctionCall + + +--- + +## ImageContent + + +--- + +## MessageContent + + +--- + +## MessageContentType + + +--- + +## MessagePruningEvent + + +--- + +## MessageRole + + +--- + +## TextContent + + +--- + +## TokenBudgetConfig + + +--- + +## TokenBudgetStrategy + + +--- + +## TokenUsageStats + + +--- + +## ToolCall + + +--- + diff --git a/content/docs/references/ai/cost.mdx b/content/docs/references/ai/cost.mdx new file mode 100644 index 000000000..ae756f1bf --- /dev/null +++ b/content/docs/references/ai/cost.mdx @@ -0,0 +1,107 @@ +--- +title: Cost +description: Cost protocol schemas +--- + +AI Cost Tracking Protocol + +Monitor and control AI API costs with budgets, alerts, and analytics. + +Provides cost optimization, budget enforcement, and financial reporting. + + +**Source:** `packages/spec/src/ai/cost.zod.ts` + + +## TypeScript Usage + +```typescript +import { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai'; +import type { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai'; + +// Validate data +const result = AIOperationCost.parse(data); +``` + +--- + +## AIOperationCost + + +--- + +## BillingPeriod + + +--- + +## BudgetLimit + + +--- + +## BudgetStatus + + +--- + +## BudgetType + + +--- + +## CostAlert + + +--- + +## CostAlertType + + +--- + +## CostAnalytics + + +--- + +## CostBreakdownDimension + + +--- + +## CostBreakdownEntry + + +--- + +## CostEntry + + +--- + +## CostMetricType + + +--- + +## CostOptimizationRecommendation + + +--- + +## CostQueryFilters + + +--- + +## CostReport + + +--- + +## TokenUsage + + +--- + diff --git a/content/docs/references/ai/devops-agent.mdx b/content/docs/references/ai/devops-agent.mdx new file mode 100644 index 000000000..caabb523c --- /dev/null +++ b/content/docs/references/ai/devops-agent.mdx @@ -0,0 +1,185 @@ +--- +title: Devops Agent +description: Devops Agent protocol schemas +--- + +DevOps Agent Protocol + +Defines autonomous DevOps agents that can self-iterate on enterprise + +management software development using the ObjectStack specification. + +This agent integrates with GitHub for version control and Vercel for + +deployment, enabling fully automated development, testing, and release cycles. + +Architecture: + +- Self-iterating development based on ObjectStack specifications + +- Automated code generation following best practices + +- Continuous integration and deployment + +- Version management and release automation + +- Monitoring and rollback capabilities + +Use Cases: + +- Automated feature development from specifications + +- Self-healing code based on test failures + +- Automated dependency updates + +- Continuous optimization and refactoring + +- Automated documentation generation + +@example + +```typescript + +import { DevOpsAgent } from '@objectstack/spec/ai'; + +const agent: DevOpsAgent = { + +name: 'devops_automation_agent', + +label: 'DevOps Automation Agent', + +role: 'Senior Full-Stack DevOps Engineer', + +instructions: '...', + +developmentConfig: { + +specificationSource: 'packages/spec', + +codeGeneration: { + +enabled: true, + +targets: ['frontend', 'backend', 'api'], + +}, + +}, + +integrations: { + +github: { + +connector: 'github_production', + +repository: { + +owner: 'objectstack-ai', + +name: 'app', + +}, + +}, + +vercel: { + +connector: 'vercel_production', + +project: 'objectstack-app', + +}, + +}, + +}; + +``` + + +**Source:** `packages/spec/src/ai/devops-agent.zod.ts` + + +## TypeScript Usage + +```typescript +import { CICDPipelineConfig, CodeGenerationConfig, CodeGenerationTarget, DeploymentStrategy, DevOpsAgent, DevOpsTool, DevelopmentConfig, GitHubIntegration, IntegrationConfig, MonitoringConfig, PipelineStage, TestingConfig, VercelIntegration, VersionManagement } from '@objectstack/spec/ai'; +import type { CICDPipelineConfig, CodeGenerationConfig, CodeGenerationTarget, DeploymentStrategy, DevOpsAgent, DevOpsTool, DevelopmentConfig, GitHubIntegration, IntegrationConfig, MonitoringConfig, PipelineStage, TestingConfig, VercelIntegration, VersionManagement } from '@objectstack/spec/ai'; + +// Validate data +const result = CICDPipelineConfig.parse(data); +``` + +--- + +## CICDPipelineConfig + + +--- + +## CodeGenerationConfig + + +--- + +## CodeGenerationTarget + + +--- + +## DeploymentStrategy + + +--- + +## DevOpsAgent + + +--- + +## DevOpsTool + + +--- + +## DevelopmentConfig + + +--- + +## GitHubIntegration + + +--- + +## IntegrationConfig + + +--- + +## MonitoringConfig + + +--- + +## PipelineStage + + +--- + +## TestingConfig + + +--- + +## VercelIntegration + + +--- + +## VersionManagement + + +--- + diff --git a/content/docs/references/ai/feedback-loop.mdx b/content/docs/references/ai/feedback-loop.mdx new file mode 100644 index 000000000..5fd5ce46c --- /dev/null +++ b/content/docs/references/ai/feedback-loop.mdx @@ -0,0 +1,41 @@ +--- +title: Feedback Loop +description: Feedback Loop protocol schemas +--- + + +**Source:** `packages/spec/src/ai/feedback-loop.zod.ts` + + +## TypeScript Usage + +```typescript +import { FeedbackLoop, Issue, MetadataSource, Resolution } from '@objectstack/spec/ai'; +import type { FeedbackLoop, Issue, MetadataSource, Resolution } from '@objectstack/spec/ai'; + +// Validate data +const result = FeedbackLoop.parse(data); +``` + +--- + +## FeedbackLoop + + +--- + +## Issue + + +--- + +## MetadataSource + + +--- + +## Resolution + + +--- + diff --git a/content/docs/references/ai/meta.json b/content/docs/references/ai/meta.json new file mode 100644 index 000000000..e1046fd19 --- /dev/null +++ b/content/docs/references/ai/meta.json @@ -0,0 +1,19 @@ +{ + "title": "AI Protocol", + "pages": [ + "agent", + "agent-action", + "conversation", + "cost", + "devops-agent", + "feedback-loop", + "mcp", + "model-registry", + "nlq", + "orchestration", + "plugin-development", + "predictive", + "rag-pipeline", + "runtime-ops" + ] +} \ No newline at end of file diff --git a/content/docs/references/ai/model-registry.mdx b/content/docs/references/ai/model-registry.mdx new file mode 100644 index 000000000..58261c416 --- /dev/null +++ b/content/docs/references/ai/model-registry.mdx @@ -0,0 +1,77 @@ +--- +title: Model Registry +description: Model Registry protocol schemas +--- + +AI Model Registry Protocol + +Centralized registry for managing AI models, prompt templates, and model versioning. + +Enables AI-powered ObjectStack applications to discover and use LLMs consistently. + + +**Source:** `packages/spec/src/ai/model-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; +import type { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai'; + +// Validate data +const result = ModelCapability.parse(data); +``` + +--- + +## ModelCapability + + +--- + +## ModelConfig + + +--- + +## ModelLimits + + +--- + +## ModelPricing + + +--- + +## ModelProvider + + +--- + +## ModelRegistry + + +--- + +## ModelRegistryEntry + + +--- + +## ModelSelectionCriteria + + +--- + +## PromptTemplate + + +--- + +## PromptVariable + + +--- + diff --git a/content/docs/references/ai/nlq.mdx b/content/docs/references/ai/nlq.mdx new file mode 100644 index 000000000..f19e66974 --- /dev/null +++ b/content/docs/references/ai/nlq.mdx @@ -0,0 +1,92 @@ +--- +title: Nlq +description: Nlq protocol schemas +--- + +Natural Language Query (NLQ) Protocol + +Transforms natural language queries into ObjectQL AST (Abstract Syntax Tree). + +Enables business users to query data using natural language instead of writing code. + + +**Source:** `packages/spec/src/ai/nlq.zod.ts` + + +## TypeScript Usage + +```typescript +import { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai'; +import type { Entity, FieldSynonymConfig, NLQAnalytics, NLQFieldMapping, NLQModelConfig, NLQParseResult, NLQRequest, NLQResponse, NLQTrainingExample, QueryContext, QueryIntent, QueryTemplate, Timeframe } from '@objectstack/spec/ai'; + +// Validate data +const result = Entity.parse(data); +``` + +--- + +## Entity + + +--- + +## FieldSynonymConfig + + +--- + +## NLQAnalytics + + +--- + +## NLQFieldMapping + + +--- + +## NLQModelConfig + + +--- + +## NLQParseResult + + +--- + +## NLQRequest + + +--- + +## NLQResponse + + +--- + +## NLQTrainingExample + + +--- + +## QueryContext + + +--- + +## QueryIntent + + +--- + +## QueryTemplate + + +--- + +## Timeframe + + +--- + diff --git a/content/docs/references/ai/orchestration.mdx b/content/docs/references/ai/orchestration.mdx new file mode 100644 index 000000000..4567b43f7 --- /dev/null +++ b/content/docs/references/ai/orchestration.mdx @@ -0,0 +1,86 @@ +--- +title: Orchestration +description: Orchestration protocol schemas +--- + +AI Agentic Orchestration Protocol + +Defines intelligent orchestration flows where AI Agents leverage cognitive skills + +to automate business processes with dynamic reasoning, planning, and execution. + +Distinction from Standard Workflows: + +- Standard Workflow: Deterministic (If X then Y). defined in src/data/workflow.zod.ts + +- AI Orchestration: Probabilistic & Agentic (Goal -> Plan -> Execute). + +Use Cases: + +- Complex Support Triage (Analyze sentiment + intent -> Draft response -> Route) + +- Intelligent Document Processing (OCR -> Extract Entities -> Validate -> Entry) + +- Research Agent (Search Web -> Summarize -> Generate Report) + + +**Source:** `packages/spec/src/ai/orchestration.zod.ts` + + +## TypeScript Usage + +```typescript +import { AIOrchestration, AIOrchestrationExecutionResult, AIOrchestrationTrigger, AITask, AITaskType, BatchAIOrchestrationExecution, PostProcessingAction, WorkflowFieldCondition, WorkflowSchedule } from '@objectstack/spec/ai'; +import type { AIOrchestration, AIOrchestrationExecutionResult, AIOrchestrationTrigger, AITask, AITaskType, BatchAIOrchestrationExecution, PostProcessingAction, WorkflowFieldCondition, WorkflowSchedule } from '@objectstack/spec/ai'; + +// Validate data +const result = AIOrchestration.parse(data); +``` + +--- + +## AIOrchestration + + +--- + +## AIOrchestrationExecutionResult + + +--- + +## AIOrchestrationTrigger + + +--- + +## AITask + + +--- + +## AITaskType + + +--- + +## BatchAIOrchestrationExecution + + +--- + +## PostProcessingAction + + +--- + +## WorkflowFieldCondition + + +--- + +## WorkflowSchedule + + +--- + diff --git a/content/docs/references/ai/plugin-development.mdx b/content/docs/references/ai/plugin-development.mdx new file mode 100644 index 000000000..68ac203b9 --- /dev/null +++ b/content/docs/references/ai/plugin-development.mdx @@ -0,0 +1,75 @@ +--- +title: Plugin Development +description: Plugin Development protocol schemas +--- + +# AI-Driven Plugin Development Protocol + +Defines protocols for AI-powered plugin development including: + +- Natural language to code generation + +- Intelligent code scaffolding + +- Automated testing and validation + +- AI-powered code review and optimization + +- Plugin composition and recommendation + + +**Source:** `packages/spec/src/ai/plugin-development.zod.ts` + + +## TypeScript Usage + +```typescript +import { AICodeReviewResult, CodeGenerationRequest, GeneratedCode, PluginCompositionRequest, PluginCompositionResult, PluginRecommendation, PluginRecommendationRequest, PluginScaffoldingTemplate } from '@objectstack/spec/ai'; +import type { AICodeReviewResult, CodeGenerationRequest, GeneratedCode, PluginCompositionRequest, PluginCompositionResult, PluginRecommendation, PluginRecommendationRequest, PluginScaffoldingTemplate } from '@objectstack/spec/ai'; + +// Validate data +const result = AICodeReviewResult.parse(data); +``` + +--- + +## AICodeReviewResult + + +--- + +## CodeGenerationRequest + + +--- + +## GeneratedCode + + +--- + +## PluginCompositionRequest + + +--- + +## PluginCompositionResult + + +--- + +## PluginRecommendation + + +--- + +## PluginRecommendationRequest + + +--- + +## PluginScaffoldingTemplate + + +--- + diff --git a/content/docs/references/ai/predictive.mdx b/content/docs/references/ai/predictive.mdx new file mode 100644 index 000000000..7014bd817 --- /dev/null +++ b/content/docs/references/ai/predictive.mdx @@ -0,0 +1,90 @@ +--- +title: Predictive +description: Predictive protocol schemas +--- + +Predictive Analytics Protocol + +Defines predictive models and machine learning configurations for + +data-driven decision making and forecasting in ObjectStack applications. + +Use Cases: + +- Lead scoring and conversion prediction + +- Customer churn prediction + +- Sales forecasting + +- Demand forecasting + +- Anomaly detection in operational data + +- Customer segmentation and clustering + +- Price optimization + +- Recommendation systems + + +**Source:** `packages/spec/src/ai/predictive.zod.ts` + + +## TypeScript Usage + +```typescript +import { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai'; +import type { EvaluationMetrics, Hyperparameters, ModelDrift, ModelFeature, PredictionRequest, PredictionResult, PredictiveModel, PredictiveModelType, TrainingConfig } from '@objectstack/spec/ai'; + +// Validate data +const result = EvaluationMetrics.parse(data); +``` + +--- + +## EvaluationMetrics + + +--- + +## Hyperparameters + + +--- + +## ModelDrift + + +--- + +## ModelFeature + + +--- + +## PredictionRequest + + +--- + +## PredictionResult + + +--- + +## PredictiveModel + + +--- + +## PredictiveModelType + + +--- + +## TrainingConfig + + +--- + diff --git a/content/docs/references/ai/rag-pipeline.mdx b/content/docs/references/ai/rag-pipeline.mdx new file mode 100644 index 000000000..ecfd27286 --- /dev/null +++ b/content/docs/references/ai/rag-pipeline.mdx @@ -0,0 +1,107 @@ +--- +title: Rag Pipeline +description: Rag Pipeline protocol schemas +--- + +RAG (Retrieval-Augmented Generation) Pipeline Protocol + +Defines schemas for building context-aware AI assistants using RAG techniques. + +Enables vector search, document chunking, embeddings, and retrieval configuration. + + +**Source:** `packages/spec/src/ai/rag-pipeline.zod.ts` + + +## TypeScript Usage + +```typescript +import { ChunkingStrategy, DocumentChunk, DocumentLoaderConfig, DocumentMetadata, EmbeddingModel, FilterExpression, FilterGroup, MetadataFilter, RAGPipelineConfig, RAGPipelineStatus, RAGQueryRequest, RAGQueryResponse, RerankingConfig, RetrievalStrategy, VectorStoreConfig, VectorStoreProvider } from '@objectstack/spec/ai'; +import type { ChunkingStrategy, DocumentChunk, DocumentLoaderConfig, DocumentMetadata, EmbeddingModel, FilterExpression, FilterGroup, MetadataFilter, RAGPipelineConfig, RAGPipelineStatus, RAGQueryRequest, RAGQueryResponse, RerankingConfig, RetrievalStrategy, VectorStoreConfig, VectorStoreProvider } from '@objectstack/spec/ai'; + +// Validate data +const result = ChunkingStrategy.parse(data); +``` + +--- + +## ChunkingStrategy + + +--- + +## DocumentChunk + + +--- + +## DocumentLoaderConfig + + +--- + +## DocumentMetadata + + +--- + +## EmbeddingModel + + +--- + +## FilterExpression + + +--- + +## FilterGroup + + +--- + +## MetadataFilter + + +--- + +## RAGPipelineConfig + + +--- + +## RAGPipelineStatus + + +--- + +## RAGQueryRequest + + +--- + +## RAGQueryResponse + + +--- + +## RerankingConfig + + +--- + +## RetrievalStrategy + + +--- + +## VectorStoreConfig + + +--- + +## VectorStoreProvider + + +--- + diff --git a/content/docs/references/ai/runtime-ops.mdx b/content/docs/references/ai/runtime-ops.mdx new file mode 100644 index 000000000..9639c36f2 --- /dev/null +++ b/content/docs/references/ai/runtime-ops.mdx @@ -0,0 +1,75 @@ +--- +title: Runtime Ops +description: Runtime Ops protocol schemas +--- + +# Runtime AI Operations (AIOps) Protocol + +Defines protocols for AI-powered runtime operations including: + +- Self-healing and automatic recovery + +- Intelligent auto-scaling + +- Anomaly detection and prediction + +- Performance optimization + +- Root cause analysis + + +**Source:** `packages/spec/src/ai/runtime-ops.zod.ts` + + +## TypeScript Usage + +```typescript +import { AIOpsAgentConfig, AnomalyDetectionConfig, AutoScalingPolicy, PerformanceOptimization, RootCauseAnalysisRequest, RootCauseAnalysisResult, SelfHealingAction, SelfHealingConfig } from '@objectstack/spec/ai'; +import type { AIOpsAgentConfig, AnomalyDetectionConfig, AutoScalingPolicy, PerformanceOptimization, RootCauseAnalysisRequest, RootCauseAnalysisResult, SelfHealingAction, SelfHealingConfig } from '@objectstack/spec/ai'; + +// Validate data +const result = AIOpsAgentConfig.parse(data); +``` + +--- + +## AIOpsAgentConfig + + +--- + +## AnomalyDetectionConfig + + +--- + +## AutoScalingPolicy + + +--- + +## PerformanceOptimization + + +--- + +## RootCauseAnalysisRequest + + +--- + +## RootCauseAnalysisResult + + +--- + +## SelfHealingAction + + +--- + +## SelfHealingConfig + + +--- + diff --git a/content/docs/references/api/analytics.mdx b/content/docs/references/api/analytics.mdx new file mode 100644 index 000000000..68d535682 --- /dev/null +++ b/content/docs/references/api/analytics.mdx @@ -0,0 +1,57 @@ +--- +title: Analytics +description: Analytics protocol schemas +--- + +Analytics API Protocol + +Defines the HTTP interface for the Semantic Layer. + +Provides endpoints for executing analytical queries and discovering metadata. + + +**Source:** `packages/spec/src/api/analytics.zod.ts` + + +## TypeScript Usage + +```typescript +import { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsResultResponse, AnalyticsSqlResponse, GetAnalyticsMetaRequest } from '@objectstack/spec/api'; +import type { AnalyticsEndpoint, AnalyticsMetadataResponse, AnalyticsQueryRequest, AnalyticsResultResponse, AnalyticsSqlResponse, GetAnalyticsMetaRequest } from '@objectstack/spec/api'; + +// Validate data +const result = AnalyticsEndpoint.parse(data); +``` + +--- + +## AnalyticsEndpoint + + +--- + +## AnalyticsMetadataResponse + + +--- + +## AnalyticsQueryRequest + + +--- + +## AnalyticsResultResponse + + +--- + +## AnalyticsSqlResponse + + +--- + +## GetAnalyticsMetaRequest + + +--- + diff --git a/content/docs/references/api/auth.mdx b/content/docs/references/api/auth.mdx new file mode 100644 index 000000000..fe3b578ce --- /dev/null +++ b/content/docs/references/api/auth.mdx @@ -0,0 +1,67 @@ +--- +title: Auth +description: Auth protocol schemas +--- + +Authentication Service Protocol + +Defines the standard API contracts for Identity, Session Management, + +and Access Control. + + +**Source:** `packages/spec/src/api/auth.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuthProvider, LoginRequest, LoginType, RefreshTokenRequest, RegisterRequest, SessionResponse, SessionUser, UserProfileResponse } from '@objectstack/spec/api'; +import type { AuthProvider, LoginRequest, LoginType, RefreshTokenRequest, RegisterRequest, SessionResponse, SessionUser, UserProfileResponse } from '@objectstack/spec/api'; + +// Validate data +const result = AuthProvider.parse(data); +``` + +--- + +## AuthProvider + + +--- + +## LoginRequest + + +--- + +## LoginType + + +--- + +## RefreshTokenRequest + + +--- + +## RegisterRequest + + +--- + +## SessionResponse + + +--- + +## SessionUser + + +--- + +## UserProfileResponse + + +--- + diff --git a/content/docs/references/api/batch.mdx b/content/docs/references/api/batch.mdx new file mode 100644 index 000000000..181cc802c --- /dev/null +++ b/content/docs/references/api/batch.mdx @@ -0,0 +1,84 @@ +--- +title: Batch +description: Batch protocol schemas +--- + +Batch Operations API + +Provides efficient bulk data operations with transaction support. + +Implements P0/P1 requirements for ObjectStack kernel. + +Features: + +- Batch create/update/delete operations + +- Atomic transaction support (all-or-none) + +- Partial success handling + +- Detailed error reporting per record + +Industry alignment: Salesforce Bulk API, Microsoft Dynamics Bulk Operations + + +**Source:** `packages/spec/src/api/batch.zod.ts` + + +## TypeScript Usage + +```typescript +import { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api'; +import type { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api'; + +// Validate data +const result = BatchConfig.parse(data); +``` + +--- + +## BatchConfig + + +--- + +## BatchOperationResult + + +--- + +## BatchOperationType + + +--- + +## BatchOptions + + +--- + +## BatchRecord + + +--- + +## BatchUpdateRequest + + +--- + +## BatchUpdateResponse + + +--- + +## DeleteManyRequest + + +--- + +## UpdateManyRequest + + +--- + diff --git a/content/docs/references/api/connector.mdx b/content/docs/references/api/connector.mdx new file mode 100644 index 000000000..639d91d64 --- /dev/null +++ b/content/docs/references/api/connector.mdx @@ -0,0 +1,26 @@ +--- +title: Connector +description: Connector protocol schemas +--- + + +**Source:** `packages/spec/src/api/connector.zod.ts` + + +## TypeScript Usage + +```typescript +import { RetryStrategy } from '@objectstack/spec/api'; +import type { RetryStrategy } from '@objectstack/spec/api'; + +// Validate data +const result = RetryStrategy.parse(data); +``` + +--- + +## RetryStrategy + + +--- + diff --git a/content/docs/references/api/contract.mdx b/content/docs/references/api/contract.mdx new file mode 100644 index 000000000..fe93491da --- /dev/null +++ b/content/docs/references/api/contract.mdx @@ -0,0 +1,88 @@ +--- +title: Contract +description: Contract protocol schemas +--- + +Standard Create Request + + +**Source:** `packages/spec/src/api/contract.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiError, BaseResponse, BulkRequest, BulkResponse, CreateRequest, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api'; +import type { ApiError, BaseResponse, BulkRequest, BulkResponse, CreateRequest, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api'; + +// Validate data +const result = ApiError.parse(data); +``` + +--- + +## ApiError + + +--- + +## BaseResponse + + +--- + +## BulkRequest + + +--- + +## BulkResponse + + +--- + +## CreateRequest + + +--- + +## DeleteResponse + + +--- + +## ExportRequest + + +--- + +## IdRequest + + +--- + +## ListRecordResponse + + +--- + +## ModificationResult + + +--- + +## RecordData + + +--- + +## SingleRecordResponse + + +--- + +## UpdateRequest + + +--- + diff --git a/content/docs/references/api/discovery.mdx b/content/docs/references/api/discovery.mdx new file mode 100644 index 000000000..20de148ad --- /dev/null +++ b/content/docs/references/api/discovery.mdx @@ -0,0 +1,45 @@ +--- +title: Discovery +description: Discovery protocol schemas +--- + +API Capabilities Schema + +Defines what features are enabled on this ObjectOS instance. + + +**Source:** `packages/spec/src/api/discovery.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiCapabilities, ApiRoutes, Discovery, ServiceInfo } from '@objectstack/spec/api'; +import type { ApiCapabilities, ApiRoutes, Discovery, ServiceInfo } from '@objectstack/spec/api'; + +// Validate data +const result = ApiCapabilities.parse(data); +``` + +--- + +## ApiCapabilities + + +--- + +## ApiRoutes + + +--- + +## Discovery + + +--- + +## ServiceInfo + + +--- + diff --git a/content/docs/references/api/documentation.mdx b/content/docs/references/api/documentation.mdx new file mode 100644 index 000000000..3c524907d --- /dev/null +++ b/content/docs/references/api/documentation.mdx @@ -0,0 +1,132 @@ +--- +title: Documentation +description: Documentation protocol schemas +--- + +API Documentation & Testing Interface Protocol + +Provides schemas for generating interactive API documentation and testing + +interfaces similar to Swagger UI, GraphQL Playground, Postman, etc. + +Features: + +- OpenAPI/Swagger specification generation + +- Interactive API testing playground + +- API versioning and changelog + +- Code generation templates + +- Mock server configuration + +Architecture Alignment: + +- Swagger UI: Interactive API documentation + +- Postman: API testing collections + +- GraphQL Playground: GraphQL-specific testing + +- Redoc: Documentation rendering + +@example Documentation Config + +```typescript + +const docConfig: ApiDocumentationConfig = { + +enabled: true, + +title: 'ObjectStack API', + +version: '1.0.0', + +servers: [{ url: 'https://api.example.com', description: 'Production' }], + +ui: { + +type: 'swagger-ui', + +theme: 'light', + +enableTryItOut: true + +} + +} + +``` + + +**Source:** `packages/spec/src/api/documentation.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api'; +import type { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api'; + +// Validate data +const result = ApiChangelogEntry.parse(data); +``` + +--- + +## ApiChangelogEntry + + +--- + +## ApiDocumentationConfig + + +--- + +## ApiTestCollection + + +--- + +## ApiTestRequest + + +--- + +## ApiTestingUiConfig + + +--- + +## ApiTestingUiType + + +--- + +## CodeGenerationTemplate + + +--- + +## GeneratedApiDocumentation + + +--- + +## OpenApiSecurityScheme + + +--- + +## OpenApiServer + + +--- + +## OpenApiSpec + + +--- + diff --git a/content/docs/references/api/endpoint.mdx b/content/docs/references/api/endpoint.mdx new file mode 100644 index 000000000..70931d7ab --- /dev/null +++ b/content/docs/references/api/endpoint.mdx @@ -0,0 +1,40 @@ +--- +title: Endpoint +description: Endpoint protocol schemas +--- + +Rate Limit Strategy + +@deprecated Use RateLimitConfigSchema from shared/http.zod.ts instead + + +**Source:** `packages/spec/src/api/endpoint.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiEndpoint, ApiMapping, RateLimit } from '@objectstack/spec/api'; +import type { ApiEndpoint, ApiMapping, RateLimit } from '@objectstack/spec/api'; + +// Validate data +const result = ApiEndpoint.parse(data); +``` + +--- + +## ApiEndpoint + + +--- + +## ApiMapping + + +--- + +## RateLimit + + +--- + diff --git a/content/docs/references/api/errors.mdx b/content/docs/references/api/errors.mdx new file mode 100644 index 000000000..92be00d41 --- /dev/null +++ b/content/docs/references/api/errors.mdx @@ -0,0 +1,64 @@ +--- +title: Errors +description: Errors protocol schemas +--- + +Standardized Error Codes Protocol + +Implements P0 requirement for ObjectStack kernel. + +Provides consistent, machine-readable error codes across the platform. + +Features: + +- Categorized error codes (validation, authentication, authorization, etc.) + +- HTTP status code mapping + +- Localization support + +- Retry guidance + +Industry alignment: Google Cloud Errors, AWS Error Codes, Stripe API Errors + + +**Source:** `packages/spec/src/api/errors.zod.ts` + + +## TypeScript Usage + +```typescript +import { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, StandardErrorCode } from '@objectstack/spec/api'; +import type { EnhancedApiError, ErrorCategory, ErrorResponse, FieldError, StandardErrorCode } from '@objectstack/spec/api'; + +// Validate data +const result = EnhancedApiError.parse(data); +``` + +--- + +## EnhancedApiError + + +--- + +## ErrorCategory + + +--- + +## ErrorResponse + + +--- + +## FieldError + + +--- + +## StandardErrorCode + + +--- + diff --git a/content/docs/references/api/graphql.mdx b/content/docs/references/api/graphql.mdx new file mode 100644 index 000000000..d01b03ebe --- /dev/null +++ b/content/docs/references/api/graphql.mdx @@ -0,0 +1,205 @@ +--- +title: Graphql +description: Graphql protocol schemas +--- + +GraphQL Protocol Support + +GraphQL is a query language for APIs and a runtime for executing those queries. + +It provides a complete and understandable description of the data in your API, + +gives clients the power to ask for exactly what they need, and enables powerful + +developer tools. + +## Overview + +GraphQL provides: + +- Type-safe schema definition + +- Precise data fetching (no over/under-fetching) + +- Introspection and documentation + +- Real-time subscriptions + +- Batched queries with DataLoader + +## Use Cases + +1. **Modern API Development** + +- Mobile and web applications + +- Microservices federation + +- Real-time dashboards + +2. **Data Aggregation** + +- Multi-source data integration + +- Complex nested queries + +- Efficient data loading + +3. **Developer Experience** + +- Self-documenting API + +- Type safety and validation + +- GraphQL playground + +@see https://graphql.org/ + +@see https://spec.graphql.org/ + +@example GraphQL Query + +```graphql + +query GetCustomer($id: ID!) { + +customer(id: $id) { + +id + +name + +email + +orders(limit: 10, status: "active") { + +id + +total + +items { + +product { + +name + +price + +} + +} + +} + +} + +} + +``` + +@example GraphQL Mutation + +```graphql + +mutation CreateOrder($input: CreateOrderInput!) { + +createOrder(input: $input) { + +id + +orderNumber + +status + +} + +} + +``` + + +**Source:** `packages/spec/src/api/graphql.zod.ts` + + +## TypeScript Usage + +```typescript +import { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api'; +import type { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api'; + +// Validate data +const result = GraphQLConfig.parse(data); +``` + +--- + +## GraphQLConfig + + +--- + +## GraphQLDataLoaderConfig + + +--- + +## GraphQLDirectiveConfig + + +--- + +## GraphQLDirectiveLocation + + +--- + +## GraphQLMutationConfig + + +--- + +## GraphQLPersistedQuery + + +--- + +## GraphQLQueryComplexity + + +--- + +## GraphQLQueryConfig + + +--- + +## GraphQLQueryDepthLimit + + +--- + +## GraphQLRateLimit + + +--- + +## GraphQLResolverConfig + + +--- + +## GraphQLScalarType + + +--- + +## GraphQLSubscriptionConfig + + +--- + +## GraphQLTypeConfig + + +--- + diff --git a/content/docs/references/api/http-cache.mdx b/content/docs/references/api/http-cache.mdx new file mode 100644 index 000000000..03354aec6 --- /dev/null +++ b/content/docs/references/api/http-cache.mdx @@ -0,0 +1,107 @@ +--- +title: Http Cache +description: Http Cache protocol schemas +--- + +HTTP Metadata Cache Protocol + +Implements efficient HTTP-level metadata caching with ETag support. + +Implements P0 requirement for ObjectStack kernel. + +## Caching in ObjectStack + +**HTTP Cache (`api/http-cache.zod.ts`) - This File** + +- **Purpose**: Cache API responses at HTTP protocol level + +- **Technologies**: HTTP headers (ETag, Last-Modified, Cache-Control), CDN + +- **Configuration**: Cache-Control headers, validation tokens + +- **Use case**: Reduce API response time for repeated metadata requests + +- **Scope**: HTTP layer, client-server communication + +**Application Cache (`system/cache.zod.ts`)** + +- **Purpose**: Cache computed data, query results, aggregations + +- **Technologies**: Redis, Memcached, in-memory LRU + +- **Configuration**: TTL, eviction policies, cache warming + +- **Use case**: Cache expensive database queries, computed values + +- **Scope**: Application layer, server-side data storage + +## Features + +- ETag-based conditional requests (HTTP 304 Not Modified) + +- Cache-Control directives + +- Metadata versioning + +- Selective cache invalidation + +Industry alignment: HTTP Caching (RFC 7234), Salesforce Metadata API + +@see ../../system/cache.zod.ts for application-level caching + + +**Source:** `packages/spec/src/api/http-cache.zod.ts` + + +## TypeScript Usage + +```typescript +import { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api'; +import type { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api'; + +// Validate data +const result = CacheControl.parse(data); +``` + +--- + +## CacheControl + + +--- + +## CacheDirective + + +--- + +## CacheInvalidationRequest + + +--- + +## CacheInvalidationResponse + + +--- + +## CacheInvalidationTarget + + +--- + +## ETag + + +--- + +## MetadataCacheRequest + + +--- + +## MetadataCacheResponse + + +--- + diff --git a/content/docs/references/api/identity.mdx b/content/docs/references/api/identity.mdx new file mode 100644 index 000000000..ea149950c --- /dev/null +++ b/content/docs/references/api/identity.mdx @@ -0,0 +1,26 @@ +--- +title: Identity +description: Identity protocol schemas +--- + + +**Source:** `packages/spec/src/api/identity.zod.ts` + + +## TypeScript Usage + +```typescript +import { Session } from '@objectstack/spec/api'; +import type { Session } from '@objectstack/spec/api'; + +// Validate data +const result = Session.parse(data); +``` + +--- + +## Session + + +--- + diff --git a/content/docs/references/api/meta.json b/content/docs/references/api/meta.json new file mode 100644 index 000000000..a4a06b13e --- /dev/null +++ b/content/docs/references/api/meta.json @@ -0,0 +1,32 @@ +{ + "title": "API Protocol", + "pages": [ + "analytics", + "auth", + "batch", + "connector", + "contract", + "discovery", + "dispatcher", + "documentation", + "endpoint", + "errors", + "graphql", + "http-cache", + "identity", + "metadata", + "object", + "odata", + "package-registry", + "plugin-rest-api", + "protocol", + "realtime", + "registry", + "rest-server", + "router", + "storage", + "versioning", + "view", + "websocket" + ] +} \ No newline at end of file diff --git a/content/docs/references/api/metadata.mdx b/content/docs/references/api/metadata.mdx new file mode 100644 index 000000000..0ff361f3c --- /dev/null +++ b/content/docs/references/api/metadata.mdx @@ -0,0 +1,42 @@ +--- +title: Metadata +description: Metadata protocol schemas +--- + +Metadata Service Protocol + +Defines the standard API contracts for fetching system metadata. + +Frontend, IDEs, and Mobile apps use this to build dynamic UIs. + + +**Source:** `packages/spec/src/api/metadata.zod.ts` + + +## TypeScript Usage + +```typescript +import { AppDefinitionResponse, ConceptListResponse, ObjectDefinitionResponse } from '@objectstack/spec/api'; +import type { AppDefinitionResponse, ConceptListResponse, ObjectDefinitionResponse } from '@objectstack/spec/api'; + +// Validate data +const result = AppDefinitionResponse.parse(data); +``` + +--- + +## AppDefinitionResponse + + +--- + +## ConceptListResponse + + +--- + +## ObjectDefinitionResponse + + +--- + diff --git a/content/docs/references/api/odata.mdx b/content/docs/references/api/odata.mdx new file mode 100644 index 000000000..5badcdc43 --- /dev/null +++ b/content/docs/references/api/odata.mdx @@ -0,0 +1,156 @@ +--- +title: Odata +description: Odata protocol schemas +--- + +OData v4 Protocol Support + +Open Data Protocol (OData) v4 is an industry-standard protocol for building + +and consuming RESTful APIs. It provides a uniform way to expose, structure, + +query, and manipulate data. + +## Overview + +OData v4 provides standardized URL conventions for querying data including: + +- $select: Choose which fields to return + +- $filter: Filter results with complex expressions + +- $orderby: Sort results + +- $top/$skip: Pagination + +- $expand: Include related entities + +- $count: Get total count + +## Use Cases + +1. **Enterprise Integration** + +- Integrate with Microsoft Dynamics 365 + +- Connect to SharePoint Online + +- SAP OData services + +2. **API Standardization** + +- Provide consistent query interface + +- Standard pagination and filtering + +- Industry-recognized protocol + +3. **External Data Sources** + +- Connect to OData-compliant systems + +- Federated queries + +- Data virtualization + +@see https://www.odata.org/documentation/ + +@see https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html + +@example OData Query + +``` + +GET /api/odata/customers? + +$select=name,email& + +$filter=country eq 'US' and revenue gt 100000& + +$orderby=revenue desc& + +$top=10& + +$skip=20& + +$expand=orders& + +$count=true + +``` + +@example Programmatic Use + +```typescript + +const query: ODataQuery = { + +select: ['name', 'email'], + +filter: "country eq 'US' and revenue gt 100000", + +orderby: 'revenue desc', + +top: 10, + +skip: 20, + +expand: ['orders'], + +count: true + +} + +``` + + +**Source:** `packages/spec/src/api/odata.zod.ts` + + +## TypeScript Usage + +```typescript +import { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api'; +import type { ODataConfig, ODataError, ODataFilterFunction, ODataFilterOperator, ODataMetadata, ODataQuery, ODataResponse } from '@objectstack/spec/api'; + +// Validate data +const result = ODataConfig.parse(data); +``` + +--- + +## ODataConfig + + +--- + +## ODataError + + +--- + +## ODataFilterFunction + + +--- + +## ODataFilterOperator + + +--- + +## ODataMetadata + + +--- + +## ODataQuery + + +--- + +## ODataResponse + + +--- + diff --git a/content/docs/references/api/package-registry.mdx b/content/docs/references/api/package-registry.mdx new file mode 100644 index 000000000..c05fd95ce --- /dev/null +++ b/content/docs/references/api/package-registry.mdx @@ -0,0 +1,81 @@ +--- +title: Package Registry +description: Package Registry protocol schemas +--- + + +**Source:** `packages/spec/src/api/package-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, ListPackagesRequest, ListPackagesResponse, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; +import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, ListPackagesRequest, ListPackagesResponse, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/api'; + +// Validate data +const result = DisablePackageRequest.parse(data); +``` + +--- + +## DisablePackageRequest + + +--- + +## DisablePackageResponse + + +--- + +## EnablePackageRequest + + +--- + +## EnablePackageResponse + + +--- + +## GetPackageRequest + + +--- + +## GetPackageResponse + + +--- + +## InstallPackageRequest + + +--- + +## InstallPackageResponse + + +--- + +## ListPackagesRequest + + +--- + +## ListPackagesResponse + + +--- + +## UninstallPackageRequest + + +--- + +## UninstallPackageResponse + + +--- + diff --git a/content/docs/references/api/protocol.mdx b/content/docs/references/api/protocol.mdx new file mode 100644 index 000000000..ef7c764fe --- /dev/null +++ b/content/docs/references/api/protocol.mdx @@ -0,0 +1,565 @@ +--- +title: Protocol +description: Protocol protocol schemas +--- + +ObjectStack Protocol - Zod Schema Definitions + +Defines the runtime-validated contract for interacting with ObjectStack metadata and data. + +Used by API adapters (HTTP, WebSocket, gRPC) to fetch data/metadata without knowing engine internals. + +This protocol enables: + +- Runtime request/response validation at API gateway level + +- Automatic API documentation generation + +- Type-safe RPC communication between microservices + +- Client SDK generation from schemas + +Architecture Alignment: + +- Salesforce: REST API Request/Response schemas + +- Kubernetes: API Resource schemas with runtime validation + +- GraphQL: Schema-first API design + + +**Source:** `packages/spec/src/api/protocol.zod.ts` + + +## TypeScript Usage + +```typescript +import { AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, CreateViewRequest, CreateViewResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetUiViewResponse, GetViewRequest, GetViewResponse, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, ListViewsResponse, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, Notification, NotificationPreferences, ObjectStackProtocol, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, UpdateViewRequest, UpdateViewResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api'; +import type { AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AutomationTriggerRequest, AutomationTriggerResponse, BatchDataRequest, BatchDataResponse, CheckPermissionRequest, CheckPermissionResponse, CreateDataRequest, CreateDataResponse, CreateManyDataRequest, CreateManyDataResponse, CreateViewRequest, CreateViewResponse, DeleteDataRequest, DeleteDataResponse, DeleteManyDataRequest, DeleteManyDataResponse, DeleteViewRequest, DeleteViewResponse, FindDataRequest, FindDataResponse, GetDataRequest, GetDataResponse, GetDiscoveryRequest, GetDiscoveryResponse, GetEffectivePermissionsRequest, GetEffectivePermissionsResponse, GetFieldLabelsRequest, GetFieldLabelsResponse, GetLocalesRequest, GetLocalesResponse, GetMetaItemCachedRequest, GetMetaItemCachedResponse, GetMetaItemRequest, GetMetaItemResponse, GetMetaItemsRequest, GetMetaItemsResponse, GetMetaTypesRequest, GetMetaTypesResponse, GetNotificationPreferencesRequest, GetNotificationPreferencesResponse, GetObjectPermissionsRequest, GetObjectPermissionsResponse, GetPresenceRequest, GetPresenceResponse, GetTranslationsRequest, GetTranslationsResponse, GetUiViewRequest, GetUiViewResponse, GetViewRequest, GetViewResponse, GetWorkflowConfigRequest, GetWorkflowConfigResponse, GetWorkflowStateRequest, GetWorkflowStateResponse, ListNotificationsRequest, ListNotificationsResponse, ListViewsRequest, ListViewsResponse, MarkAllNotificationsReadRequest, MarkAllNotificationsReadResponse, MarkNotificationsReadRequest, MarkNotificationsReadResponse, Notification, NotificationPreferences, ObjectStackProtocol, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeDisconnectRequest, RealtimeDisconnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RealtimeUnsubscribeRequest, RealtimeUnsubscribeResponse, RegisterDeviceRequest, RegisterDeviceResponse, SaveMetaItemRequest, SaveMetaItemResponse, SetPresenceRequest, SetPresenceResponse, UnregisterDeviceRequest, UnregisterDeviceResponse, UpdateDataRequest, UpdateDataResponse, UpdateManyDataRequest, UpdateManyDataResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, UpdateViewRequest, UpdateViewResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowState, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api'; + +// Validate data +const result = AiChatRequest.parse(data); +``` + +--- + +## AiChatRequest + + +--- + +## AiChatResponse + + +--- + +## AiInsightsRequest + + +--- + +## AiInsightsResponse + + +--- + +## AiNlqRequest + + +--- + +## AiNlqResponse + + +--- + +## AiSuggestRequest + + +--- + +## AiSuggestResponse + + +--- + +## AutomationTriggerRequest + + +--- + +## AutomationTriggerResponse + + +--- + +## BatchDataRequest + + +--- + +## BatchDataResponse + + +--- + +## CheckPermissionRequest + + +--- + +## CheckPermissionResponse + + +--- + +## CreateDataRequest + + +--- + +## CreateDataResponse + + +--- + +## CreateManyDataRequest + + +--- + +## CreateManyDataResponse + + +--- + +## CreateViewRequest + + +--- + +## CreateViewResponse + + +--- + +## DeleteDataRequest + + +--- + +## DeleteDataResponse + + +--- + +## DeleteManyDataRequest + + +--- + +## DeleteManyDataResponse + + +--- + +## DeleteViewRequest + + +--- + +## DeleteViewResponse + + +--- + +## FindDataRequest + + +--- + +## FindDataResponse + + +--- + +## GetDataRequest + + +--- + +## GetDataResponse + + +--- + +## GetDiscoveryRequest + + +--- + +## GetDiscoveryResponse + + +--- + +## GetEffectivePermissionsRequest + + +--- + +## GetEffectivePermissionsResponse + + +--- + +## GetFieldLabelsRequest + + +--- + +## GetFieldLabelsResponse + + +--- + +## GetLocalesRequest + + +--- + +## GetLocalesResponse + + +--- + +## GetMetaItemCachedRequest + + +--- + +## GetMetaItemCachedResponse + + +--- + +## GetMetaItemRequest + + +--- + +## GetMetaItemResponse + + +--- + +## GetMetaItemsRequest + + +--- + +## GetMetaItemsResponse + + +--- + +## GetMetaTypesRequest + + +--- + +## GetMetaTypesResponse + + +--- + +## GetNotificationPreferencesRequest + + +--- + +## GetNotificationPreferencesResponse + + +--- + +## GetObjectPermissionsRequest + + +--- + +## GetObjectPermissionsResponse + + +--- + +## GetPresenceRequest + + +--- + +## GetPresenceResponse + + +--- + +## GetTranslationsRequest + + +--- + +## GetTranslationsResponse + + +--- + +## GetUiViewRequest + + +--- + +## GetUiViewResponse + + +--- + +## GetViewRequest + + +--- + +## GetViewResponse + + +--- + +## GetWorkflowConfigRequest + + +--- + +## GetWorkflowConfigResponse + + +--- + +## GetWorkflowStateRequest + + +--- + +## GetWorkflowStateResponse + + +--- + +## ListNotificationsRequest + + +--- + +## ListNotificationsResponse + + +--- + +## ListViewsRequest + + +--- + +## ListViewsResponse + + +--- + +## MarkAllNotificationsReadRequest + + +--- + +## MarkAllNotificationsReadResponse + + +--- + +## MarkNotificationsReadRequest + + +--- + +## MarkNotificationsReadResponse + + +--- + +## Notification + + +--- + +## NotificationPreferences + + +--- + +## ObjectStackProtocol + + +--- + +## RealtimeConnectRequest + + +--- + +## RealtimeConnectResponse + + +--- + +## RealtimeDisconnectRequest + + +--- + +## RealtimeDisconnectResponse + + +--- + +## RealtimeSubscribeRequest + + +--- + +## RealtimeSubscribeResponse + + +--- + +## RealtimeUnsubscribeRequest + + +--- + +## RealtimeUnsubscribeResponse + + +--- + +## RegisterDeviceRequest + + +--- + +## RegisterDeviceResponse + + +--- + +## SaveMetaItemRequest + + +--- + +## SaveMetaItemResponse + + +--- + +## SetPresenceRequest + + +--- + +## SetPresenceResponse + + +--- + +## UnregisterDeviceRequest + + +--- + +## UnregisterDeviceResponse + + +--- + +## UpdateDataRequest + + +--- + +## UpdateDataResponse + + +--- + +## UpdateManyDataRequest + + +--- + +## UpdateManyDataResponse + + +--- + +## UpdateNotificationPreferencesRequest + + +--- + +## UpdateNotificationPreferencesResponse + + +--- + +## UpdateViewRequest + + +--- + +## UpdateViewResponse + + +--- + +## WorkflowApproveRequest + + +--- + +## WorkflowApproveResponse + + +--- + +## WorkflowRejectRequest + + +--- + +## WorkflowRejectResponse + + +--- + +## WorkflowState + + +--- + +## WorkflowTransitionRequest + + +--- + +## WorkflowTransitionResponse + + +--- + diff --git a/content/docs/references/api/realtime.mdx b/content/docs/references/api/realtime.mdx new file mode 100644 index 000000000..333fcb16d --- /dev/null +++ b/content/docs/references/api/realtime.mdx @@ -0,0 +1,70 @@ +--- +title: Realtime +description: Realtime protocol schemas +--- + +Transport Protocol Enum + +Defines the communication protocol for realtime data synchronization + + +**Source:** `packages/spec/src/api/realtime.zod.ts` + + +## TypeScript Usage + +```typescript +import { RealtimeAction, RealtimeConfig, RealtimeEvent, RealtimeEventType, RealtimePresence, RealtimePresenceStatus, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api'; +import type { RealtimeAction, RealtimeConfig, RealtimeEvent, RealtimeEventType, RealtimePresence, RealtimePresenceStatus, Subscription, SubscriptionEvent, TransportProtocol } from '@objectstack/spec/api'; + +// Validate data +const result = RealtimeAction.parse(data); +``` + +--- + +## RealtimeAction + + +--- + +## RealtimeConfig + + +--- + +## RealtimeEvent + + +--- + +## RealtimeEventType + + +--- + +## RealtimePresence + + +--- + +## RealtimePresenceStatus + + +--- + +## Subscription + + +--- + +## SubscriptionEvent + + +--- + +## TransportProtocol + + +--- + diff --git a/content/docs/references/api/registry.mdx b/content/docs/references/api/registry.mdx new file mode 100644 index 000000000..e5d597578 --- /dev/null +++ b/content/docs/references/api/registry.mdx @@ -0,0 +1,142 @@ +--- +title: Registry +description: Registry protocol schemas +--- + +Unified API Registry Protocol + +Provides a centralized registry for managing all API endpoints across different + +API types (REST, GraphQL, OData, WebSocket, Auth, File, Plugin-registered). + +This enables: + +- Unified API discovery and documentation (similar to Swagger/OpenAPI) + +- API testing interfaces + +- API governance and monitoring + +- Plugin API registration + +- Multi-protocol support + +Architecture Alignment: + +- Kubernetes: Service Discovery & API Server + +- AWS API Gateway: Unified API Management + +- Kong Gateway: Plugin-based API Management + +@example API Registry Entry + +```typescript + +const apiEntry: ApiRegistryEntry = { + +id: 'customer_crud', + +name: 'Customer CRUD API', + +type: 'rest', + +version: 'v1', + +basePath: '/api/v1/data/customer', + +endpoints: [...], + +metadata: { + +owner: 'sales_team', + +tags: ['customer', 'crm'] + +} + +} + +``` + + +**Source:** `packages/spec/src/api/registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiMetadata, ApiParameter, ApiProtocolType, ApiRegistry, ApiRegistryEntry, ApiResponse, ConflictResolutionStrategy, HttpStatusCode, ObjectQLReference, SchemaDefinition } from '@objectstack/spec/api'; +import type { ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiMetadata, ApiParameter, ApiProtocolType, ApiRegistry, ApiRegistryEntry, ApiResponse, ConflictResolutionStrategy, HttpStatusCode, ObjectQLReference, SchemaDefinition } from '@objectstack/spec/api'; + +// Validate data +const result = ApiDiscoveryQuery.parse(data); +``` + +--- + +## ApiDiscoveryQuery + + +--- + +## ApiDiscoveryResponse + + +--- + +## ApiEndpointRegistration + + +--- + +## ApiMetadata + + +--- + +## ApiParameter + + +--- + +## ApiProtocolType + + +--- + +## ApiRegistry + + +--- + +## ApiRegistryEntry + + +--- + +## ApiResponse + + +--- + +## ConflictResolutionStrategy + + +--- + +## HttpStatusCode + + +--- + +## ObjectQLReference + + +--- + +## SchemaDefinition + + +--- + diff --git a/content/docs/references/api/rest-server.mdx b/content/docs/references/api/rest-server.mdx new file mode 100644 index 000000000..66aae21a1 --- /dev/null +++ b/content/docs/references/api/rest-server.mdx @@ -0,0 +1,97 @@ +--- +title: Rest Server +description: Rest Server protocol schemas +--- + +REST API Server Protocol + +Defines the REST API server configuration for automatically generating + +RESTful CRUD endpoints, metadata endpoints, and batch operations. + +Features: + +- Automatic CRUD endpoint generation from Object definitions + +- Standard REST conventions (GET, POST, PUT, PATCH, DELETE) + +- Metadata API endpoints + +- Batch operation endpoints + +- OpenAPI/Swagger documentation generation + +Architecture alignment: + +- Salesforce: REST API with Object CRUD + +- Microsoft Dynamics: Web API with entity operations + +- Strapi: Auto-generated REST endpoints + + +**Source:** `packages/spec/src/api/rest-server.zod.ts` + + +## TypeScript Usage + +```typescript +import { BatchEndpointsConfig, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api'; +import type { BatchEndpointsConfig, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api'; + +// Validate data +const result = BatchEndpointsConfig.parse(data); +``` + +--- + +## BatchEndpointsConfig + + +--- + +## CrudEndpointPattern + + +--- + +## CrudEndpointsConfig + + +--- + +## CrudOperation + + +--- + +## EndpointRegistry + + +--- + +## GeneratedEndpoint + + +--- + +## MetadataEndpointsConfig + + +--- + +## RestApiConfig + + +--- + +## RestServerConfig + + +--- + +## RouteGenerationConfig + + +--- + diff --git a/content/docs/references/api/router.mdx b/content/docs/references/api/router.mdx new file mode 100644 index 000000000..054720031 --- /dev/null +++ b/content/docs/references/api/router.mdx @@ -0,0 +1,40 @@ +--- +title: Router +description: Router protocol schemas +--- + +Route Category Enum + +Classifies routes for middleware application and security policies. + + +**Source:** `packages/spec/src/api/router.zod.ts` + + +## TypeScript Usage + +```typescript +import { RouteCategory, RouteDefinition, RouterConfig } from '@objectstack/spec/api'; +import type { RouteCategory, RouteDefinition, RouterConfig } from '@objectstack/spec/api'; + +// Validate data +const result = RouteCategory.parse(data); +``` + +--- + +## RouteCategory + + +--- + +## RouteDefinition + + +--- + +## RouterConfig + + +--- + diff --git a/content/docs/references/api/storage.mdx b/content/docs/references/api/storage.mdx new file mode 100644 index 000000000..b951ec9b4 --- /dev/null +++ b/content/docs/references/api/storage.mdx @@ -0,0 +1,49 @@ +--- +title: Storage +description: Storage protocol schemas +--- + +Storage Service Protocol + +Defines the API contract for client-side file operations. + +Focuses on secure, direct-to-cloud uploads (Presigned URLs) + +rather than proxying bytes through the API server. + + +**Source:** `packages/spec/src/api/storage.zod.ts` + + +## TypeScript Usage + +```typescript +import { CompleteUploadRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse } from '@objectstack/spec/api'; +import type { CompleteUploadRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse } from '@objectstack/spec/api'; + +// Validate data +const result = CompleteUploadRequest.parse(data); +``` + +--- + +## CompleteUploadRequest + + +--- + +## FileUploadResponse + + +--- + +## GetPresignedUrlRequest + + +--- + +## PresignedUrlResponse + + +--- + diff --git a/content/docs/references/api/view.mdx b/content/docs/references/api/view.mdx new file mode 100644 index 000000000..004962318 --- /dev/null +++ b/content/docs/references/api/view.mdx @@ -0,0 +1,26 @@ +--- +title: View +description: View protocol schemas +--- + + +**Source:** `packages/spec/src/api/view.zod.ts` + + +## TypeScript Usage + +```typescript +import { HttpMethod } from '@objectstack/spec/api'; +import type { HttpMethod } from '@objectstack/spec/api'; + +// Validate data +const result = HttpMethod.parse(data); +``` + +--- + +## HttpMethod + + +--- + diff --git a/content/docs/references/api/websocket.mdx b/content/docs/references/api/websocket.mdx new file mode 100644 index 000000000..9d13d1027 --- /dev/null +++ b/content/docs/references/api/websocket.mdx @@ -0,0 +1,179 @@ +--- +title: Websocket +description: Websocket protocol schemas +--- + +WebSocket Event Protocol + +Defines the schema for WebSocket-based real-time communication in ObjectStack. + +Supports event subscriptions, filtering, presence tracking, and collaborative editing. + +Industry alignment: Firebase Realtime Database, Socket.IO, Pusher + + +**Source:** `packages/spec/src/api/websocket.zod.ts` + + +## TypeScript Usage + +```typescript +import { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api'; +import type { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api'; + +// Validate data +const result = AckMessage.parse(data); +``` + +--- + +## AckMessage + + +--- + +## CursorMessage + + +--- + +## CursorPosition + + +--- + +## DocumentState + + +--- + +## EditMessage + + +--- + +## EditOperation + + +--- + +## EditOperationType + + +--- + +## ErrorMessage + + +--- + +## EventFilter + + +--- + +## EventFilterCondition + + +--- + +## EventMessage + + +--- + +## EventPattern + + +--- + +## EventSubscription + + +--- + +## FilterOperator + + +--- + +## PingMessage + + +--- + +## PongMessage + + +--- + +## PresenceMessage + + +--- + +## PresenceState + + +--- + +## PresenceUpdate + + +--- + +## SimpleCursorPosition + + +--- + +## SimplePresenceState + + +--- + +## SubscribeMessage + + +--- + +## UnsubscribeMessage + + +--- + +## UnsubscribeRequest + + +--- + +## WebSocketConfig + + +--- + +## WebSocketEvent + + +--- + +## WebSocketMessage + + +--- + +## WebSocketMessageType + + +--- + +## WebSocketPresenceStatus + + +--- + +## WebSocketServerConfig + + +--- + diff --git a/content/docs/references/automation/approval.mdx b/content/docs/references/automation/approval.mdx new file mode 100644 index 000000000..896d74877 --- /dev/null +++ b/content/docs/references/automation/approval.mdx @@ -0,0 +1,48 @@ +--- +title: Approval +description: Approval protocol schemas +--- + +Approval Step Approver Type + + +**Source:** `packages/spec/src/automation/approval.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApprovalAction, ApprovalActionType, ApprovalProcess, ApprovalStep, ApproverType } from '@objectstack/spec/automation'; +import type { ApprovalAction, ApprovalActionType, ApprovalProcess, ApprovalStep, ApproverType } from '@objectstack/spec/automation'; + +// Validate data +const result = ApprovalAction.parse(data); +``` + +--- + +## ApprovalAction + + +--- + +## ApprovalActionType + + +--- + +## ApprovalProcess + + +--- + +## ApprovalStep + + +--- + +## ApproverType + + +--- + diff --git a/content/docs/references/automation/connector.mdx b/content/docs/references/automation/connector.mdx new file mode 100644 index 000000000..624b90bf0 --- /dev/null +++ b/content/docs/references/automation/connector.mdx @@ -0,0 +1,41 @@ +--- +title: Connector +description: Connector protocol schemas +--- + + +**Source:** `packages/spec/src/automation/connector.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConflictResolution, Connector, ConnectorTrigger, DataSyncConfig } from '@objectstack/spec/automation'; +import type { ConflictResolution, Connector, ConnectorTrigger, DataSyncConfig } from '@objectstack/spec/automation'; + +// Validate data +const result = ConflictResolution.parse(data); +``` + +--- + +## ConflictResolution + + +--- + +## Connector + + +--- + +## ConnectorTrigger + + +--- + +## DataSyncConfig + + +--- + diff --git a/content/docs/references/automation/etl.mdx b/content/docs/references/automation/etl.mdx new file mode 100644 index 000000000..5945358c5 --- /dev/null +++ b/content/docs/references/automation/etl.mdx @@ -0,0 +1,192 @@ +--- +title: Etl +description: Etl protocol schemas +--- + +ETL (Extract, Transform, Load) Pipeline Protocol - LEVEL 2: Data Engineering + +Inspired by modern data integration platforms like Airbyte, Fivetran, and Apache NiFi. + +**Positioning in 3-Layer Architecture:** + +- **L1: Simple Sync** (automation/sync.zod.ts) - Business users - Sync Salesforce to Sheets + +- **L2: ETL Pipeline** (THIS FILE) - Data engineers - Aggregate 10 sources to warehouse + +- **L3: Enterprise Connector** (integration/connector.zod.ts) - System integrators - Full SAP integration + +ETL pipelines enable automated data synchronization between systems, transforming + +data as it moves from source to destination. + +**SCOPE: Advanced multi-source, multi-stage transformations.** + +Supports complex operations: joins, aggregations, filtering, custom SQL. + +## When to Use This Layer + +**Use ETL Pipeline when:** + +- Combining data from multiple sources + +- Need aggregations, joins, transformations + +- Building data warehouses or analytics platforms + +- Complex data transformations required + +**Examples:** + +- Sales data from Salesforce + Marketing from HubSpot → Data Warehouse + +- Multi-region databases → Consolidated reporting + +- Legacy system migration with transformation + +**When to downgrade:** + +- Simple 1:1 sync → Use [Simple Sync](./sync.zod.ts) + +**When to upgrade:** + +- Need full connector lifecycle (auth, webhooks, rate limits) → Use [Enterprise Connector](../integration/connector.zod.ts) + +@see [./sync.zod.ts](./sync.zod.ts) for Level 1 (simple sync) + +@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration) + +## Use Cases + +1. **Data Warehouse Population** + +- Extract from multiple operational systems + +- Transform to analytical schema + +- Load into data warehouse + +2. **System Integration** + +- Sync data between CRM and Marketing Automation + +- Keep product catalog synchronized across e-commerce platforms + +- Replicate data for backup/disaster recovery + +3. **Data Migration** + +- Move data from legacy systems to modern platforms + +- Consolidate data from multiple sources + +- Split monolithic databases into microservices + +@see https://airbyte.com/ + +@see https://docs.fivetran.com/ + +@see https://nifi.apache.org/ + +@example + +```typescript + +const salesforceToDB: ETLPipeline = { + +name: 'salesforce_to_postgres', + +label: 'Salesforce Accounts to PostgreSQL', + +source: { + +type: 'api', + +connector: 'salesforce', + +config: { object: 'Account' } + +}, + +destination: { + +type: 'database', + +connector: 'postgres', + +config: { table: 'accounts' } + +}, + +transformations: [ + +{ type: 'map', config: { 'Name': 'account_name' } } + +], + +schedule: '0 2 * * *' // Daily at 2 AM + +} + +``` + + +**Source:** `packages/spec/src/automation/etl.zod.ts` + + +## TypeScript Usage + +```typescript +import { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; +import type { ETLDestination, ETLEndpointType, ETLPipeline, ETLPipelineRun, ETLRunStatus, ETLSource, ETLSyncMode, ETLTransformation, ETLTransformationType } from '@objectstack/spec/automation'; + +// Validate data +const result = ETLDestination.parse(data); +``` + +--- + +## ETLDestination + + +--- + +## ETLEndpointType + + +--- + +## ETLPipeline + + +--- + +## ETLPipelineRun + + +--- + +## ETLRunStatus + + +--- + +## ETLSource + + +--- + +## ETLSyncMode + + +--- + +## ETLTransformation + + +--- + +## ETLTransformationType + + +--- + diff --git a/content/docs/references/automation/events.mdx b/content/docs/references/automation/events.mdx new file mode 100644 index 000000000..9f30f43c5 --- /dev/null +++ b/content/docs/references/automation/events.mdx @@ -0,0 +1,26 @@ +--- +title: Events +description: Events protocol schemas +--- + + +**Source:** `packages/spec/src/automation/events.zod.ts` + + +## TypeScript Usage + +```typescript +import { Event } from '@objectstack/spec/automation'; +import type { Event } from '@objectstack/spec/automation'; + +// Validate data +const result = Event.parse(data); +``` + +--- + +## Event + + +--- + diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx new file mode 100644 index 000000000..54aed34e4 --- /dev/null +++ b/content/docs/references/automation/flow.mdx @@ -0,0 +1,48 @@ +--- +title: Flow +description: Flow protocol schemas +--- + +Flow Node Types + + +**Source:** `packages/spec/src/automation/flow.zod.ts` + + +## TypeScript Usage + +```typescript +import { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; +import type { Flow, FlowEdge, FlowNode, FlowNodeAction, FlowVariable } from '@objectstack/spec/automation'; + +// Validate data +const result = Flow.parse(data); +``` + +--- + +## Flow + + +--- + +## FlowEdge + + +--- + +## FlowNode + + +--- + +## FlowNodeAction + + +--- + +## FlowVariable + + +--- + diff --git a/content/docs/references/automation/meta.json b/content/docs/references/automation/meta.json new file mode 100644 index 000000000..09fde8421 --- /dev/null +++ b/content/docs/references/automation/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Automation Protocol", + "pages": [ + "approval", + "connector", + "etl", + "events", + "flow", + "state-machine", + "sync", + "trigger-registry", + "webhook", + "workflow" + ] +} \ No newline at end of file diff --git a/content/docs/references/automation/state-machine.mdx b/content/docs/references/automation/state-machine.mdx new file mode 100644 index 000000000..23f28619b --- /dev/null +++ b/content/docs/references/automation/state-machine.mdx @@ -0,0 +1,52 @@ +--- +title: State Machine +description: State Machine protocol schemas +--- + +XState-inspired State Machine Protocol + +Used to define strict business logic constraints and lifecycle management. + +Prevent AI "hallucinations" by enforcing valid valid transitions. + + +**Source:** `packages/spec/src/automation/state-machine.zod.ts` + + +## TypeScript Usage + +```typescript +import { ActionRef, GuardRef, StateMachine, StateNode, Transition } from '@objectstack/spec/automation'; +import type { ActionRef, GuardRef, StateMachine, StateNode, Transition } from '@objectstack/spec/automation'; + +// Validate data +const result = ActionRef.parse(data); +``` + +--- + +## ActionRef + + +--- + +## GuardRef + + +--- + +## StateMachine + + +--- + +## StateNode + + +--- + +## Transition + + +--- + diff --git a/content/docs/references/automation/sync.mdx b/content/docs/references/automation/sync.mdx new file mode 100644 index 000000000..7079b5ab5 --- /dev/null +++ b/content/docs/references/automation/sync.mdx @@ -0,0 +1,181 @@ +--- +title: Sync +description: Sync protocol schemas +--- + +Data Sync Protocol - LEVEL 1: Simple Synchronization + +Inspired by Salesforce Connect, Segment Sync, and Census Reverse ETL. + +**Positioning in 3-Layer Architecture:** + +- **L1: Simple Sync** (THIS FILE) - Business users - Sync Salesforce to Sheets + +- **L2: ETL Pipeline** (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse + +- **L3: Enterprise Connector** (integration/connector.zod.ts) - System integrators - Full SAP integration + +Data sync provides bidirectional or unidirectional data synchronization + +between ObjectStack and external systems, maintaining data consistency + +across platforms. + +**SCOPE: Simple field mappings only. NO complex transformations.** + +For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (Level 2). + +## When to Use This Layer + +**Use Simple Sync when:** + +- Syncing 1:1 fields between two systems + +- Simple field transformations (uppercase, cast, etc.) + +- No complex logic required + +- Business users need to configure integrations + +**Examples:** + +- Salesforce Contact ↔ Google Sheets + +- HubSpot Company ↔ CRM Account + +- Shopify Orders → Accounting System + +**When to upgrade:** + +- Need multi-source joins → Use [ETL Pipeline](./etl.zod.ts) + +- Need complex authentication/webhooks → Use [Enterprise Connector](../integration/connector.zod.ts) + +- Need aggregations or data warehousing → Use [ETL Pipeline](./etl.zod.ts) + +@see [./etl.zod.ts](./etl.zod.ts) for Level 2 (data engineering) + +@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration) + +## Use Cases + +1. **CRM Integration** + +- Sync contacts between ObjectStack and Salesforce + +- Keep opportunity data synchronized + +- Bidirectional updates + +2. **Customer Data Platform (CDP)** + +- Sync user profiles to Segment + +- Enrichment data from Clearbit + +- Marketing automation sync + +3. **Operational Analytics** + +- Sync production data to analytics warehouse + +- Real-time dashboards + +- Business intelligence + +@see https://help.salesforce.com/s/articleView?id=sf.platform_connect_about.htm + +@see https://segment.com/docs/connections/sync/ + +@see https://www.getcensus.com/ + +@example + +```typescript + +const contactSync: DataSyncConfig = { + +name: 'salesforce_contact_sync', + +label: 'Salesforce Contact Sync', + +source: { + +object: 'contact', + +filters: { status: 'active' } + +}, + +destination: { + +connector: 'salesforce', + +operation: 'upsert_contact', + +mapping: { + +first_name: 'FirstName', + +last_name: 'LastName', + +email: 'Email' + +} + +}, + +syncMode: 'incremental', + +schedule: '0 * * * *' // Hourly + +} + +``` + + +**Source:** `packages/spec/src/automation/sync.zod.ts` + + +## TypeScript Usage + +```typescript +import { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; +import type { DataDestinationConfig, DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation'; + +// Validate data +const result = DataDestinationConfig.parse(data); +``` + +--- + +## DataDestinationConfig + + +--- + +## DataSourceConfig + + +--- + +## SyncDirection + + +--- + +## SyncExecutionResult + + +--- + +## SyncExecutionStatus + + +--- + +## SyncMode + + +--- + diff --git a/content/docs/references/automation/trigger-registry.mdx b/content/docs/references/automation/trigger-registry.mdx new file mode 100644 index 000000000..906f2f0c0 --- /dev/null +++ b/content/docs/references/automation/trigger-registry.mdx @@ -0,0 +1,160 @@ +--- +title: Trigger Registry +description: Trigger Registry protocol schemas +--- + +Trigger Registry Protocol + +Lightweight automation triggers for simple integrations. + +Inspired by Zapier, n8n, and Workato connector architectures. + +## When to use Trigger Registry vs. Integration Connector? + +**Use `automation/trigger-registry.zod.ts` when:** + +- Building simple automation triggers (e.g., "when Slack message received, create task") + +- No complex authentication needed (simple API keys, basic auth) + +- Lightweight, single-purpose integrations + +- Quick setup with minimal configuration + +- Webhook-based or polling triggers for automation workflows + +**Use `integration/connector.zod.ts` when:** + +- Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) + +- Complex OAuth2/SAML authentication required + +- Bidirectional sync with field mapping and transformations + +- Webhook management and rate limiting required + +- Full CRUD operations and data synchronization + +## Use Cases + +1. **Simple Automation Triggers** + +- Slack notifications on record updates + +- Twilio SMS on workflow events + +- SendGrid email templates + +2. **Lightweight Operations** + +- Single-action integrations (send, notify, log) + +- No bidirectional sync required + +- Webhook receivers for incoming events + +3. **Quick Integrations** + +- Payment webhooks (Stripe, PayPal) + +- Communication triggers (Twilio, SendGrid, Slack) + +- Simple API calls to third-party services + +@see https://zapier.com/developer/documentation/v2/ + +@see https://docs.n8n.io/integrations/creating-nodes/ + +@see ../../integration/connector.zod.ts for enterprise connectors + +@example + +```typescript + +const slackNotifier: Connector = { + +id: 'slack_notify', + +name: 'Slack Notification', + +category: 'communication', + +authentication: { + +type: 'apiKey', + +fields: [{ name: 'webhook_url', label: 'Webhook URL', type: 'url' }] + +}, + +operations: [ + +{ id: 'send_message', name: 'Send Message', type: 'action' } + +] + +} + +``` + + +**Source:** `packages/spec/src/automation/trigger-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuthField, Authentication, AuthenticationType, ConnectorCategory, ConnectorInstance, ConnectorOperation, OAuth2Config, OperationParameter, OperationType } from '@objectstack/spec/automation'; +import type { AuthField, Authentication, AuthenticationType, ConnectorCategory, ConnectorInstance, ConnectorOperation, OAuth2Config, OperationParameter, OperationType } from '@objectstack/spec/automation'; + +// Validate data +const result = AuthField.parse(data); +``` + +--- + +## AuthField + + +--- + +## Authentication + + +--- + +## AuthenticationType + + +--- + +## ConnectorCategory + + +--- + +## ConnectorInstance + + +--- + +## ConnectorOperation + + +--- + +## OAuth2Config + + +--- + +## OperationParameter + + +--- + +## OperationType + + +--- + diff --git a/content/docs/references/automation/webhook.mdx b/content/docs/references/automation/webhook.mdx new file mode 100644 index 000000000..278e34403 --- /dev/null +++ b/content/docs/references/automation/webhook.mdx @@ -0,0 +1,40 @@ +--- +title: Webhook +description: Webhook protocol schemas +--- + +Webhook Trigger Event + +When should this webhook fire? + + +**Source:** `packages/spec/src/automation/webhook.zod.ts` + + +## TypeScript Usage + +```typescript +import { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation'; +import type { Webhook, WebhookReceiver, WebhookTriggerType } from '@objectstack/spec/automation'; + +// Validate data +const result = Webhook.parse(data); +``` + +--- + +## Webhook + + +--- + +## WebhookReceiver + + +--- + +## WebhookTriggerType + + +--- + diff --git a/content/docs/references/automation/workflow.mdx b/content/docs/references/automation/workflow.mdx new file mode 100644 index 000000000..41c4da011 --- /dev/null +++ b/content/docs/references/automation/workflow.mdx @@ -0,0 +1,78 @@ +--- +title: Workflow +description: Workflow protocol schemas +--- + +Trigger events for workflow automation + + +**Source:** `packages/spec/src/automation/workflow.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConnectorActionRef, CustomScriptAction, EmailAlertAction, FieldUpdateAction, HttpCallAction, PushNotificationAction, TaskCreationAction, TimeTrigger, WorkflowAction, WorkflowRule, WorkflowTriggerType } from '@objectstack/spec/automation'; +import type { ConnectorActionRef, CustomScriptAction, EmailAlertAction, FieldUpdateAction, HttpCallAction, PushNotificationAction, TaskCreationAction, TimeTrigger, WorkflowAction, WorkflowRule, WorkflowTriggerType } from '@objectstack/spec/automation'; + +// Validate data +const result = ConnectorActionRef.parse(data); +``` + +--- + +## ConnectorActionRef + + +--- + +## CustomScriptAction + + +--- + +## EmailAlertAction + + +--- + +## FieldUpdateAction + + +--- + +## HttpCallAction + + +--- + +## PushNotificationAction + + +--- + +## TaskCreationAction + + +--- + +## TimeTrigger + + +--- + +## WorkflowAction + + +--- + +## WorkflowRule + + +--- + +## WorkflowTriggerType + + +--- + diff --git a/content/docs/references/contracts/meta.json b/content/docs/references/contracts/meta.json new file mode 100644 index 000000000..532dffd33 --- /dev/null +++ b/content/docs/references/contracts/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Contracts Protocol", + "pages": [] +} \ No newline at end of file diff --git a/content/docs/references/data/analytics.mdx b/content/docs/references/data/analytics.mdx new file mode 100644 index 000000000..87de8ce86 --- /dev/null +++ b/content/docs/references/data/analytics.mdx @@ -0,0 +1,71 @@ +--- +title: Analytics +description: Analytics protocol schemas +--- + +Analytics/Semantic Layer Protocol + +Defines the "Business Logic" for data analysis. + +Inspired by Cube.dev, LookML, and dbt MetricFlow. + +This layer decouples the "Physical Data" (Tables/Columns) from the + +"Business Data" (Metrics/Dimensions). + + +**Source:** `packages/spec/src/data/analytics.zod.ts` + + +## TypeScript Usage + +```typescript +import { AggregationMetricType, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data'; +import type { AggregationMetricType, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data'; + +// Validate data +const result = AggregationMetricType.parse(data); +``` + +--- + +## AggregationMetricType + + +--- + +## AnalyticsQuery + + +--- + +## Cube + + +--- + +## CubeJoin + + +--- + +## Dimension + + +--- + +## DimensionType + + +--- + +## Metric + + +--- + +## TimeUpdateInterval + + +--- + diff --git a/content/docs/references/data/data-engine.mdx b/content/docs/references/data/data-engine.mdx new file mode 100644 index 000000000..58ad69d2c --- /dev/null +++ b/content/docs/references/data/data-engine.mdx @@ -0,0 +1,133 @@ +--- +title: Data Engine +description: Data Engine protocol schemas +--- + +Data Engine Protocol + +Defines the standard interface for data persistence engines in ObjectStack. + +This protocol abstracts the underlying storage mechanism (SQL, NoSQL, API, Memory), + +allowing the ObjectQL engine to execute standardized CRUD and Aggregation operations + +regardless of where the data resides. + +The Data Engine acts as the "Driver" layer in the Hexagonal Architecture. + + +**Source:** `packages/spec/src/data/data-engine.zod.ts` + + +## TypeScript Usage + +```typescript +import { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineContract, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data'; +import type { DataEngineAggregateOptions, DataEngineAggregateRequest, DataEngineBatchRequest, DataEngineContract, DataEngineCountOptions, DataEngineCountRequest, DataEngineDeleteOptions, DataEngineDeleteRequest, DataEngineExecuteRequest, DataEngineFilter, DataEngineFindOneRequest, DataEngineFindRequest, DataEngineInsertOptions, DataEngineInsertRequest, DataEngineQueryOptions, DataEngineRequest, DataEngineSort, DataEngineUpdateOptions, DataEngineUpdateRequest, DataEngineVectorFindRequest } from '@objectstack/spec/data'; + +// Validate data +const result = DataEngineAggregateOptions.parse(data); +``` + +--- + +## DataEngineAggregateOptions + + +--- + +## DataEngineAggregateRequest + + +--- + +## DataEngineBatchRequest + + +--- + +## DataEngineContract + + +--- + +## DataEngineCountOptions + + +--- + +## DataEngineCountRequest + + +--- + +## DataEngineDeleteOptions + + +--- + +## DataEngineDeleteRequest + + +--- + +## DataEngineExecuteRequest + + +--- + +## DataEngineFilter + + +--- + +## DataEngineFindOneRequest + + +--- + +## DataEngineFindRequest + + +--- + +## DataEngineInsertOptions + + +--- + +## DataEngineInsertRequest + + +--- + +## DataEngineQueryOptions + + +--- + +## DataEngineRequest + + +--- + +## DataEngineSort + + +--- + +## DataEngineUpdateOptions + + +--- + +## DataEngineUpdateRequest + + +--- + +## DataEngineVectorFindRequest + + +--- + diff --git a/content/docs/references/data/dataset.mdx b/content/docs/references/data/dataset.mdx new file mode 100644 index 000000000..399be677d --- /dev/null +++ b/content/docs/references/data/dataset.mdx @@ -0,0 +1,35 @@ +--- +title: Dataset +description: Dataset protocol schemas +--- + +Data Import Strategy + +Defines how the engine handles existing records. + + +**Source:** `packages/spec/src/data/dataset.zod.ts` + + +## TypeScript Usage + +```typescript +import { Dataset, DatasetMode } from '@objectstack/spec/data'; +import type { Dataset, DatasetMode } from '@objectstack/spec/data'; + +// Validate data +const result = Dataset.parse(data); +``` + +--- + +## Dataset + + +--- + +## DatasetMode + + +--- + diff --git a/content/docs/references/data/datasource.mdx b/content/docs/references/data/datasource.mdx new file mode 100644 index 000000000..4d4b68f54 --- /dev/null +++ b/content/docs/references/data/datasource.mdx @@ -0,0 +1,45 @@ +--- +title: Datasource +description: Datasource protocol schemas +--- + +Driver Identifier + +Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowflake"). + + +**Source:** `packages/spec/src/data/datasource.zod.ts` + + +## TypeScript Usage + +```typescript +import { Datasource, DatasourceCapabilities, DriverDefinition, DriverType } from '@objectstack/spec/data'; +import type { Datasource, DatasourceCapabilities, DriverDefinition, DriverType } from '@objectstack/spec/data'; + +// Validate data +const result = Datasource.parse(data); +``` + +--- + +## Datasource + + +--- + +## DatasourceCapabilities + + +--- + +## DriverDefinition + + +--- + +## DriverType + + +--- + diff --git a/content/docs/references/data/document.mdx b/content/docs/references/data/document.mdx new file mode 100644 index 000000000..24eed7bf1 --- /dev/null +++ b/content/docs/references/data/document.mdx @@ -0,0 +1,71 @@ +--- +title: Document +description: Document protocol schemas +--- + +Document Version Schema + +Represents a single version of a document in a version-controlled system. + +Each version is immutable and maintains its own metadata and download URL. + +@example + +```json + +{ + +"versionNumber": 2, + +"createdAt": 1704067200000, + +"createdBy": "user_123", + +"size": 2048576, + +"checksum": "a1b2c3d4e5f6", + +"downloadUrl": "https://storage.example.com/docs/v2/file.pdf", + +"isLatest": true + +} + +``` + + +**Source:** `packages/spec/src/data/document.zod.ts` + + +## TypeScript Usage + +```typescript +import { Document, DocumentTemplate, DocumentVersion, ESignatureConfig } from '@objectstack/spec/data'; +import type { Document, DocumentTemplate, DocumentVersion, ESignatureConfig } from '@objectstack/spec/data'; + +// Validate data +const result = Document.parse(data); +``` + +--- + +## Document + + +--- + +## DocumentTemplate + + +--- + +## DocumentVersion + + +--- + +## ESignatureConfig + + +--- + diff --git a/content/docs/references/data/driver-nosql.mdx b/content/docs/references/data/driver-nosql.mdx new file mode 100644 index 000000000..8d695b35d --- /dev/null +++ b/content/docs/references/data/driver-nosql.mdx @@ -0,0 +1,95 @@ +--- +title: Driver Nosql +description: Driver Nosql protocol schemas +--- + +NoSQL Database Type Enumeration + +Supported NoSQL database types + + +**Source:** `packages/spec/src/data/driver-nosql.zod.ts` + + +## TypeScript Usage + +```typescript +import { AggregationPipeline, AggregationStage, ConsistencyLevel, DocumentValidationSchema, NoSQLDataTypeMapping, NoSQLDatabaseType, NoSQLDriverConfig, NoSQLIndex, NoSQLIndexType, NoSQLOperationType, NoSQLQueryOptions, NoSQLTransactionOptions, ReplicationConfig, ShardingConfig } from '@objectstack/spec/data'; +import type { AggregationPipeline, AggregationStage, ConsistencyLevel, DocumentValidation, NoSQLDataTypeMapping, NoSQLDatabaseType, NoSQLDriverConfig, NoSQLIndex, NoSQLIndexType, NoSQLOperationType, NoSQLQueryOptions, NoSQLTransactionOptions, ReplicationConfig, ShardingConfig } from '@objectstack/spec/data'; + +// Validate data +const result = AggregationPipeline.parse(data); +``` + +--- + +## AggregationPipeline + + +--- + +## AggregationStage + + +--- + +## ConsistencyLevel + + +--- + +## DocumentValidationSchema + + +--- + +## NoSQLDataTypeMapping + + +--- + +## NoSQLDatabaseType + + +--- + +## NoSQLDriverConfig + + +--- + +## NoSQLIndex + + +--- + +## NoSQLIndexType + + +--- + +## NoSQLOperationType + + +--- + +## NoSQLQueryOptions + + +--- + +## NoSQLTransactionOptions + + +--- + +## ReplicationConfig + + +--- + +## ShardingConfig + + +--- + diff --git a/content/docs/references/data/driver-sql.mdx b/content/docs/references/data/driver-sql.mdx new file mode 100644 index 000000000..74f54d672 --- /dev/null +++ b/content/docs/references/data/driver-sql.mdx @@ -0,0 +1,45 @@ +--- +title: Driver Sql +description: Driver Sql protocol schemas +--- + +SQL Dialect Enumeration + +Supported SQL database dialects + + +**Source:** `packages/spec/src/data/driver-sql.zod.ts` + + +## TypeScript Usage + +```typescript +import { DataTypeMapping, SQLDialect, SQLDriverConfig, SSLConfig } from '@objectstack/spec/data'; +import type { DataTypeMapping, SQLDialect, SQLDriverConfig, SSLConfig } from '@objectstack/spec/data'; + +// Validate data +const result = DataTypeMapping.parse(data); +``` + +--- + +## DataTypeMapping + + +--- + +## SQLDialect + + +--- + +## SQLDriverConfig + + +--- + +## SSLConfig + + +--- + diff --git a/content/docs/references/data/driver.mdx b/content/docs/references/data/driver.mdx new file mode 100644 index 000000000..84ac6468d --- /dev/null +++ b/content/docs/references/data/driver.mdx @@ -0,0 +1,50 @@ +--- +title: Driver +description: Driver protocol schemas +--- + +Common Driver Options + +Passed to most driver methods to control behavior (transactions, timeouts, etc.) + + +**Source:** `packages/spec/src/data/driver.zod.ts` + + +## TypeScript Usage + +```typescript +import { DriverCapabilities, DriverConfig, DriverInterface, DriverOptions, PoolConfig } from '@objectstack/spec/data'; +import type { DriverCapabilities, DriverConfig, DriverInterface, DriverOptions, PoolConfig } from '@objectstack/spec/data'; + +// Validate data +const result = DriverCapabilities.parse(data); +``` + +--- + +## DriverCapabilities + + +--- + +## DriverConfig + + +--- + +## DriverInterface + + +--- + +## DriverOptions + + +--- + +## PoolConfig + + +--- + diff --git a/content/docs/references/data/external-lookup.mdx b/content/docs/references/data/external-lookup.mdx new file mode 100644 index 000000000..e0a5434cc --- /dev/null +++ b/content/docs/references/data/external-lookup.mdx @@ -0,0 +1,76 @@ +--- +title: External Lookup +description: External Lookup protocol schemas +--- + +External Data Source Schema + +Configuration for connecting to external data systems. + +Similar to Salesforce External Objects for real-time data integration. + +@example + +```json + +{ + +"id": "salesforce-accounts", + +"name": "Salesforce Account Data", + +"type": "rest-api", + +"endpoint": "https://api.salesforce.com/services/data/v58.0", + +"authentication": { + +"type": "oauth2", + +"config": { + +"clientId": "...", + +"clientSecret": "...", + +"tokenUrl": "https://login.salesforce.com/services/oauth2/token" + +} + +} + +} + +``` + + +**Source:** `packages/spec/src/data/external-lookup.zod.ts` + + +## TypeScript Usage + +```typescript +import { ExternalDataSource, ExternalFieldMapping, ExternalLookup } from '@objectstack/spec/data'; +import type { ExternalDataSource, ExternalFieldMapping, ExternalLookup } from '@objectstack/spec/data'; + +// Validate data +const result = ExternalDataSource.parse(data); +``` + +--- + +## ExternalDataSource + + +--- + +## ExternalFieldMapping + + +--- + +## ExternalLookup + + +--- + diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx new file mode 100644 index 000000000..3e504cfcd --- /dev/null +++ b/content/docs/references/data/field.mdx @@ -0,0 +1,78 @@ +--- +title: Field +description: Field protocol schemas +--- + +Field Type Enum + + +**Source:** `packages/spec/src/data/field.zod.ts` + + +## TypeScript Usage + +```typescript +import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; +import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data'; + +// Validate data +const result = Address.parse(data); +``` + +--- + +## Address + + +--- + +## ComputedFieldCache + + +--- + +## CurrencyConfig + + +--- + +## CurrencyValue + + +--- + +## DataQualityRules + + +--- + +## Field + + +--- + +## FieldType + + +--- + +## FileAttachmentConfig + + +--- + +## LocationCoordinates + + +--- + +## SelectOption + + +--- + +## VectorConfig + + +--- + diff --git a/content/docs/references/data/filter.mdx b/content/docs/references/data/filter.mdx new file mode 100644 index 000000000..fcc72a057 --- /dev/null +++ b/content/docs/references/data/filter.mdx @@ -0,0 +1,106 @@ +--- +title: Filter +description: Filter protocol schemas +--- + +Unified Query DSL Specification + +Based on industry best practices from: + +- Prisma ORM + +- Strapi CMS + +- TypeORM + +- LoopBack Framework + +Version: 1.0.0 + +Status: Draft + +Objective: Define a JSON-based, database-agnostic query syntax standard + +for data filtering interactions between frontend and backend APIs. + +Design Principles: + +1. Declarative: Frontend describes "what data to get", not "how to query" + +2. Database Agnostic: Syntax contains no database-specific directives + +3. Type Safe: Structure can be statically inferred by TypeScript + +4. Convention over Configuration: Implicit syntax for common queries + + +**Source:** `packages/spec/src/data/filter.zod.ts` + + +## TypeScript Usage + +```typescript +import { ComparisonOperator, EqualityOperator, FieldOperators, FieldReference, FilterCondition, NormalizedFilter, QueryFilter, RangeOperator, SetOperator, SpecialOperator, StringOperator } from '@objectstack/spec/data'; +import type { ComparisonOperator, EqualityOperator, FieldOperators, FieldReference, FilterCondition, NormalizedFilter, QueryFilter, RangeOperator, SetOperator, SpecialOperator, StringOperator } from '@objectstack/spec/data'; + +// Validate data +const result = ComparisonOperator.parse(data); +``` + +--- + +## ComparisonOperator + + +--- + +## EqualityOperator + + +--- + +## FieldOperators + + +--- + +## FieldReference + + +--- + +## FilterCondition + + +--- + +## NormalizedFilter + + +--- + +## QueryFilter + + +--- + +## RangeOperator + + +--- + +## SetOperator + + +--- + +## SpecialOperator + + +--- + +## StringOperator + + +--- + diff --git a/content/docs/references/data/hook.mdx b/content/docs/references/data/hook.mdx new file mode 100644 index 000000000..a04ffe3ed --- /dev/null +++ b/content/docs/references/data/hook.mdx @@ -0,0 +1,40 @@ +--- +title: Hook +description: Hook protocol schemas +--- + +Hook Lifecycle Events + +Defines the interception points in the ObjectQL execution pipeline. + + +**Source:** `packages/spec/src/data/hook.zod.ts` + + +## TypeScript Usage + +```typescript +import { Hook, HookContext, HookEvent } from '@objectstack/spec/data'; +import type { Hook, HookContext, HookEvent } from '@objectstack/spec/data'; + +// Validate data +const result = Hook.parse(data); +``` + +--- + +## Hook + + +--- + +## HookContext + + +--- + +## HookEvent + + +--- + diff --git a/content/docs/references/data/mapping.mdx b/content/docs/references/data/mapping.mdx new file mode 100644 index 000000000..309a2be43 --- /dev/null +++ b/content/docs/references/data/mapping.mdx @@ -0,0 +1,40 @@ +--- +title: Mapping +description: Mapping protocol schemas +--- + +Transformation Logic + +Built-in helpers for converting data during import. + + +**Source:** `packages/spec/src/data/mapping.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldMapping, Mapping, TransformType } from '@objectstack/spec/data'; +import type { FieldMapping, Mapping, TransformType } from '@objectstack/spec/data'; + +// Validate data +const result = FieldMapping.parse(data); +``` + +--- + +## FieldMapping + + +--- + +## Mapping + + +--- + +## TransformType + + +--- + diff --git a/content/docs/references/data/meta.json b/content/docs/references/data/meta.json new file mode 100644 index 000000000..f7eee50bd --- /dev/null +++ b/content/docs/references/data/meta.json @@ -0,0 +1,22 @@ +{ + "title": "Data Protocol", + "pages": [ + "analytics", + "data-engine", + "dataset", + "datasource", + "document", + "driver", + "driver-nosql", + "driver-sql", + "external-lookup", + "field", + "filter", + "hook", + "mapping", + "object", + "query", + "search-engine", + "validation" + ] +} \ No newline at end of file diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx new file mode 100644 index 000000000..b079c525d --- /dev/null +++ b/content/docs/references/data/object.mdx @@ -0,0 +1,78 @@ +--- +title: Object +description: Object protocol schemas +--- + +API Operations Enum + + +**Source:** `packages/spec/src/data/object.zod.ts` + + +## TypeScript Usage + +```typescript +import { ApiMethod, CDCConfig, Index, Object, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; +import type { ApiMethod, CDCConfig, Index, Object, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data'; + +// Validate data +const result = ApiMethod.parse(data); +``` + +--- + +## ApiMethod + + +--- + +## CDCConfig + + +--- + +## Index + + +--- + +## Object + + +--- + +## ObjectCapabilities + + +--- + +## ObjectExtension + + +--- + +## ObjectOwnershipEnum + + +--- + +## PartitioningConfig + + +--- + +## SoftDeleteConfig + + +--- + +## TenancyConfig + + +--- + +## VersioningConfig + + +--- + diff --git a/content/docs/references/data/query.mdx b/content/docs/references/data/query.mdx new file mode 100644 index 000000000..7c82245b0 --- /dev/null +++ b/content/docs/references/data/query.mdx @@ -0,0 +1,85 @@ +--- +title: Query +description: Query protocol schemas +--- + +Sort Node + +Represents "Order By". + + +**Source:** `packages/spec/src/data/query.zod.ts` + + +## TypeScript Usage + +```typescript +import { AggregationFunction, AggregationNode, FieldNode, FullTextSearch, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data'; +import type { AggregationFunction, AggregationNode, FieldNode, FullTextSearch, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data'; + +// Validate data +const result = AggregationFunction.parse(data); +``` + +--- + +## AggregationFunction + + +--- + +## AggregationNode + + +--- + +## FieldNode + + +--- + +## FullTextSearch + + +--- + +## JoinNode + + +--- + +## JoinStrategy + + +--- + +## JoinType + + +--- + +## Query + + +--- + +## SortNode + + +--- + +## WindowFunction + + +--- + +## WindowFunctionNode + + +--- + +## WindowSpec + + +--- + diff --git a/content/docs/references/data/search-engine.mdx b/content/docs/references/data/search-engine.mdx new file mode 100644 index 000000000..d2a3fbbc9 --- /dev/null +++ b/content/docs/references/data/search-engine.mdx @@ -0,0 +1,26 @@ +--- +title: Search Engine +description: Search Engine protocol schemas +--- + + +**Source:** `packages/spec/src/data/search-engine.zod.ts` + + +## TypeScript Usage + +```typescript +import { SearchConfig } from '@objectstack/spec/data'; +import type { SearchConfig } from '@objectstack/spec/data'; + +// Validate data +const result = SearchConfig.parse(data); +``` + +--- + +## SearchConfig + + +--- + diff --git a/content/docs/references/data/validation.mdx b/content/docs/references/data/validation.mdx new file mode 100644 index 000000000..bb726af1b --- /dev/null +++ b/content/docs/references/data/validation.mdx @@ -0,0 +1,139 @@ +--- +title: Validation +description: Validation protocol schemas +--- + +# ObjectStack Validation Protocol + +This module defines the validation schema protocol for ObjectStack, providing a comprehensive + +type-safe validation system similar to Salesforce's validation rules but with enhanced capabilities. + +## Overview + +Validation rules are applied at the data layer to ensure data integrity and enforce business logic. + +The system supports multiple validation types: + +1. **Script Validation**: Formula-based validation using expressions + +2. **Uniqueness Validation**: Enforce unique constraints across fields + +3. **State Machine Validation**: Control allowed state transitions + +4. **Format Validation**: Validate field formats (email, URL, regex, etc.) + +5. **Cross-Field Validation**: Validate relationships between multiple fields + +6. **Async Validation**: Remote validation via API calls + +7. **Custom Validation**: User-defined validation functions + +8. **Conditional Validation**: Apply validations based on conditions + +## Salesforce Comparison + +ObjectStack validation rules are inspired by Salesforce validation rules but enhanced: + +- Salesforce: Formula-based validation with `Error Condition Formula` + +- ObjectStack: Multiple validation types with composable rules + +Example Salesforce validation rule: + +``` + +Rule Name: Discount_Cannot_Exceed_40_Percent + +Error Condition Formula: Discount_Percent__c > 0.40 + +Error Message: Discount cannot exceed 40%. + +``` + +Equivalent ObjectStack rule: + +```typescript + +{ + +type: 'script', + +name: 'discount_cannot_exceed_40_percent', + +condition: 'discount_percent > 0.40', + +message: 'Discount cannot exceed 40%', + +severity: 'error' + +} + +``` + + +**Source:** `packages/spec/src/data/validation.zod.ts` + + +## TypeScript Usage + +```typescript +import { AsyncValidation, ConditionalValidation, CrossFieldValidation, CustomValidator, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, UniquenessValidation, ValidationRule } from '@objectstack/spec/data'; +import type { AsyncValidation, ConditionalValidation, CrossFieldValidation, CustomValidator, FormatValidation, JSONValidation, ScriptValidation, StateMachineValidation, UniquenessValidation, ValidationRule } from '@objectstack/spec/data'; + +// Validate data +const result = AsyncValidation.parse(data); +``` + +--- + +## AsyncValidation + + +--- + +## ConditionalValidation + + +--- + +## CrossFieldValidation + + +--- + +## CustomValidator + + +--- + +## FormatValidation + + +--- + +## JSONValidation + + +--- + +## ScriptValidation + + +--- + +## StateMachineValidation + + +--- + +## UniquenessValidation + + +--- + +## ValidationRule + + +--- + diff --git a/content/docs/references/identity/identity.mdx b/content/docs/references/identity/identity.mdx new file mode 100644 index 000000000..65d4763d4 --- /dev/null +++ b/content/docs/references/identity/identity.mdx @@ -0,0 +1,51 @@ +--- +title: Identity +description: Identity protocol schemas +--- + +Identity & User Model Specification + +Defines the standard user, account, and session data models for ObjectStack. + +These schemas represent "who is logged in" and their associated data. + +This is separate from authentication configuration (auth.zod.ts) which + +defines "how to login". + + +**Source:** `packages/spec/src/identity/identity.zod.ts` + + +## TypeScript Usage + +```typescript +import { Account, Session, User, VerificationToken } from '@objectstack/spec/identity'; +import type { Account, Session, User, VerificationToken } from '@objectstack/spec/identity'; + +// Validate data +const result = Account.parse(data); +``` + +--- + +## Account + + +--- + +## Session + + +--- + +## User + + +--- + +## VerificationToken + + +--- + diff --git a/content/docs/references/identity/meta.json b/content/docs/references/identity/meta.json new file mode 100644 index 000000000..782d0bb30 --- /dev/null +++ b/content/docs/references/identity/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Identity Protocol", + "pages": [ + "identity", + "organization", + "role", + "scim" + ] +} \ No newline at end of file diff --git a/content/docs/references/identity/organization.mdx b/content/docs/references/identity/organization.mdx new file mode 100644 index 000000000..c884257a0 --- /dev/null +++ b/content/docs/references/identity/organization.mdx @@ -0,0 +1,49 @@ +--- +title: Organization +description: Organization protocol schemas +--- + +Organization Schema (Multi-Tenant Architecture) + +Defines the standard organization/workspace model for ObjectStack. + +Supports B2B SaaS scenarios where users belong to multiple teams/workspaces. + +This aligns with better-auth's organization plugin capabilities. + + +**Source:** `packages/spec/src/identity/organization.zod.ts` + + +## TypeScript Usage + +```typescript +import { Invitation, InvitationStatus, Member, Organization } from '@objectstack/spec/identity'; +import type { Invitation, InvitationStatus, Member, Organization } from '@objectstack/spec/identity'; + +// Validate data +const result = Invitation.parse(data); +``` + +--- + +## Invitation + + +--- + +## InvitationStatus + + +--- + +## Member + + +--- + +## Organization + + +--- + diff --git a/content/docs/references/identity/role.mdx b/content/docs/references/identity/role.mdx new file mode 100644 index 000000000..ad8d099d7 --- /dev/null +++ b/content/docs/references/identity/role.mdx @@ -0,0 +1,64 @@ +--- +title: Role +description: Role protocol schemas +--- + +Role Schema (aka Business Unit / Org Unit) + +Defines the organizational hierarchy (Reporting Structure). + +COMPARISON: + +- Salesforce: "Role" (Hierarchy for visibility rollup) + +- Microsoft: "Business Unit" (Structural container for data) + +- Kubernetes/AWS: "Role" usually refers to Permissions (we use PermissionSet for that) + +ROLES IN OBJECTSTACK: + +Used primarily for "Reporting Structure" - Managers see subordinates' data. + +**NAMING CONVENTION:** + +Role names MUST be lowercase snake_case to prevent security issues. + +@example Good role names + +- 'sales_manager' + +- 'ceo' + +- 'region_east_vp' + +- 'engineering_lead' + +@example Bad role names (will be rejected) + +- 'SalesManager' (camelCase) + +- 'CEO' (uppercase) + +- 'Region East VP' (spaces and uppercase) + + +**Source:** `packages/spec/src/identity/role.zod.ts` + + +## TypeScript Usage + +```typescript +import { Role } from '@objectstack/spec/identity'; +import type { Role } from '@objectstack/spec/identity'; + +// Validate data +const result = Role.parse(data); +``` + +--- + +## Role + + +--- + diff --git a/content/docs/references/identity/scim.mdx b/content/docs/references/identity/scim.mdx new file mode 100644 index 000000000..5b9880e8e --- /dev/null +++ b/content/docs/references/identity/scim.mdx @@ -0,0 +1,161 @@ +--- +title: Scim +description: Scim protocol schemas +--- + +# SCIM 2.0 Protocol Implementation + +System for Cross-domain Identity Management (SCIM) 2.0 specification + +implementation for ObjectStack. + +## Overview + +SCIM 2.0 is an HTTP-based protocol for managing user and group identities + +across domains. It provides a standardized REST API for user provisioning, + +de-provisioning, and synchronization. + +## Use Cases + +1. **Enterprise SSO Integration** + +- Integrate with Okta, Azure AD, OneLogin + +- Automatic user provisioning from corporate directory + +- Just-in-Time (JIT) user creation on first login + +2. **User Lifecycle Management** + +- Automatically create users when they join organization + +- Update user attributes when they change roles + +- Deactivate users when they leave organization + +3. **Group/Department Synchronization** + +- Sync organizational structure from AD/LDAP + +- Maintain group memberships automatically + +- Map corporate roles to application permissions + +4. **Compliance & Audit** + +- Maintain accurate user directory + +- Track all identity changes + +- Meet SOX/HIPAA requirements for user management + +## Specification References + +- **RFC 7643**: SCIM Core Schema + +- **RFC 7644**: SCIM Protocol + +- **RFC 7642**: SCIM Requirements + +## Industry Implementations + +- **Okta**: Leading SCIM provider + +- **Azure AD**: Microsoft's identity platform + +- **OneLogin**: Enterprise SSO provider + +- **Google Workspace**: Google's identity management + +@see https://datatracker.ietf.org/doc/html/rfc7643 + +@see https://datatracker.ietf.org/doc/html/rfc7644 + + +**Source:** `packages/spec/src/identity/scim.zod.ts` + + +## TypeScript Usage + +```typescript +import { SCIMAddress, SCIMEmail, SCIMEnterpriseUser, SCIMError, SCIMGroup, SCIMGroupReference, SCIMListResponse, SCIMMemberReference, SCIMMeta, SCIMName, SCIMPatchOperation, SCIMPatchRequest, SCIMPhoneNumber, SCIMUser } from '@objectstack/spec/identity'; +import type { SCIMAddress, SCIMEmail, SCIMEnterpriseUser, SCIMError, SCIMGroup, SCIMGroupReference, SCIMListResponse, SCIMMemberReference, SCIMMeta, SCIMName, SCIMPatchOperation, SCIMPatchRequest, SCIMPhoneNumber, SCIMUser } from '@objectstack/spec/identity'; + +// Validate data +const result = SCIMAddress.parse(data); +``` + +--- + +## SCIMAddress + + +--- + +## SCIMEmail + + +--- + +## SCIMEnterpriseUser + + +--- + +## SCIMError + + +--- + +## SCIMGroup + + +--- + +## SCIMGroupReference + + +--- + +## SCIMListResponse + + +--- + +## SCIMMemberReference + + +--- + +## SCIMMeta + + +--- + +## SCIMName + + +--- + +## SCIMPatchOperation + + +--- + +## SCIMPatchRequest + + +--- + +## SCIMPhoneNumber + + +--- + +## SCIMUser + + +--- + diff --git a/content/docs/references/integration/connector.mdx b/content/docs/references/integration/connector.mdx new file mode 100644 index 000000000..ca8deeb23 --- /dev/null +++ b/content/docs/references/integration/connector.mdx @@ -0,0 +1,181 @@ +--- +title: Connector +description: Connector protocol schemas +--- + +Connector Protocol - LEVEL 3: Enterprise Connector + +Defines the standard connector specification for external system integration. + +Connectors enable ObjectStack to sync data with SaaS apps, databases, file storage, + +and message queues through a unified protocol. + +**Positioning in 3-Layer Architecture:** + +- **L1: Simple Sync** (automation/sync.zod.ts) - Business users - Sync Salesforce to Sheets + +- **L2: ETL Pipeline** (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse + +- **L3: Enterprise Connector** (THIS FILE) - System integrators - Full SAP integration + +**SCOPE: Most comprehensive integration layer.** + +Includes authentication, webhooks, rate limiting, field mapping, bidirectional sync, + +retry policies, and complete lifecycle management. + +This protocol supports multiple authentication strategies, bidirectional sync, + +field mapping, webhooks, and comprehensive rate limiting. + +Authentication is now imported from the canonical auth/config.zod.ts. + +## When to Use This Layer + +**Use Enterprise Connector when:** + +- Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) + +- Complex OAuth2/SAML authentication required + +- Bidirectional sync with field mapping and transformations + +- Webhook management and rate limiting required + +- Full CRUD operations and data synchronization + +- Need comprehensive retry strategies and error handling + +**Examples:** + +- Full Salesforce integration with webhooks + +- SAP ERP connector with CDC (Change Data Capture) + +- Microsoft Dynamics 365 connector + +**When to downgrade:** + +- Simple field sync → Use [Simple Sync](../automation/sync.zod.ts) + +- Data transformation only → Use [ETL Pipeline](../automation/etl.zod.ts) + +@see [../automation/sync.zod.ts](../automation/sync.zod.ts) for Level 1 (simple sync) + +@see [../automation/etl.zod.ts](../automation/etl.zod.ts) for Level 2 (data engineering) + +## When to use Integration Connector vs. Trigger Registry? + +**Use `integration/connector.zod.ts` when:** + +- Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle) + +- Complex OAuth2/SAML authentication required + +- Bidirectional sync with field mapping and transformations + +- Webhook management and rate limiting required + +- Full CRUD operations and data synchronization + +- Need comprehensive retry strategies and error handling + +**Use `automation/trigger-registry.zod.ts` when:** + +- Building simple automation triggers (e.g., "when Slack message received, create task") + +- No complex authentication needed (simple API keys, basic auth) + +- Lightweight, single-purpose integrations + +- Quick setup with minimal configuration + +@see ../../automation/trigger-registry.zod.ts for lightweight automation triggers + + +**Source:** `packages/spec/src/integration/connector.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConflictResolution, Connector, ConnectorAction, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; +import type { ConflictResolution, Connector, ConnectorAction, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration'; + +// Validate data +const result = ConflictResolution.parse(data); +``` + +--- + +## ConflictResolution + + +--- + +## Connector + + +--- + +## ConnectorAction + + +--- + +## ConnectorStatus + + +--- + +## ConnectorTrigger + + +--- + +## ConnectorType + + +--- + +## DataSyncConfig + + +--- + +## RateLimitStrategy + + +--- + +## RetryConfig + + +--- + +## RetryStrategy + + +--- + +## SyncStrategy + + +--- + +## WebhookConfig + + +--- + +## WebhookEvent + + +--- + +## WebhookSignatureAlgorithm + + +--- + diff --git a/content/docs/references/integration/http.mdx b/content/docs/references/integration/http.mdx new file mode 100644 index 000000000..00dcc4f0c --- /dev/null +++ b/content/docs/references/integration/http.mdx @@ -0,0 +1,26 @@ +--- +title: Http +description: Http protocol schemas +--- + + +**Source:** `packages/spec/src/integration/http.zod.ts` + + +## TypeScript Usage + +```typescript +import { RateLimitConfig } from '@objectstack/spec/integration'; +import type { RateLimitConfig } from '@objectstack/spec/integration'; + +// Validate data +const result = RateLimitConfig.parse(data); +``` + +--- + +## RateLimitConfig + + +--- + diff --git a/content/docs/references/integration/mapping.mdx b/content/docs/references/integration/mapping.mdx new file mode 100644 index 000000000..c6092aa44 --- /dev/null +++ b/content/docs/references/integration/mapping.mdx @@ -0,0 +1,26 @@ +--- +title: Mapping +description: Mapping protocol schemas +--- + + +**Source:** `packages/spec/src/integration/mapping.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldMapping } from '@objectstack/spec/integration'; +import type { FieldMapping } from '@objectstack/spec/integration'; + +// Validate data +const result = FieldMapping.parse(data); +``` + +--- + +## FieldMapping + + +--- + diff --git a/content/docs/references/integration/message-queue.mdx b/content/docs/references/integration/message-queue.mdx new file mode 100644 index 000000000..63c5a1c9a --- /dev/null +++ b/content/docs/references/integration/message-queue.mdx @@ -0,0 +1,31 @@ +--- +title: Message Queue +description: Message Queue protocol schemas +--- + + +**Source:** `packages/spec/src/integration/message-queue.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConsumerConfig, MessageQueueProvider } from '@objectstack/spec/integration'; +import type { ConsumerConfig, MessageQueueProvider } from '@objectstack/spec/integration'; + +// Validate data +const result = ConsumerConfig.parse(data); +``` + +--- + +## ConsumerConfig + + +--- + +## MessageQueueProvider + + +--- + diff --git a/content/docs/references/integration/meta.json b/content/docs/references/integration/meta.json new file mode 100644 index 000000000..43bfa6991 --- /dev/null +++ b/content/docs/references/integration/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Integration Protocol", + "pages": [ + "connector", + "http", + "mapping", + "message-queue", + "misc", + "object-storage" + ] +} \ No newline at end of file diff --git a/content/docs/references/integration/misc.mdx b/content/docs/references/integration/misc.mdx new file mode 100644 index 000000000..c8911b61f --- /dev/null +++ b/content/docs/references/integration/misc.mdx @@ -0,0 +1,241 @@ +--- +title: Misc +description: Misc protocol schemas +--- + + +**Source:** `packages/spec/src/integration/misc.zod.ts` + + +## TypeScript Usage + +```typescript +import { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseProvider, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageFormat, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; +import type { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseProvider, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageFormat, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration'; + +// Validate data +const result = AckMode.parse(data); +``` + +--- + +## AckMode + + +--- + +## ApiVersionConfig + + +--- + +## BuildConfig + + +--- + +## CdcConfig + + +--- + +## DatabaseConnector + + +--- + +## DatabasePoolConfig + + +--- + +## DatabaseProvider + + +--- + +## DatabaseTable + + +--- + +## DeliveryGuarantee + + +--- + +## DeploymentConfig + + +--- + +## DlqConfig + + +--- + +## DomainConfig + + +--- + +## EdgeFunctionConfig + + +--- + +## EnvironmentVariables + + +--- + +## FileAccessPattern + + +--- + +## FileFilterConfig + + +--- + +## FileMetadataConfig + + +--- + +## FileStorageConnector + + +--- + +## FileStorageProvider + + +--- + +## FileVersioningConfig + + +--- + +## GitHubActionsWorkflow + + +--- + +## GitHubCommitConfig + + +--- + +## GitHubConnector + + +--- + +## GitHubIssueTracking + + +--- + +## GitHubProvider + + +--- + +## GitHubPullRequestConfig + + +--- + +## GitHubReleaseConfig + + +--- + +## GitHubRepository + + +--- + +## GitRepositoryConfig + + +--- + +## MessageFormat + + +--- + +## MessageQueueConnector + + +--- + +## ProducerConfig + + +--- + +## SaasConnector + + +--- + +## SaasObjectType + + +--- + +## SaasProvider + + +--- + +## SslConfig + + +--- + +## StorageBucket + + +--- + +## TopicQueue + + +--- + +## VercelConnector + + +--- + +## VercelFramework + + +--- + +## VercelMonitoring + + +--- + +## VercelProject + + +--- + +## VercelProvider + + +--- + +## VercelTeam + + +--- + diff --git a/content/docs/references/integration/object-storage.mdx b/content/docs/references/integration/object-storage.mdx new file mode 100644 index 000000000..2ca32e54e --- /dev/null +++ b/content/docs/references/integration/object-storage.mdx @@ -0,0 +1,26 @@ +--- +title: Object Storage +description: Object Storage protocol schemas +--- + + +**Source:** `packages/spec/src/integration/object-storage.zod.ts` + + +## TypeScript Usage + +```typescript +import { MultipartUploadConfig } from '@objectstack/spec/integration'; +import type { MultipartUploadConfig } from '@objectstack/spec/integration'; + +// Validate data +const result = MultipartUploadConfig.parse(data); +``` + +--- + +## MultipartUploadConfig + + +--- + diff --git a/content/docs/references/kernel/context.mdx b/content/docs/references/kernel/context.mdx new file mode 100644 index 000000000..a0f90d00c --- /dev/null +++ b/content/docs/references/kernel/context.mdx @@ -0,0 +1,35 @@ +--- +title: Context +description: Context protocol schemas +--- + +Runtime Mode Enum + +Defines the operating mode of the kernel + + +**Source:** `packages/spec/src/kernel/context.zod.ts` + + +## TypeScript Usage + +```typescript +import { KernelContext, RuntimeMode } from '@objectstack/spec/kernel'; +import type { KernelContext, RuntimeMode } from '@objectstack/spec/kernel'; + +// Validate data +const result = KernelContext.parse(data); +``` + +--- + +## KernelContext + + +--- + +## RuntimeMode + + +--- + diff --git a/content/docs/references/kernel/events.mdx b/content/docs/references/kernel/events.mdx new file mode 100644 index 000000000..51334d27e --- /dev/null +++ b/content/docs/references/kernel/events.mdx @@ -0,0 +1,107 @@ +--- +title: Events +description: Events protocol schemas +--- + +Event Priority Enum + +Priority levels for event processing + +Lower numbers = higher priority + + +**Source:** `packages/spec/src/kernel/events.zod.ts` + + +## TypeScript Usage + +```typescript +import { DeadLetterQueueEntry, Event, EventBusConfig, EventHandler, EventLogEntry, EventMessageQueueConfig, EventMetadata, EventPersistence, EventPriority, EventQueueConfig, EventReplayConfig, EventRoute, EventSourcingConfig, EventTypeDefinition, EventWebhookConfig, RealTimeNotificationConfig } from '@objectstack/spec/kernel'; +import type { DeadLetterQueueEntry, Event, EventBusConfig, EventHandler, EventLogEntry, EventMessageQueueConfig, EventMetadata, EventPersistence, EventPriority, EventQueueConfig, EventReplayConfig, EventRoute, EventSourcingConfig, EventTypeDefinition, EventWebhookConfig, RealTimeNotificationConfig } from '@objectstack/spec/kernel'; + +// Validate data +const result = DeadLetterQueueEntry.parse(data); +``` + +--- + +## DeadLetterQueueEntry + + +--- + +## Event + + +--- + +## EventBusConfig + + +--- + +## EventHandler + + +--- + +## EventLogEntry + + +--- + +## EventMessageQueueConfig + + +--- + +## EventMetadata + + +--- + +## EventPersistence + + +--- + +## EventPriority + + +--- + +## EventQueueConfig + + +--- + +## EventReplayConfig + + +--- + +## EventRoute + + +--- + +## EventSourcingConfig + + +--- + +## EventTypeDefinition + + +--- + +## EventWebhookConfig + + +--- + +## RealTimeNotificationConfig + + +--- + diff --git a/content/docs/references/kernel/feature.mdx b/content/docs/references/kernel/feature.mdx new file mode 100644 index 000000000..dfd81f989 --- /dev/null +++ b/content/docs/references/kernel/feature.mdx @@ -0,0 +1,33 @@ +--- +title: Feature +description: Feature protocol schemas +--- + +Feature Rollout Strategy + + +**Source:** `packages/spec/src/kernel/feature.zod.ts` + + +## TypeScript Usage + +```typescript +import { FeatureFlag, FeatureStrategy } from '@objectstack/spec/kernel'; +import type { FeatureFlag, FeatureStrategy } from '@objectstack/spec/kernel'; + +// Validate data +const result = FeatureFlag.parse(data); +``` + +--- + +## FeatureFlag + + +--- + +## FeatureStrategy + + +--- + diff --git a/content/docs/references/kernel/manifest.mdx b/content/docs/references/kernel/manifest.mdx new file mode 100644 index 000000000..7b55e99ca --- /dev/null +++ b/content/docs/references/kernel/manifest.mdx @@ -0,0 +1,58 @@ +--- +title: Manifest +description: Manifest protocol schemas +--- + +Schema for the ObjectStack Manifest. + +This defines the structure of a package configuration in the ObjectStack ecosystem. + +All packages (apps, plugins, drivers, modules) must conform to this schema. + +@example App Package + +```yaml + +id: com.acme.crm + +version: 1.0.0 + +type: app + +name: Acme CRM + +description: Customer Relationship Management system + +permissions: + +- system.user.read + +- system.object.create + +objects: + +- "./src/objects/*.object.yml" + +``` + + +**Source:** `packages/spec/src/kernel/manifest.zod.ts` + + +## TypeScript Usage + +```typescript +import { Manifest } from '@objectstack/spec/kernel'; +import type { Manifest } from '@objectstack/spec/kernel'; + +// Validate data +const result = Manifest.parse(data); +``` + +--- + +## Manifest + + +--- + diff --git a/content/docs/references/kernel/meta.json b/content/docs/references/kernel/meta.json new file mode 100644 index 000000000..626b3c1ae --- /dev/null +++ b/content/docs/references/kernel/meta.json @@ -0,0 +1,26 @@ +{ + "title": "Kernel Protocol", + "pages": [ + "context", + "events", + "feature", + "manifest", + "metadata-persistence", + "package-registry", + "permission", + "plugin", + "plugin-capability", + "plugin-lifecycle-advanced", + "plugin-lifecycle-events", + "plugin-loading", + "plugin-registry", + "plugin-runtime", + "plugin-security", + "plugin-security-advanced", + "plugin-structure", + "plugin-validator", + "plugin-versioning", + "service-registry", + "startup-orchestrator" + ] +} \ No newline at end of file diff --git a/content/docs/references/kernel/metadata-persistence.mdx b/content/docs/references/kernel/metadata-persistence.mdx new file mode 100644 index 000000000..afd839528 --- /dev/null +++ b/content/docs/references/kernel/metadata-persistence.mdx @@ -0,0 +1,81 @@ +--- +title: Metadata Persistence +description: Metadata Persistence protocol schemas +--- + + +**Source:** `packages/spec/src/kernel/metadata-persistence.zod.ts` + + +## TypeScript Usage + +```typescript +import { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; +import type { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel'; + +// Validate data +const result = MetadataCollectionInfo.parse(data); +``` + +--- + +## MetadataCollectionInfo + + +--- + +## MetadataExportOptions + + +--- + +## MetadataFormat + + +--- + +## MetadataImportOptions + + +--- + +## MetadataLoadOptions + + +--- + +## MetadataLoadResult + + +--- + +## MetadataLoaderContract + + +--- + +## MetadataManagerConfig + + +--- + +## MetadataSaveOptions + + +--- + +## MetadataSaveResult + + +--- + +## MetadataStats + + +--- + +## MetadataWatchEvent + + +--- + diff --git a/content/docs/references/kernel/package-registry.mdx b/content/docs/references/kernel/package-registry.mdx new file mode 100644 index 000000000..0c1acbdbb --- /dev/null +++ b/content/docs/references/kernel/package-registry.mdx @@ -0,0 +1,121 @@ +--- +title: Package Registry +description: Package Registry protocol schemas +--- + +# Package Registry Protocol + +Defines the runtime state and lifecycle operations for installed packages. + +## Key Distinction: Package vs App + +- **Package (Manifest)**: The unit of installation — a deployable artifact containing + +metadata (objects, actions, flows, etc.) and optionally one or more Apps. + +- **App (AppSchema)**: A UI navigation shell defined inside a package. + +A package may contain: + +- Zero apps (pure functionality plugin, e.g. a storage driver) + +- One app (typical business application) + +- Multiple apps (suite of applications) + +## Architecture Alignment + +- **Salesforce**: Managed Packages with install/uninstall lifecycle + +- **VS Code**: Extension marketplace with enable/disable per-workspace + +- **Kubernetes**: Helm charts with release state tracking + +- **npm**: Package registry with install/uninstall/version management + + +**Source:** `packages/spec/src/kernel/package-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; +import type { DisablePackageRequest, DisablePackageResponse, EnablePackageRequest, EnablePackageResponse, GetPackageRequest, GetPackageResponse, InstallPackageRequest, InstallPackageResponse, InstalledPackage, ListPackagesRequest, ListPackagesResponse, PackageStatusEnum, UninstallPackageRequest, UninstallPackageResponse } from '@objectstack/spec/kernel'; + +// Validate data +const result = DisablePackageRequest.parse(data); +``` + +--- + +## DisablePackageRequest + + +--- + +## DisablePackageResponse + + +--- + +## EnablePackageRequest + + +--- + +## EnablePackageResponse + + +--- + +## GetPackageRequest + + +--- + +## GetPackageResponse + + +--- + +## InstallPackageRequest + + +--- + +## InstallPackageResponse + + +--- + +## InstalledPackage + + +--- + +## ListPackagesRequest + + +--- + +## ListPackagesResponse + + +--- + +## PackageStatusEnum + + +--- + +## UninstallPackageRequest + + +--- + +## UninstallPackageResponse + + +--- + diff --git a/content/docs/references/kernel/permission.mdx b/content/docs/references/kernel/permission.mdx new file mode 100644 index 000000000..bd761ad0b --- /dev/null +++ b/content/docs/references/kernel/permission.mdx @@ -0,0 +1,26 @@ +--- +title: Permission +description: Permission protocol schemas +--- + + +**Source:** `packages/spec/src/kernel/permission.zod.ts` + + +## TypeScript Usage + +```typescript +import { PermissionSet } from '@objectstack/spec/kernel'; +import type { PermissionSet } from '@objectstack/spec/kernel'; + +// Validate data +const result = PermissionSet.parse(data); +``` + +--- + +## PermissionSet + + +--- + diff --git a/content/docs/references/kernel/plugin-capability.mdx b/content/docs/references/kernel/plugin-capability.mdx new file mode 100644 index 000000000..c223db5f6 --- /dev/null +++ b/content/docs/references/kernel/plugin-capability.mdx @@ -0,0 +1,80 @@ +--- +title: Plugin Capability +description: Plugin Capability protocol schemas +--- + +# Plugin Capability Protocol + +Defines the standard way plugins declare their capabilities, implementations, + +and conformance levels to ensure interoperability across vendors. + +Based on the Protocol-Oriented Architecture pattern similar to: + +- Kubernetes CRDs (Custom Resource Definitions) + +- OSGi Service Registry + +- Eclipse Extension Points + + +**Source:** `packages/spec/src/kernel/plugin-capability.zod.ts` + + +## TypeScript Usage + +```typescript +import { CapabilityConformanceLevel, ExtensionPoint, PluginCapability, PluginCapabilityManifest, PluginDependency, PluginInterface, ProtocolFeature, ProtocolReference, ProtocolVersion } from '@objectstack/spec/kernel'; +import type { CapabilityConformanceLevel, ExtensionPoint, PluginCapability, PluginCapabilityManifest, PluginDependency, PluginInterface, ProtocolFeature, ProtocolReference, ProtocolVersion } from '@objectstack/spec/kernel'; + +// Validate data +const result = CapabilityConformanceLevel.parse(data); +``` + +--- + +## CapabilityConformanceLevel + + +--- + +## ExtensionPoint + + +--- + +## PluginCapability + + +--- + +## PluginCapabilityManifest + + +--- + +## PluginDependency + + +--- + +## PluginInterface + + +--- + +## ProtocolFeature + + +--- + +## ProtocolReference + + +--- + +## ProtocolVersion + + +--- + diff --git a/content/docs/references/kernel/plugin-lifecycle-advanced.mdx b/content/docs/references/kernel/plugin-lifecycle-advanced.mdx new file mode 100644 index 000000000..245ec253e --- /dev/null +++ b/content/docs/references/kernel/plugin-lifecycle-advanced.mdx @@ -0,0 +1,82 @@ +--- +title: Plugin Lifecycle Advanced +description: Plugin Lifecycle Advanced protocol schemas +--- + +# Advanced Plugin Lifecycle Protocol + +Defines advanced lifecycle management capabilities including: + +- Hot reload and live updates + +- Graceful degradation and fallback mechanisms + +- Health monitoring and auto-recovery + +- State preservation during updates + +This protocol extends the basic plugin lifecycle with enterprise-grade + +features for production environments. + + +**Source:** `packages/spec/src/kernel/plugin-lifecycle-advanced.zod.ts` + + +## TypeScript Usage + +```typescript +import { AdvancedPluginLifecycleConfig, DistributedStateConfig, GracefulDegradation, HotReloadConfig, PluginHealthCheck, PluginHealthReport, PluginHealthStatus, PluginStateSnapshot, PluginUpdateStrategy } from '@objectstack/spec/kernel'; +import type { AdvancedPluginLifecycleConfig, DistributedStateConfig, GracefulDegradation, HotReloadConfig, PluginHealthCheck, PluginHealthReport, PluginHealthStatus, PluginStateSnapshot, PluginUpdateStrategy } from '@objectstack/spec/kernel'; + +// Validate data +const result = AdvancedPluginLifecycleConfig.parse(data); +``` + +--- + +## AdvancedPluginLifecycleConfig + + +--- + +## DistributedStateConfig + + +--- + +## GracefulDegradation + + +--- + +## HotReloadConfig + + +--- + +## PluginHealthCheck + + +--- + +## PluginHealthReport + + +--- + +## PluginHealthStatus + + +--- + +## PluginStateSnapshot + + +--- + +## PluginUpdateStrategy + + +--- + diff --git a/content/docs/references/kernel/plugin-lifecycle-events.mdx b/content/docs/references/kernel/plugin-lifecycle-events.mdx new file mode 100644 index 000000000..d99507c5f --- /dev/null +++ b/content/docs/references/kernel/plugin-lifecycle-events.mdx @@ -0,0 +1,96 @@ +--- +title: Plugin Lifecycle Events +description: Plugin Lifecycle Events protocol schemas +--- + +Plugin Lifecycle Events Protocol + +Zod schemas for plugin lifecycle event data structures. + +These schemas align with the IPluginLifecycleEvents contract interface. + +Following ObjectStack "Zod First" principle - all data structures + +must have Zod schemas for runtime validation and JSON Schema generation. + + +**Source:** `packages/spec/src/kernel/plugin-lifecycle-events.zod.ts` + + +## TypeScript Usage + +```typescript +import { EventPhase, HookRegisteredEvent, HookTriggeredEvent, KernelEventBase, KernelReadyEvent, KernelShutdownEvent, PluginErrorEvent, PluginEventBase, PluginLifecycleEventType, PluginLifecyclePhaseEvent, PluginRegisteredEvent, ServiceRegisteredEvent, ServiceUnregisteredEvent } from '@objectstack/spec/kernel'; +import type { EventPhase, HookRegisteredEvent, HookTriggeredEvent, KernelEventBase, KernelReadyEvent, KernelShutdownEvent, PluginErrorEvent, PluginEventBase, PluginLifecycleEventType, PluginLifecyclePhaseEvent, PluginRegisteredEvent, ServiceRegisteredEvent, ServiceUnregisteredEvent } from '@objectstack/spec/kernel'; + +// Validate data +const result = EventPhase.parse(data); +``` + +--- + +## EventPhase + + +--- + +## HookRegisteredEvent + + +--- + +## HookTriggeredEvent + + +--- + +## KernelEventBase + + +--- + +## KernelReadyEvent + + +--- + +## KernelShutdownEvent + + +--- + +## PluginErrorEvent + + +--- + +## PluginEventBase + + +--- + +## PluginLifecycleEventType + + +--- + +## PluginLifecyclePhaseEvent + + +--- + +## PluginRegisteredEvent + + +--- + +## ServiceRegisteredEvent + + +--- + +## ServiceUnregisteredEvent + + +--- + diff --git a/content/docs/references/kernel/plugin-loading.mdx b/content/docs/references/kernel/plugin-loading.mdx new file mode 100644 index 000000000..a95d43259 --- /dev/null +++ b/content/docs/references/kernel/plugin-loading.mdx @@ -0,0 +1,112 @@ +--- +title: Plugin Loading +description: Plugin Loading protocol schemas +--- + +# Plugin Loading Protocol + +Defines the enhanced plugin loading mechanism for the microkernel architecture. + +Inspired by industry best practices from: + +- Kubernetes CRDs and Operators + +- OSGi Dynamic Module System + +- Eclipse Plugin Framework + +- Webpack Module Federation + +This protocol enables: + +- Lazy loading and code splitting + +- Dynamic imports and parallel initialization + +- Capability-based discovery + +- Hot reload in development + +- Advanced caching strategies + + +**Source:** `packages/spec/src/kernel/plugin-loading.zod.ts` + + +## TypeScript Usage + +```typescript +import { PluginCaching, PluginCodeSplitting, PluginDependencyResolution, PluginDynamicImport, PluginHotReload, PluginInitialization, PluginLoadingConfig, PluginLoadingEvent, PluginLoadingState, PluginLoadingStrategy, PluginPerformanceMonitoring, PluginPreloadConfig, PluginSandboxing } from '@objectstack/spec/kernel'; +import type { PluginCaching, PluginCodeSplitting, PluginDependencyResolution, PluginDynamicImport, PluginHotReload, PluginInitialization, PluginLoadingConfig, PluginLoadingEvent, PluginLoadingState, PluginLoadingStrategy, PluginPerformanceMonitoring, PluginPreloadConfig, PluginSandboxing } from '@objectstack/spec/kernel'; + +// Validate data +const result = PluginCaching.parse(data); +``` + +--- + +## PluginCaching + + +--- + +## PluginCodeSplitting + + +--- + +## PluginDependencyResolution + + +--- + +## PluginDynamicImport + + +--- + +## PluginHotReload + + +--- + +## PluginInitialization + + +--- + +## PluginLoadingConfig + + +--- + +## PluginLoadingEvent + + +--- + +## PluginLoadingState + + +--- + +## PluginLoadingStrategy + + +--- + +## PluginPerformanceMonitoring + + +--- + +## PluginPreloadConfig + + +--- + +## PluginSandboxing + + +--- + diff --git a/content/docs/references/kernel/plugin-registry.mdx b/content/docs/references/kernel/plugin-registry.mdx new file mode 100644 index 000000000..05d09ca95 --- /dev/null +++ b/content/docs/references/kernel/plugin-registry.mdx @@ -0,0 +1,59 @@ +--- +title: Plugin Registry +description: Plugin Registry protocol schemas +--- + +# Plugin Registry Protocol + +Defines the schema for the plugin discovery and registry system. + +This enables plugins from different vendors to be discovered, validated, + +and composed together in the ObjectStack ecosystem. + + +**Source:** `packages/spec/src/kernel/plugin-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { PluginInstallConfig, PluginQualityMetrics, PluginRegistryEntry, PluginSearchFilters, PluginStatistics, PluginVendor } from '@objectstack/spec/kernel'; +import type { PluginInstallConfig, PluginQualityMetrics, PluginRegistryEntry, PluginSearchFilters, PluginStatistics, PluginVendor } from '@objectstack/spec/kernel'; + +// Validate data +const result = PluginInstallConfig.parse(data); +``` + +--- + +## PluginInstallConfig + + +--- + +## PluginQualityMetrics + + +--- + +## PluginRegistryEntry + + +--- + +## PluginSearchFilters + + +--- + +## PluginStatistics + + +--- + +## PluginVendor + + +--- + diff --git a/content/docs/references/kernel/plugin-security-advanced.mdx b/content/docs/references/kernel/plugin-security-advanced.mdx new file mode 100644 index 000000000..291d2eaab --- /dev/null +++ b/content/docs/references/kernel/plugin-security-advanced.mdx @@ -0,0 +1,94 @@ +--- +title: Plugin Security Advanced +description: Plugin Security Advanced protocol schemas +--- + +# Plugin Security and Sandboxing Protocol + +Defines comprehensive security mechanisms for plugin isolation, permission + +management, and threat protection in the ObjectStack ecosystem. + +Features: + +- Fine-grained permission system + +- Resource access control + +- Sandboxing and isolation + +- Security scanning and verification + +- Runtime security monitoring + + +**Source:** `packages/spec/src/kernel/plugin-security-advanced.zod.ts` + + +## TypeScript Usage + +```typescript +import { KernelSecurityPolicy, KernelSecurityScanResult, KernelSecurityVulnerability, Permission, PermissionAction, PermissionScope, PluginSecurityManifest, PluginTrustLevel, ResourceType, RuntimeConfig, SandboxConfig } from '@objectstack/spec/kernel'; +import type { KernelSecurityPolicy, KernelSecurityScanResult, KernelSecurityVulnerability, Permission, PermissionAction, PermissionScope, PluginSecurityManifest, PluginTrustLevel, ResourceType, RuntimeConfig, SandboxConfig } from '@objectstack/spec/kernel'; + +// Validate data +const result = KernelSecurityPolicy.parse(data); +``` + +--- + +## KernelSecurityPolicy + + +--- + +## KernelSecurityScanResult + + +--- + +## KernelSecurityVulnerability + + +--- + +## Permission + + +--- + +## PermissionAction + + +--- + +## PermissionScope + + +--- + +## PluginSecurityManifest + + +--- + +## PluginTrustLevel + + +--- + +## ResourceType + + +--- + +## RuntimeConfig + + +--- + +## SandboxConfig + + +--- + diff --git a/content/docs/references/kernel/plugin-security.mdx b/content/docs/references/kernel/plugin-security.mdx new file mode 100644 index 000000000..6cf4d1374 --- /dev/null +++ b/content/docs/references/kernel/plugin-security.mdx @@ -0,0 +1,106 @@ +--- +title: Plugin Security +description: Plugin Security protocol schemas +--- + +# Plugin Security & Dependency Resolution Protocol + +Provides comprehensive security scanning, vulnerability management, + +and dependency resolution for the ObjectStack plugin ecosystem. + +Features: + +- CVE/vulnerability scanning + +- Dependency graph resolution + +- Semantic version conflict detection + +- Supply chain security + +- Plugin sandboxing policies + +- Trust and verification workflows + + +**Source:** `packages/spec/src/kernel/plugin-security.zod.ts` + + +## TypeScript Usage + +```typescript +import { DependencyGraph, DependencyGraphNode, PackageDependency, PackageDependencyConflict, PackageDependencyResolutionResult, PluginProvenance, PluginTrustScore, SBOM, SBOMEntry, SecurityPolicy, SecurityScanResult, SecurityVulnerability, VulnerabilitySeverity } from '@objectstack/spec/kernel'; +import type { DependencyGraph, DependencyGraphNode, PackageDependency, PackageDependencyConflict, PackageDependencyResolutionResult, PluginProvenance, PluginTrustScore, SBOM, SBOMEntry, SecurityPolicy, SecurityScanResult, SecurityVulnerability, VulnerabilitySeverity } from '@objectstack/spec/kernel'; + +// Validate data +const result = DependencyGraph.parse(data); +``` + +--- + +## DependencyGraph + + +--- + +## DependencyGraphNode + + +--- + +## PackageDependency + + +--- + +## PackageDependencyConflict + + +--- + +## PackageDependencyResolutionResult + + +--- + +## PluginProvenance + + +--- + +## PluginTrustScore + + +--- + +## SBOM + + +--- + +## SBOMEntry + + +--- + +## SecurityPolicy + + +--- + +## SecurityScanResult + + +--- + +## SecurityVulnerability + + +--- + +## VulnerabilitySeverity + + +--- + diff --git a/content/docs/references/kernel/plugin-structure.mdx b/content/docs/references/kernel/plugin-structure.mdx new file mode 100644 index 000000000..b99844e53 --- /dev/null +++ b/content/docs/references/kernel/plugin-structure.mdx @@ -0,0 +1,44 @@ +--- +title: Plugin Structure +description: Plugin Structure protocol schemas +--- + +ObjectStack Plugin Structure Standards (OPS) + +Formal Zod definitions for the Plugin Directory Structure and File Naming conventions. + +This can be used by the CLI or IDE extensions to lint project structure. + +@see PLUGIN_STANDARDS.md + + +**Source:** `packages/spec/src/kernel/plugin-structure.zod.ts` + + +## TypeScript Usage + +```typescript +import { OpsDomainModule, OpsFilePath, OpsPluginStructure } from '@objectstack/spec/kernel'; +import type { OpsDomainModule, OpsFilePath, OpsPluginStructure } from '@objectstack/spec/kernel'; + +// Validate data +const result = OpsDomainModule.parse(data); +``` + +--- + +## OpsDomainModule + + +--- + +## OpsFilePath + + +--- + +## OpsPluginStructure + + +--- + diff --git a/content/docs/references/kernel/plugin-validator.mdx b/content/docs/references/kernel/plugin-validator.mdx new file mode 100644 index 000000000..3751b410e --- /dev/null +++ b/content/docs/references/kernel/plugin-validator.mdx @@ -0,0 +1,51 @@ +--- +title: Plugin Validator +description: Plugin Validator protocol schemas +--- + +Plugin Validator Protocol + +Zod schemas for plugin validation data structures. + +These schemas align with the IPluginValidator contract interface. + +Following ObjectStack "Zod First" principle - all data structures + +must have Zod schemas for runtime validation and JSON Schema generation. + + +**Source:** `packages/spec/src/kernel/plugin-validator.zod.ts` + + +## TypeScript Usage + +```typescript +import { PluginMetadata, ValidationError, ValidationResult, ValidationWarning } from '@objectstack/spec/kernel'; +import type { PluginMetadata, ValidationError, ValidationResult, ValidationWarning } from '@objectstack/spec/kernel'; + +// Validate data +const result = PluginMetadata.parse(data); +``` + +--- + +## PluginMetadata + + +--- + +## ValidationError + + +--- + +## ValidationResult + + +--- + +## ValidationWarning + + +--- + diff --git a/content/docs/references/kernel/plugin-versioning.mdx b/content/docs/references/kernel/plugin-versioning.mdx new file mode 100644 index 000000000..19b0285ae --- /dev/null +++ b/content/docs/references/kernel/plugin-versioning.mdx @@ -0,0 +1,92 @@ +--- +title: Plugin Versioning +description: Plugin Versioning protocol schemas +--- + +# Plugin Versioning and Compatibility Protocol + +Defines comprehensive versioning, compatibility checking, and dependency + +resolution mechanisms for the plugin ecosystem. + +Based on semantic versioning (SemVer) with extensions for: + +- Compatibility matrices + +- Breaking change detection + +- Migration paths + +- Multi-version support + + +**Source:** `packages/spec/src/kernel/plugin-versioning.zod.ts` + + +## TypeScript Usage + +```typescript +import { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DependencyResolutionResult, DeprecationNotice, MultiVersionSupport, PluginCompatibilityMatrix, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel'; +import type { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DependencyResolutionResult, DeprecationNotice, MultiVersionSupport, PluginCompatibilityMatrix, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel'; + +// Validate data +const result = BreakingChange.parse(data); +``` + +--- + +## BreakingChange + + +--- + +## CompatibilityLevel + + +--- + +## CompatibilityMatrixEntry + + +--- + +## DependencyConflict + + +--- + +## DependencyResolutionResult + + +--- + +## DeprecationNotice + + +--- + +## MultiVersionSupport + + +--- + +## PluginCompatibilityMatrix + + +--- + +## PluginVersionMetadata + + +--- + +## SemanticVersion + + +--- + +## VersionConstraint + + +--- + diff --git a/content/docs/references/kernel/plugin.mdx b/content/docs/references/kernel/plugin.mdx new file mode 100644 index 000000000..492b254ec --- /dev/null +++ b/content/docs/references/kernel/plugin.mdx @@ -0,0 +1,45 @@ +--- +title: Plugin +description: Plugin protocol schemas +--- + +Shared Plugin Types + +These are the specialized plugin types common between Manifest (Package) and Plugin (Runtime). + + +**Source:** `packages/spec/src/kernel/plugin.zod.ts` + + +## TypeScript Usage + +```typescript +import { ActivationEvent, Plugin, PluginContext, PluginLifecycle } from '@objectstack/spec/kernel'; +import type { ActivationEvent, Plugin, PluginContext, PluginLifecycle } from '@objectstack/spec/kernel'; + +// Validate data +const result = ActivationEvent.parse(data); +``` + +--- + +## ActivationEvent + + +--- + +## Plugin + + +--- + +## PluginContext + + +--- + +## PluginLifecycle + + +--- + diff --git a/content/docs/references/kernel/service-registry.mdx b/content/docs/references/kernel/service-registry.mdx new file mode 100644 index 000000000..256f44035 --- /dev/null +++ b/content/docs/references/kernel/service-registry.mdx @@ -0,0 +1,67 @@ +--- +title: Service Registry +description: Service Registry protocol schemas +--- + +Service Registry Protocol + +Zod schemas for service registry data structures. + +These schemas align with the IServiceRegistry contract interface. + +Following ObjectStack "Zod First" principle - all data structures + +must have Zod schemas for runtime validation and JSON Schema generation. + +Note: IServiceRegistry itself is a runtime interface (methods only), + +so it correctly remains a TypeScript interface. This file contains + +schemas for configuration and metadata related to service registry. + + +**Source:** `packages/spec/src/kernel/service-registry.zod.ts` + + +## TypeScript Usage + +```typescript +import { ScopeConfig, ScopeInfo, ServiceFactoryRegistration, ServiceMetadata, ServiceRegistryConfig, ServiceScopeType } from '@objectstack/spec/kernel'; +import type { ScopeConfig, ScopeInfo, ServiceFactoryRegistration, ServiceMetadata, ServiceRegistryConfig, ServiceScopeType } from '@objectstack/spec/kernel'; + +// Validate data +const result = ScopeConfig.parse(data); +``` + +--- + +## ScopeConfig + + +--- + +## ScopeInfo + + +--- + +## ServiceFactoryRegistration + + +--- + +## ServiceMetadata + + +--- + +## ServiceRegistryConfig + + +--- + +## ServiceScopeType + + +--- + diff --git a/content/docs/references/kernel/startup-orchestrator.mdx b/content/docs/references/kernel/startup-orchestrator.mdx new file mode 100644 index 000000000..630c6d1cd --- /dev/null +++ b/content/docs/references/kernel/startup-orchestrator.mdx @@ -0,0 +1,51 @@ +--- +title: Startup Orchestrator +description: Startup Orchestrator protocol schemas +--- + +Startup Orchestrator Protocol + +Zod schemas for plugin startup orchestration data structures. + +These schemas align with the IStartupOrchestrator contract interface. + +Following ObjectStack "Zod First" principle - all data structures + +must have Zod schemas for runtime validation and JSON Schema generation. + + +**Source:** `packages/spec/src/kernel/startup-orchestrator.zod.ts` + + +## TypeScript Usage + +```typescript +import { HealthStatus, PluginStartupResult, StartupOptions, StartupOrchestrationResult } from '@objectstack/spec/kernel'; +import type { HealthStatus, PluginStartupResult, StartupOptions, StartupOrchestrationResult } from '@objectstack/spec/kernel'; + +// Validate data +const result = HealthStatus.parse(data); +``` + +--- + +## HealthStatus + + +--- + +## PluginStartupResult + + +--- + +## StartupOptions + + +--- + +## StartupOrchestrationResult + + +--- + diff --git a/content/docs/references/qa/meta.json b/content/docs/references/qa/meta.json new file mode 100644 index 000000000..f546c4824 --- /dev/null +++ b/content/docs/references/qa/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Qa Protocol", + "pages": [ + "testing" + ] +} \ No newline at end of file diff --git a/content/docs/references/qa/testing.mdx b/content/docs/references/qa/testing.mdx new file mode 100644 index 000000000..187eac6ba --- /dev/null +++ b/content/docs/references/qa/testing.mdx @@ -0,0 +1,61 @@ +--- +title: Testing +description: Testing protocol schemas +--- + + +**Source:** `packages/spec/src/qa/testing.zod.ts` + + +## TypeScript Usage + +```typescript +import { TestAction, TestActionType, TestAssertion, TestAssertionType, TestContext, TestScenario, TestStep, TestSuite } from '@objectstack/spec/qa'; +import type { TestAction, TestActionType, TestAssertion, TestAssertionType, TestContext, TestScenario, TestStep, TestSuite } from '@objectstack/spec/qa'; + +// Validate data +const result = TestAction.parse(data); +``` + +--- + +## TestAction + + +--- + +## TestActionType + + +--- + +## TestAssertion + + +--- + +## TestAssertionType + + +--- + +## TestContext + + +--- + +## TestScenario + + +--- + +## TestStep + + +--- + +## TestSuite + + +--- + diff --git a/content/docs/references/security/meta.json b/content/docs/references/security/meta.json new file mode 100644 index 000000000..e5d72448c --- /dev/null +++ b/content/docs/references/security/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Security Protocol", + "pages": [ + "permission", + "policy", + "rls", + "sharing", + "territory" + ] +} \ No newline at end of file diff --git a/content/docs/references/security/permission.mdx b/content/docs/references/security/permission.mdx new file mode 100644 index 000000000..70a6bdd0a --- /dev/null +++ b/content/docs/references/security/permission.mdx @@ -0,0 +1,48 @@ +--- +title: Permission +description: Permission protocol schemas +--- + +Entity (Object) Level Permissions + +Defines CRUD + VAMA (View All / Modify All) + Lifecycle access. + +Refined with enterprise data lifecycle controls: + +- Transfer (Ownership change) + +- Restore (Soft delete recovery) + +- Purge (Hard delete / Compliance) + + +**Source:** `packages/spec/src/security/permission.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldPermission, ObjectPermission, PermissionSet } from '@objectstack/spec/security'; +import type { FieldPermission, ObjectPermission, PermissionSet } from '@objectstack/spec/security'; + +// Validate data +const result = FieldPermission.parse(data); +``` + +--- + +## FieldPermission + + +--- + +## ObjectPermission + + +--- + +## PermissionSet + + +--- + diff --git a/content/docs/references/security/policy.mdx b/content/docs/references/security/policy.mdx new file mode 100644 index 000000000..fe6c4e394 --- /dev/null +++ b/content/docs/references/security/policy.mdx @@ -0,0 +1,48 @@ +--- +title: Policy +description: Policy protocol schemas +--- + +Password Complexity Policy + + +**Source:** `packages/spec/src/security/policy.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuditPolicy, NetworkPolicy, PasswordPolicy, Policy, SessionPolicy } from '@objectstack/spec/security'; +import type { AuditPolicy, NetworkPolicy, PasswordPolicy, Policy, SessionPolicy } from '@objectstack/spec/security'; + +// Validate data +const result = AuditPolicy.parse(data); +``` + +--- + +## AuditPolicy + + +--- + +## NetworkPolicy + + +--- + +## PasswordPolicy + + +--- + +## Policy + + +--- + +## SessionPolicy + + +--- + diff --git a/content/docs/references/security/rls.mdx b/content/docs/references/security/rls.mdx new file mode 100644 index 000000000..accac8e3c --- /dev/null +++ b/content/docs/references/security/rls.mdx @@ -0,0 +1,178 @@ +--- +title: Rls +description: Rls protocol schemas +--- + +# Row-Level Security (RLS) Protocol + +Implements fine-grained record-level access control inspired by PostgreSQL RLS + +and Salesforce Criteria-Based Sharing Rules. + +## Overview + +Row-Level Security (RLS) allows you to control which rows users can access + +in database tables based on their identity and role. Unlike object-level + +permissions (CRUD), RLS provides record-level filtering. + +## Use Cases + +1. **Multi-Tenant Data Isolation** + +- Users only see records from their organization + +- `using: "tenant_id = current_user.tenant_id"` + +2. **Ownership-Based Access** + +- Users only see records they own + +- `using: "owner_id = current_user.id"` + +3. **Department-Based Access** + +- Users only see records from their department + +- `using: "department = current_user.department"` + +4. **Regional Access Control** + +- Sales reps only see accounts in their territory + +- `using: "region IN (current_user.assigned_regions)"` + +5. **Time-Based Access** + +- Users can only access active records + +- `using: "status = 'active' AND expiry_date > NOW()"` + +## PostgreSQL RLS Comparison + +PostgreSQL RLS Example: + +```sql + +CREATE POLICY tenant_isolation ON accounts + +FOR SELECT + +USING (tenant_id = current_setting('app.current_tenant_id')::uuid); + +CREATE POLICY account_insert ON accounts + +FOR INSERT + +WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::uuid); + +``` + +ObjectStack RLS Equivalent: + +```typescript + +{ + +name: 'tenant_isolation', + +object: 'account', + +operation: 'select', + +using: 'tenant_id = current_user.tenant_id' + +} + +``` + +## Salesforce Sharing Rules Comparison + +Salesforce uses "Sharing Rules" and "Role Hierarchy" for record-level access. + +ObjectStack RLS provides similar functionality with more flexibility. + +Salesforce: + +- Criteria-Based Sharing: Share records matching criteria with users/roles + +- Owner-Based Sharing: Share records based on owner's role + +- Manual Sharing: Individual record sharing + +ObjectStack RLS: + +- More flexible formula-based conditions + +- Direct SQL-like syntax + +- Supports complex logic with AND/OR/NOT + +## Best Practices + +1. **Always Define SELECT Policy**: Control what users can view + +2. **Define INSERT/UPDATE CHECK Policies**: Prevent data leakage + +3. **Use Role-Based Policies**: Apply different rules to different roles + +4. **Test Thoroughly**: RLS can have complex interactions + +5. **Monitor Performance**: Complex RLS policies can impact query performance + +## Security Considerations + +1. **Defense in Depth**: RLS is one layer; use with object permissions + +2. **Default Deny**: If no policy matches, access is denied + +3. **Policy Precedence**: More permissive policy wins (OR logic) + +4. **Context Variables**: Ensure current_user context is always set + +@see https://www.postgresql.org/docs/current/ddl-rowsecurity.html + +@see https://help.salesforce.com/s/articleView?id=sf.security_sharing_rules.htm + + +**Source:** `packages/spec/src/security/rls.zod.ts` + + +## TypeScript Usage + +```typescript +import { RLSConfig, RLSEvaluationResult, RLSOperation, RLSUserContext, RowLevelSecurityPolicy } from '@objectstack/spec/security'; +import type { RLSConfig, RLSEvaluationResult, RLSOperation, RLSUserContext, RowLevelSecurityPolicy } from '@objectstack/spec/security'; + +// Validate data +const result = RLSConfig.parse(data); +``` + +--- + +## RLSConfig + + +--- + +## RLSEvaluationResult + + +--- + +## RLSOperation + + +--- + +## RLSUserContext + + +--- + +## RowLevelSecurityPolicy + + +--- + diff --git a/content/docs/references/security/sharing.mdx b/content/docs/references/security/sharing.mdx new file mode 100644 index 000000000..380cdac69 --- /dev/null +++ b/content/docs/references/security/sharing.mdx @@ -0,0 +1,60 @@ +--- +title: Sharing +description: Sharing protocol schemas +--- + +Organization-Wide Defaults (OWD) + +The baseline security posture for an object. + + +**Source:** `packages/spec/src/security/sharing.zod.ts` + + +## TypeScript Usage + +```typescript +import { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security'; +import type { CriteriaSharingRule, OWDModel, OwnerSharingRule, ShareRecipientType, SharingLevel, SharingRule, SharingRuleType } from '@objectstack/spec/security'; + +// Validate data +const result = CriteriaSharingRule.parse(data); +``` + +--- + +## CriteriaSharingRule + + +--- + +## OWDModel + + +--- + +## OwnerSharingRule + + +--- + +## ShareRecipientType + + +--- + +## SharingLevel + + +--- + +## SharingRule + + +--- + +## SharingRuleType + + +--- + diff --git a/content/docs/references/security/territory.mdx b/content/docs/references/security/territory.mdx new file mode 100644 index 000000000..5163c48d7 --- /dev/null +++ b/content/docs/references/security/territory.mdx @@ -0,0 +1,58 @@ +--- +title: Territory +description: Territory protocol schemas +--- + +Territory Management Protocol + +Defines a matrix reporting structure that exists parallel to the Role Hierarchy. + +USE CASE: + +- Enterprise Sales Teams (Geo-based: "EMEA", "APAC") + +- Industry Verticals (Industry-based: "Healthcare", "Financial") + +- Strategic Accounts (Account-based: "Strategic Accounts") + +DIFFERENCE FROM ROLE: + +- Role: Hierarchy of PEOPLE (Who reports to whom). Stable. HR-driven. + +- Territory: Hierarchy of ACCOUNTS/REVENUE (Who owns which market). Flexible. Sales-driven. + +- One User can be assigned to MANY Territories (Matrix). + +- One User has only ONE Role (Tree). + + +**Source:** `packages/spec/src/security/territory.zod.ts` + + +## TypeScript Usage + +```typescript +import { Territory, TerritoryModel, TerritoryType } from '@objectstack/spec/security'; +import type { Territory, TerritoryModel, TerritoryType } from '@objectstack/spec/security'; + +// Validate data +const result = Territory.parse(data); +``` + +--- + +## Territory + + +--- + +## TerritoryModel + + +--- + +## TerritoryType + + +--- + diff --git a/content/docs/references/shared/http.mdx b/content/docs/references/shared/http.mdx new file mode 100644 index 000000000..353685674 --- /dev/null +++ b/content/docs/references/shared/http.mdx @@ -0,0 +1,42 @@ +--- +title: Http +description: Http protocol schemas +--- + +Shared HTTP Schemas + +Common HTTP-related schemas used across API and System protocols. + +These schemas ensure consistency across different parts of the stack. + + +**Source:** `packages/spec/src/shared/http.zod.ts` + + +## TypeScript Usage + +```typescript +import { CorsConfig, RateLimitConfig, StaticMount } from '@objectstack/spec/shared'; +import type { CorsConfig, RateLimitConfig, StaticMount } from '@objectstack/spec/shared'; + +// Validate data +const result = CorsConfig.parse(data); +``` + +--- + +## CorsConfig + + +--- + +## RateLimitConfig + + +--- + +## StaticMount + + +--- + diff --git a/content/docs/references/shared/identifiers.mdx b/content/docs/references/shared/identifiers.mdx new file mode 100644 index 000000000..2a555ce54 --- /dev/null +++ b/content/docs/references/shared/identifiers.mdx @@ -0,0 +1,108 @@ +--- +title: Identifiers +description: Identifiers protocol schemas +--- + +System Identifier Schema + +Universal naming convention for all machine identifiers (API Names) in ObjectStack. + +Enforces lowercase with underscores or dots to ensure: + +- Cross-platform compatibility (case-insensitive filesystems) + +- URL-friendliness (no encoding needed) + +- Database consistency (no collation issues) + +- Security (no case-sensitivity bugs in permission checks) + +**Applies to all metadata that acts as a machine identifier:** + +- Object names (tables/collections) + +- Field names + +- Role names + +- Permission set names + +- Action/trigger names + +- Event keys + +- App IDs + +- Menu/page IDs + +- Select option values + +- Workflow names + +- Webhook names + +**Naming Convention Summary:** + +| Type | Pattern | Example | + +|------|---------|---------| + +| Machine ID | snake_case | `crm_account`, `btn_submit`, `role_admin` | + +| Event keys | dot.notation | `user.login`, `order.created` | + +| Labels | Any case | `Client Account`, `Submit Form` | + +@example Valid identifiers + +- 'account' + +- 'crm_account' + +- 'user_profile' + +- 'order.created' (for events) + +- 'api_v2_endpoint' + +@example Invalid identifiers (will be rejected) + +- 'Account' (uppercase) + +- 'CrmAccount' (camelCase) + +- 'crm-account' (kebab-case - use underscore instead) + +- 'user profile' (spaces) + + +**Source:** `packages/spec/src/shared/identifiers.zod.ts` + + +## TypeScript Usage + +```typescript +import { EventName, SnakeCaseIdentifier, SystemIdentifier } from '@objectstack/spec/shared'; +import type { EventName, SnakeCaseIdentifier, SystemIdentifier } from '@objectstack/spec/shared'; + +// Validate data +const result = EventName.parse(data); +``` + +--- + +## EventName + + +--- + +## SnakeCaseIdentifier + + +--- + +## SystemIdentifier + + +--- + diff --git a/content/docs/references/shared/mapping.mdx b/content/docs/references/shared/mapping.mdx new file mode 100644 index 000000000..0101df6da --- /dev/null +++ b/content/docs/references/shared/mapping.mdx @@ -0,0 +1,81 @@ +--- +title: Mapping +description: Mapping protocol schemas +--- + +Base Field Mapping Protocol + +Shared by: ETL, Sync, Connector, External Lookup + +This module provides the canonical field mapping schema used across + +ObjectStack for data transformation and synchronization. + +**Use Cases:** + +- ETL pipelines (data/mapping.zod.ts) + +- Data synchronization (automation/sync.zod.ts) + +- Integration connectors (integration/connector.zod.ts) + +- External lookups (data/external-lookup.zod.ts) + +@example Basic field mapping + +```typescript + +const mapping: FieldMapping = { + +source: 'external_user_id', + +target: 'user_id', + +}; + +``` + +@example With transformation + +```typescript + +const mapping: FieldMapping = { + +source: 'user_name', + +target: 'name', + +transform: { type: 'cast', targetType: 'string' }, + +defaultValue: 'Unknown' + +}; + +``` + + +**Source:** `packages/spec/src/shared/mapping.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldMapping, TransformType } from '@objectstack/spec/shared'; +import type { FieldMapping, TransformType } from '@objectstack/spec/shared'; + +// Validate data +const result = FieldMapping.parse(data); +``` + +--- + +## FieldMapping + + +--- + +## TransformType + + +--- + diff --git a/content/docs/references/shared/meta.json b/content/docs/references/shared/meta.json new file mode 100644 index 000000000..faae950f2 --- /dev/null +++ b/content/docs/references/shared/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Shared Protocol", + "pages": [ + "enums", + "http", + "identifiers", + "mapping", + "metadata-persistence", + "metadata-types", + "view" + ] +} \ No newline at end of file diff --git a/content/docs/references/shared/view.mdx b/content/docs/references/shared/view.mdx new file mode 100644 index 000000000..0ca5eb64e --- /dev/null +++ b/content/docs/references/shared/view.mdx @@ -0,0 +1,26 @@ +--- +title: View +description: View protocol schemas +--- + + +**Source:** `packages/spec/src/shared/view.zod.ts` + + +## TypeScript Usage + +```typescript +import { HttpMethod } from '@objectstack/spec/shared'; +import type { HttpMethod } from '@objectstack/spec/shared'; + +// Validate data +const result = HttpMethod.parse(data); +``` + +--- + +## HttpMethod + + +--- + diff --git a/content/docs/references/system/audit.mdx b/content/docs/references/system/audit.mdx new file mode 100644 index 000000000..c261f0eed --- /dev/null +++ b/content/docs/references/system/audit.mdx @@ -0,0 +1,94 @@ +--- +title: Audit +description: Audit protocol schemas +--- + +Audit Log Architecture + +Comprehensive audit logging system for compliance and security. + +Supports SOX, HIPAA, GDPR, and other regulatory requirements. + +Features: + +- Records all CRUD operations on data + +- Tracks authentication events (login, logout, password reset) + +- Monitors authorization changes (permissions, roles) + +- Configurable retention policies (180-day GDPR requirement) + +- Suspicious activity detection and alerting + + +**Source:** `packages/spec/src/system/audit.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; +import type { AuditConfig, AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig, SuspiciousActivityRule } from '@objectstack/spec/system'; + +// Validate data +const result = AuditConfig.parse(data); +``` + +--- + +## AuditConfig + + +--- + +## AuditEvent + + +--- + +## AuditEventActor + + +--- + +## AuditEventChange + + +--- + +## AuditEventFilter + + +--- + +## AuditEventSeverity + + +--- + +## AuditEventTarget + + +--- + +## AuditEventType + + +--- + +## AuditRetentionPolicy + + +--- + +## AuditStorageConfig + + +--- + +## SuspiciousActivityRule + + +--- + diff --git a/content/docs/references/system/auth-config.mdx b/content/docs/references/system/auth-config.mdx new file mode 100644 index 000000000..fe52a3c17 --- /dev/null +++ b/content/docs/references/system/auth-config.mdx @@ -0,0 +1,42 @@ +--- +title: Auth Config +description: Auth Config protocol schemas +--- + +Better-Auth Configuration Protocol + +Defines the configuration required to initialize the Better-Auth kernel. + +Used in server-side configuration injection. + + +**Source:** `packages/spec/src/system/auth-config.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuthConfig, AuthPluginConfig, AuthProviderConfig } from '@objectstack/spec/system'; +import type { AuthConfig, AuthPluginConfig, AuthProviderConfig } from '@objectstack/spec/system'; + +// Validate data +const result = AuthConfig.parse(data); +``` + +--- + +## AuthConfig + + +--- + +## AuthPluginConfig + + +--- + +## AuthProviderConfig + + +--- + diff --git a/content/docs/references/system/cache.mdx b/content/docs/references/system/cache.mdx new file mode 100644 index 000000000..c3666b7c3 --- /dev/null +++ b/content/docs/references/system/cache.mdx @@ -0,0 +1,75 @@ +--- +title: Cache +description: Cache protocol schemas +--- + +Application-Level Cache Protocol + +Multi-tier caching strategy for application data. + +Supports Memory, Redis, Memcached, and CDN. + +## Caching in ObjectStack + +**Application Cache (`system/cache.zod.ts`) - This File** + +- **Purpose**: Cache computed data, query results, aggregations + +- **Technologies**: Redis, Memcached, in-memory LRU + +- **Configuration**: TTL, eviction policies, cache warming + +- **Use case**: Cache expensive database queries, computed values + +- **Scope**: Application layer, server-side data storage + +**HTTP Cache (`api/http-cache.zod.ts`)** + +- **Purpose**: Cache API responses at HTTP protocol level + +- **Technologies**: HTTP headers (ETag, Last-Modified, Cache-Control), CDN + +- **Configuration**: Cache-Control headers, validation tokens + +- **Use case**: Reduce API response time for repeated metadata requests + +- **Scope**: HTTP layer, client-server communication + +@see ../../api/http-cache.zod.ts for HTTP-level caching + + +**Source:** `packages/spec/src/system/cache.zod.ts` + + +## TypeScript Usage + +```typescript +import { CacheConfig, CacheInvalidation, CacheStrategy, CacheTier } from '@objectstack/spec/system'; +import type { CacheConfig, CacheInvalidation, CacheStrategy, CacheTier } from '@objectstack/spec/system'; + +// Validate data +const result = CacheConfig.parse(data); +``` + +--- + +## CacheConfig + + +--- + +## CacheInvalidation + + +--- + +## CacheStrategy + + +--- + +## CacheTier + + +--- + diff --git a/content/docs/references/system/change-management.mdx b/content/docs/references/system/change-management.mdx new file mode 100644 index 000000000..b9679a1d0 --- /dev/null +++ b/content/docs/references/system/change-management.mdx @@ -0,0 +1,57 @@ +--- +title: Change Management +description: Change Management protocol schemas +--- + +Change Type Enum + +Classification of change requests based on risk and approval requirements. + +Follows ITIL change management best practices. + + +**Source:** `packages/spec/src/system/change-management.zod.ts` + + +## TypeScript Usage + +```typescript +import { ChangeImpact, ChangePriority, ChangeRequest, ChangeStatus, ChangeType, RollbackPlan } from '@objectstack/spec/system'; +import type { ChangeImpact, ChangePriority, ChangeRequest, ChangeStatus, ChangeType, RollbackPlan } from '@objectstack/spec/system'; + +// Validate data +const result = ChangeImpact.parse(data); +``` + +--- + +## ChangeImpact + + +--- + +## ChangePriority + + +--- + +## ChangeRequest + + +--- + +## ChangeStatus + + +--- + +## ChangeType + + +--- + +## RollbackPlan + + +--- + diff --git a/content/docs/references/system/collaboration.mdx b/content/docs/references/system/collaboration.mdx new file mode 100644 index 000000000..f4372971d --- /dev/null +++ b/content/docs/references/system/collaboration.mdx @@ -0,0 +1,176 @@ +--- +title: Collaboration +description: Collaboration protocol schemas +--- + +Real-Time Collaboration Protocol + +Defines schemas for real-time collaborative editing in ObjectStack. + +Supports Operational Transformation (OT), CRDT (Conflict-free Replicated Data Types), + +cursor sharing, and awareness state for collaborative applications. + +Industry alignment: Google Docs, Figma, VSCode Live Share, Yjs + + +**Source:** `packages/spec/src/system/collaboration.zod.ts` + + +## TypeScript Usage + +```typescript +import { AwarenessEvent, AwarenessSession, AwarenessUpdate, AwarenessUserState, CRDTMergeResult, CRDTState, CRDTType, CollaborationMode, CollaborationSession, CollaborationSessionConfig, CollaborativeCursor, CounterOperation, CursorColorPreset, CursorSelection, CursorStyle, CursorUpdate, GCounter, LWWRegister, ORSet, ORSetElement, OTComponent, OTOperation, OTOperationType, OTTransformResult, PNCounter, TextCRDTOperation, TextCRDTState, UserActivityStatus, VectorClock } from '@objectstack/spec/system'; +import type { AwarenessEvent, AwarenessSession, AwarenessUpdate, AwarenessUserState, CRDTMergeResult, CRDTState, CRDTType, CollaborationMode, CollaborationSession, CollaborationSessionConfig, CollaborativeCursor, CounterOperation, CursorColorPreset, CursorSelection, CursorStyle, CursorUpdate, GCounter, LWWRegister, ORSet, ORSetElement, OTComponent, OTOperation, OTOperationType, OTTransformResult, PNCounter, TextCRDTOperation, TextCRDTState, UserActivityStatus, VectorClock } from '@objectstack/spec/system'; + +// Validate data +const result = AwarenessEvent.parse(data); +``` + +--- + +## AwarenessEvent + + +--- + +## AwarenessSession + + +--- + +## AwarenessUpdate + + +--- + +## AwarenessUserState + + +--- + +## CRDTMergeResult + + +--- + +## CRDTState + + +--- + +## CRDTType + + +--- + +## CollaborationMode + + +--- + +## CollaborationSession + + +--- + +## CollaborationSessionConfig + + +--- + +## CollaborativeCursor + + +--- + +## CounterOperation + + +--- + +## CursorColorPreset + + +--- + +## CursorSelection + + +--- + +## CursorStyle + + +--- + +## CursorUpdate + + +--- + +## GCounter + + +--- + +## LWWRegister + + +--- + +## ORSet + + +--- + +## ORSetElement + + +--- + +## OTComponent + + +--- + +## OTOperation + + +--- + +## OTOperationType + + +--- + +## OTTransformResult + + +--- + +## PNCounter + + +--- + +## TextCRDTOperation + + +--- + +## TextCRDTState + + +--- + +## UserActivityStatus + + +--- + +## VectorClock + + +--- + diff --git a/content/docs/references/system/compliance.mdx b/content/docs/references/system/compliance.mdx new file mode 100644 index 000000000..de96d4274 --- /dev/null +++ b/content/docs/references/system/compliance.mdx @@ -0,0 +1,48 @@ +--- +title: Compliance +description: Compliance protocol schemas +--- + +Compliance protocol for GDPR, CCPA, HIPAA, SOX, PCI-DSS + + +**Source:** `packages/spec/src/system/compliance.zod.ts` + + +## TypeScript Usage + +```typescript +import { AuditLogConfig, ComplianceConfig, GDPRConfig, HIPAAConfig, PCIDSSConfig } from '@objectstack/spec/system'; +import type { AuditLogConfig, ComplianceConfig, GDPRConfig, HIPAAConfig, PCIDSSConfig } from '@objectstack/spec/system'; + +// Validate data +const result = AuditLogConfig.parse(data); +``` + +--- + +## AuditLogConfig + + +--- + +## ComplianceConfig + + +--- + +## GDPRConfig + + +--- + +## HIPAAConfig + + +--- + +## PCIDSSConfig + + +--- + diff --git a/content/docs/references/system/encryption.mdx b/content/docs/references/system/encryption.mdx new file mode 100644 index 000000000..6ee4c7827 --- /dev/null +++ b/content/docs/references/system/encryption.mdx @@ -0,0 +1,50 @@ +--- +title: Encryption +description: Encryption protocol schemas +--- + +Field-level encryption protocol + +GDPR/HIPAA/PCI-DSS compliant + + +**Source:** `packages/spec/src/system/encryption.zod.ts` + + +## TypeScript Usage + +```typescript +import { EncryptionAlgorithm, EncryptionConfig, FieldEncryption, KeyManagementProvider, KeyRotationPolicy } from '@objectstack/spec/system'; +import type { EncryptionAlgorithm, EncryptionConfig, FieldEncryption, KeyManagementProvider, KeyRotationPolicy } from '@objectstack/spec/system'; + +// Validate data +const result = EncryptionAlgorithm.parse(data); +``` + +--- + +## EncryptionAlgorithm + + +--- + +## EncryptionConfig + + +--- + +## FieldEncryption + + +--- + +## KeyManagementProvider + + +--- + +## KeyRotationPolicy + + +--- + diff --git a/content/docs/references/system/http-server.mdx b/content/docs/references/system/http-server.mdx new file mode 100644 index 000000000..692b75453 --- /dev/null +++ b/content/docs/references/system/http-server.mdx @@ -0,0 +1,75 @@ +--- +title: Http Server +description: Http Server protocol schemas +--- + +HTTP Server Protocol + +Defines the runtime HTTP server configuration and capabilities. + +Provides abstractions for HTTP server implementations (Express, Fastify, Hono, etc.) + +Architecture alignment: + +- Kubernetes: Service and Ingress resources + +- AWS: API Gateway configuration + +- Spring Boot: Application properties + + +**Source:** `packages/spec/src/system/http-server.zod.ts` + + +## TypeScript Usage + +```typescript +import { HttpServerConfig, MiddlewareConfig, MiddlewareType, RouteHandlerMetadata, ServerCapabilities, ServerEvent, ServerEventType, ServerStatus } from '@objectstack/spec/system'; +import type { HttpServerConfig, MiddlewareConfig, MiddlewareType, RouteHandlerMetadata, ServerCapabilities, ServerEvent, ServerEventType, ServerStatus } from '@objectstack/spec/system'; + +// Validate data +const result = HttpServerConfig.parse(data); +``` + +--- + +## HttpServerConfig + + +--- + +## MiddlewareConfig + + +--- + +## MiddlewareType + + +--- + +## RouteHandlerMetadata + + +--- + +## ServerCapabilities + + +--- + +## ServerEvent + + +--- + +## ServerEventType + + +--- + +## ServerStatus + + +--- + diff --git a/content/docs/references/system/job.mdx b/content/docs/references/system/job.mdx new file mode 100644 index 000000000..b44873eb6 --- /dev/null +++ b/content/docs/references/system/job.mdx @@ -0,0 +1,65 @@ +--- +title: Job +description: Job protocol schemas +--- + +Cron Schedule Schema + +Schedule jobs using cron expressions + + +**Source:** `packages/spec/src/system/job.zod.ts` + + +## TypeScript Usage + +```typescript +import { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; +import type { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system'; + +// Validate data +const result = CronSchedule.parse(data); +``` + +--- + +## CronSchedule + + +--- + +## IntervalSchedule + + +--- + +## Job + + +--- + +## JobExecution + + +--- + +## JobExecutionStatus + + +--- + +## OnceSchedule + + +--- + +## RetryPolicy + + +--- + +## Schedule + + +--- + diff --git a/content/docs/references/system/license.mdx b/content/docs/references/system/license.mdx new file mode 100644 index 000000000..1acf623f3 --- /dev/null +++ b/content/docs/references/system/license.mdx @@ -0,0 +1,43 @@ +--- +title: License +description: License protocol schemas +--- + +Metric Type Classification + + +**Source:** `packages/spec/src/system/license.zod.ts` + + +## TypeScript Usage + +```typescript +import { Feature, License, LicenseMetricType, Plan } from '@objectstack/spec/system'; +import type { Feature, License, LicenseMetricType, Plan } from '@objectstack/spec/system'; + +// Validate data +const result = Feature.parse(data); +``` + +--- + +## Feature + + +--- + +## License + + +--- + +## LicenseMetricType + + +--- + +## Plan + + +--- + diff --git a/content/docs/references/system/logging.mdx b/content/docs/references/system/logging.mdx new file mode 100644 index 000000000..2b1a62371 --- /dev/null +++ b/content/docs/references/system/logging.mdx @@ -0,0 +1,107 @@ +--- +title: Logging +description: Logging protocol schemas +--- + +Logging Protocol - Comprehensive Observability Logging + +Unified logging protocol that combines: + +- Basic kernel logging (LoggerConfig) + +- Enterprise-grade features (LoggingConfig) + +- Multiple log destinations (file, console, external services) + +- Structured logging with enrichment + +- Log aggregation and forwarding + +- Integration with external log management systems + + +**Source:** `packages/spec/src/system/logging.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConsoleDestinationConfig, ExtendedLogLevel, ExternalServiceDestinationConfig, FileDestinationConfig, HttpDestinationConfig, LogDestination, LogDestinationType, LogEnrichmentConfig, LogEntry, LogFormat, LogLevel, LoggerConfig, LoggingConfig, StructuredLogEntry } from '@objectstack/spec/system'; +import type { ConsoleDestinationConfig, ExtendedLogLevel, ExternalServiceDestinationConfig, FileDestinationConfig, HttpDestinationConfig, LogDestination, LogDestinationType, LogEnrichmentConfig, LogEntry, LogFormat, LogLevel, LoggerConfig, LoggingConfig, StructuredLogEntry } from '@objectstack/spec/system'; + +// Validate data +const result = ConsoleDestinationConfig.parse(data); +``` + +--- + +## ConsoleDestinationConfig + + +--- + +## ExtendedLogLevel + + +--- + +## ExternalServiceDestinationConfig + + +--- + +## FileDestinationConfig + + +--- + +## HttpDestinationConfig + + +--- + +## LogDestination + + +--- + +## LogDestinationType + + +--- + +## LogEnrichmentConfig + + +--- + +## LogEntry + + +--- + +## LogFormat + + +--- + +## LogLevel + + +--- + +## LoggerConfig + + +--- + +## LoggingConfig + + +--- + +## StructuredLogEntry + + +--- + diff --git a/content/docs/references/system/masking.mdx b/content/docs/references/system/masking.mdx new file mode 100644 index 000000000..2e2c04284 --- /dev/null +++ b/content/docs/references/system/masking.mdx @@ -0,0 +1,38 @@ +--- +title: Masking +description: Masking protocol schemas +--- + +Data masking protocol for PII protection + + +**Source:** `packages/spec/src/system/masking.zod.ts` + + +## TypeScript Usage + +```typescript +import { MaskingConfig, MaskingRule, MaskingStrategy } from '@objectstack/spec/system'; +import type { MaskingConfig, MaskingRule, MaskingStrategy } from '@objectstack/spec/system'; + +// Validate data +const result = MaskingConfig.parse(data); +``` + +--- + +## MaskingConfig + + +--- + +## MaskingRule + + +--- + +## MaskingStrategy + + +--- + diff --git a/content/docs/references/system/message-queue.mdx b/content/docs/references/system/message-queue.mdx new file mode 100644 index 000000000..8af831046 --- /dev/null +++ b/content/docs/references/system/message-queue.mdx @@ -0,0 +1,50 @@ +--- +title: Message Queue +description: Message Queue protocol schemas +--- + +Message queue protocol for async communication + +Supports Kafka, RabbitMQ, AWS SQS, Redis Pub/Sub + + +**Source:** `packages/spec/src/system/message-queue.zod.ts` + + +## TypeScript Usage + +```typescript +import { ConsumerConfig, DeadLetterQueue, MessageQueueConfig, MessageQueueProvider, TopicConfig } from '@objectstack/spec/system'; +import type { ConsumerConfig, DeadLetterQueue, MessageQueueConfig, MessageQueueProvider, TopicConfig } from '@objectstack/spec/system'; + +// Validate data +const result = ConsumerConfig.parse(data); +``` + +--- + +## ConsumerConfig + + +--- + +## DeadLetterQueue + + +--- + +## MessageQueueConfig + + +--- + +## MessageQueueProvider + + +--- + +## TopicConfig + + +--- + diff --git a/content/docs/references/system/meta.json b/content/docs/references/system/meta.json new file mode 100644 index 000000000..4dbfa10ed --- /dev/null +++ b/content/docs/references/system/meta.json @@ -0,0 +1,30 @@ +{ + "title": "System Protocol", + "pages": [ + "audit", + "auth-config", + "cache", + "change-management", + "collaboration", + "compliance", + "core-services", + "encryption", + "http-server", + "job", + "license", + "logging", + "masking", + "message-queue", + "metadata-persistence", + "metrics", + "migration", + "notification", + "object-storage", + "registry-config", + "search-engine", + "tenant", + "tracing", + "translation", + "worker" + ] +} \ No newline at end of file diff --git a/content/docs/references/system/metadata-persistence.mdx b/content/docs/references/system/metadata-persistence.mdx new file mode 100644 index 000000000..ab00eaf0b --- /dev/null +++ b/content/docs/references/system/metadata-persistence.mdx @@ -0,0 +1,100 @@ +--- +title: Metadata Persistence +description: Metadata Persistence protocol schemas +--- + +Metadata Scope Enum + +Defines the lifecycle and mutability of a metadata item. + + +**Source:** `packages/spec/src/system/metadata-persistence.zod.ts` + + +## TypeScript Usage + +```typescript +import { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataState, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system'; +import type { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataState, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system'; + +// Validate data +const result = MetadataCollectionInfo.parse(data); +``` + +--- + +## MetadataCollectionInfo + + +--- + +## MetadataExportOptions + + +--- + +## MetadataFormat + + +--- + +## MetadataImportOptions + + +--- + +## MetadataLoadOptions + + +--- + +## MetadataLoadResult + + +--- + +## MetadataLoaderContract + + +--- + +## MetadataManagerConfig + + +--- + +## MetadataRecord + + +--- + +## MetadataSaveOptions + + +--- + +## MetadataSaveResult + + +--- + +## MetadataScope + + +--- + +## MetadataState + + +--- + +## MetadataStats + + +--- + +## MetadataWatchEvent + + +--- + diff --git a/content/docs/references/system/metrics.mdx b/content/docs/references/system/metrics.mdx new file mode 100644 index 000000000..8b8f2b5aa --- /dev/null +++ b/content/docs/references/system/metrics.mdx @@ -0,0 +1,105 @@ +--- +title: Metrics +description: Metrics protocol schemas +--- + +Metrics Protocol - Performance and Operational Metrics + +Comprehensive metrics collection and monitoring: + +- Counter, Gauge, Histogram, Summary metric types + +- Time-series data collection + +- SLI/SLO definitions + +- Metric aggregation and export + +- Integration with monitoring systems (Prometheus, etc.) + + +**Source:** `packages/spec/src/system/metrics.zod.ts` + + +## TypeScript Usage + +```typescript +import { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, MetricsConfig, ServiceLevelIndicator, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system'; +import type { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, MetricsConfig, ServiceLevelIndicator, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system'; + +// Validate data +const result = HistogramBucketConfig.parse(data); +``` + +--- + +## HistogramBucketConfig + + +--- + +## MetricAggregationConfig + + +--- + +## MetricAggregationType + + +--- + +## MetricDataPoint + + +--- + +## MetricDefinition + + +--- + +## MetricExportConfig + + +--- + +## MetricLabels + + +--- + +## MetricType + + +--- + +## MetricUnit + + +--- + +## MetricsConfig + + +--- + +## ServiceLevelIndicator + + +--- + +## ServiceLevelObjective + + +--- + +## TimeSeries + + +--- + +## TimeSeriesDataPoint + + +--- + diff --git a/content/docs/references/system/migration.mdx b/content/docs/references/system/migration.mdx new file mode 100644 index 000000000..437a2d7da --- /dev/null +++ b/content/docs/references/system/migration.mdx @@ -0,0 +1,71 @@ +--- +title: Migration +description: Migration protocol schemas +--- + + +**Source:** `packages/spec/src/system/migration.zod.ts` + + +## TypeScript Usage + +```typescript +import { AddFieldOperation, ChangeSet, CreateObjectOperation, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; +import type { AddFieldOperation, ChangeSet, CreateObjectOperation, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system'; + +// Validate data +const result = AddFieldOperation.parse(data); +``` + +--- + +## AddFieldOperation + + +--- + +## ChangeSet + + +--- + +## CreateObjectOperation + + +--- + +## DeleteObjectOperation + + +--- + +## ExecuteSqlOperation + + +--- + +## MigrationDependency + + +--- + +## MigrationOperation + + +--- + +## ModifyFieldOperation + + +--- + +## RemoveFieldOperation + + +--- + +## RenameObjectOperation + + +--- + diff --git a/content/docs/references/system/notification.mdx b/content/docs/references/system/notification.mdx new file mode 100644 index 000000000..038597dc8 --- /dev/null +++ b/content/docs/references/system/notification.mdx @@ -0,0 +1,89 @@ +--- +title: Notification +description: Notification protocol schemas +--- + +Email Template Schema + +Defines the structure and content of email notifications. + +Supports variables for personalization and file attachments. + +@example + +```json + +{ + +"id": "welcome-email", + +"subject": "Welcome to {{company_name}}", + +"body": "

Welcome {{user_name}}!

", + +"bodyType": "html", + +"variables": ["company_name", "user_name"], + +"attachments": [ + +{ + +"name": "guide.pdf", + +"url": "https://example.com/guide.pdf" + +} + +] + +} + +``` + + +**Source:** `packages/spec/src/system/notification.zod.ts` + + +## TypeScript Usage + +```typescript +import { EmailTemplate, InAppNotification, NotificationChannel, NotificationConfig, PushNotification, SMSTemplate } from '@objectstack/spec/system'; +import type { EmailTemplate, InAppNotification, NotificationChannel, NotificationConfig, PushNotification, SMSTemplate } from '@objectstack/spec/system'; + +// Validate data +const result = EmailTemplate.parse(data); +``` + +--- + +## EmailTemplate + + +--- + +## InAppNotification + + +--- + +## NotificationChannel + + +--- + +## NotificationConfig + + +--- + +## PushNotification + + +--- + +## SMSTemplate + + +--- + diff --git a/content/docs/references/system/object-storage.mdx b/content/docs/references/system/object-storage.mdx new file mode 100644 index 000000000..463326d17 --- /dev/null +++ b/content/docs/references/system/object-storage.mdx @@ -0,0 +1,116 @@ +--- +title: Object Storage +description: Object Storage protocol schemas +--- + +Object Storage Protocol + +Unified storage protocol that combines: + +- Object storage systems (S3, Azure Blob, GCS, MinIO) + +- Scoped storage configuration (temp, cache, data, logs, config, public) + +- Multi-cloud storage providers + +- Bucket/container configuration + +- Access control and permissions + +- Lifecycle policies for data retention + +- Presigned URLs for secure direct access + +- Multipart uploads for large files + + +**Source:** `packages/spec/src/system/object-storage.zod.ts` + + +## TypeScript Usage + +```typescript +import { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system'; +import type { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system'; + +// Validate data +const result = AccessControlConfig.parse(data); +``` + +--- + +## AccessControlConfig + + +--- + +## BucketConfig + + +--- + +## FileMetadata + + +--- + +## LifecycleAction + + +--- + +## LifecyclePolicyConfig + + +--- + +## LifecyclePolicyRule + + +--- + +## MultipartUploadConfig + + +--- + +## ObjectMetadata + + +--- + +## ObjectStorageConfig + + +--- + +## PresignedUrlConfig + + +--- + +## StorageAcl + + +--- + +## StorageClass + + +--- + +## StorageConnection + + +--- + +## StorageProvider + + +--- + +## StorageScope + + +--- + diff --git a/content/docs/references/system/registry-config.mdx b/content/docs/references/system/registry-config.mdx new file mode 100644 index 000000000..6b8ed3223 --- /dev/null +++ b/content/docs/references/system/registry-config.mdx @@ -0,0 +1,42 @@ +--- +title: Registry Config +description: Registry Config protocol schemas +--- + +# Registry Configuration Protocol + +Defines the configuration for the ObjectStack Registry Service. + +Includes federation, synchronization, and storage settings. + + +**Source:** `packages/spec/src/system/registry-config.zod.ts` + + +## TypeScript Usage + +```typescript +import { RegistryConfig, RegistrySyncPolicy, RegistryUpstream } from '@objectstack/spec/system'; +import type { RegistryConfig, RegistrySyncPolicy, RegistryUpstream } from '@objectstack/spec/system'; + +// Validate data +const result = RegistryConfig.parse(data); +``` + +--- + +## RegistryConfig + + +--- + +## RegistrySyncPolicy + + +--- + +## RegistryUpstream + + +--- + diff --git a/content/docs/references/system/search-engine.mdx b/content/docs/references/system/search-engine.mdx new file mode 100644 index 000000000..d4e98e930 --- /dev/null +++ b/content/docs/references/system/search-engine.mdx @@ -0,0 +1,50 @@ +--- +title: Search Engine +description: Search Engine protocol schemas +--- + +Full-text search protocol + +Supports Elasticsearch, Algolia, Meilisearch, Typesense + + +**Source:** `packages/spec/src/system/search-engine.zod.ts` + + +## TypeScript Usage + +```typescript +import { AnalyzerConfig, FacetConfig, SearchConfig, SearchIndexConfig, SearchProvider } from '@objectstack/spec/system'; +import type { AnalyzerConfig, FacetConfig, SearchConfig, SearchIndexConfig, SearchProvider } from '@objectstack/spec/system'; + +// Validate data +const result = AnalyzerConfig.parse(data); +``` + +--- + +## AnalyzerConfig + + +--- + +## FacetConfig + + +--- + +## SearchConfig + + +--- + +## SearchIndexConfig + + +--- + +## SearchProvider + + +--- + diff --git a/content/docs/references/system/tenant.mdx b/content/docs/references/system/tenant.mdx new file mode 100644 index 000000000..89526146e --- /dev/null +++ b/content/docs/references/system/tenant.mdx @@ -0,0 +1,77 @@ +--- +title: Tenant +description: Tenant protocol schemas +--- + +Tenant Schema (Multi-Tenant Architecture) + +Defines the tenant/tenancy model for ObjectStack SaaS deployments. + +Supports different levels of data isolation to meet varying security, + +performance, and compliance requirements. + +Isolation Levels: + +- shared_schema: All tenants share the same database and schema (row-level isolation) + +- isolated_schema: Tenants have separate schemas within a shared database + +- isolated_db: Each tenant has a completely separate database + + +**Source:** `packages/spec/src/system/tenant.zod.ts` + + +## TypeScript Usage + +```typescript +import { DatabaseLevelIsolationStrategy, LevelIsolationStrategySchema, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/system'; +import type { DatabaseLevelIsolationStrategy, LevelIsolationStrategy, RowLevelIsolationStrategy, Tenant, TenantIsolationConfig, TenantIsolationLevel, TenantQuota, TenantSecurityPolicy } from '@objectstack/spec/system'; + +// Validate data +const result = DatabaseLevelIsolationStrategy.parse(data); +``` + +--- + +## DatabaseLevelIsolationStrategy + + +--- + +## LevelIsolationStrategySchema + + +--- + +## RowLevelIsolationStrategy + + +--- + +## Tenant + + +--- + +## TenantIsolationConfig + + +--- + +## TenantIsolationLevel + + +--- + +## TenantQuota + + +--- + +## TenantSecurityPolicy + + +--- + diff --git a/content/docs/references/system/tracing.mdx b/content/docs/references/system/tracing.mdx new file mode 100644 index 000000000..d12aeabfe --- /dev/null +++ b/content/docs/references/system/tracing.mdx @@ -0,0 +1,125 @@ +--- +title: Tracing +description: Tracing protocol schemas +--- + +Tracing Protocol - Distributed Tracing & Observability + +Comprehensive distributed tracing based on OpenTelemetry standards: + +- Trace context propagation + +- Span creation and management + +- Sampling strategies + +- Integration with tracing backends (Jaeger, Zipkin, etc.) + +- W3C Trace Context standard compliance + + +**Source:** `packages/spec/src/system/tracing.zod.ts` + + +## TypeScript Usage + +```typescript +import { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system'; +import type { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system'; + +// Validate data +const result = OpenTelemetryCompatibility.parse(data); +``` + +--- + +## OpenTelemetryCompatibility + + +--- + +## OtelExporterType + + +--- + +## SamplingDecision + + +--- + +## SamplingStrategyType + + +--- + +## Span + + +--- + +## SpanAttributeValue + + +--- + +## SpanAttributes + + +--- + +## SpanEvent + + +--- + +## SpanKind + + +--- + +## SpanLink + + +--- + +## SpanStatus + + +--- + +## TraceContext + + +--- + +## TraceContextPropagation + + +--- + +## TraceFlags + + +--- + +## TracePropagationFormat + + +--- + +## TraceSamplingConfig + + +--- + +## TraceState + + +--- + +## TracingConfig + + +--- + diff --git a/content/docs/references/system/translation.mdx b/content/docs/references/system/translation.mdx new file mode 100644 index 000000000..b033761ec --- /dev/null +++ b/content/docs/references/system/translation.mdx @@ -0,0 +1,54 @@ +--- +title: Translation +description: Translation protocol schemas +--- + +Translation Schema + +Supports i18n for labels, messages, and options. + +Example structure: + +```json + +{ + +"en": { "objects": { "account": { "label": "Account" } } }, + +"zh-CN": { "objects": { "account": { "label": "客户" } } } + +} + +``` + + +**Source:** `packages/spec/src/system/translation.zod.ts` + + +## TypeScript Usage + +```typescript +import { Locale, TranslationBundle, TranslationData } from '@objectstack/spec/system'; +import type { Locale, TranslationBundle, TranslationData } from '@objectstack/spec/system'; + +// Validate data +const result = Locale.parse(data); +``` + +--- + +## Locale + + +--- + +## TranslationBundle + + +--- + +## TranslationData + + +--- + diff --git a/content/docs/references/system/worker.mdx b/content/docs/references/system/worker.mdx new file mode 100644 index 000000000..e9a2c3112 --- /dev/null +++ b/content/docs/references/system/worker.mdx @@ -0,0 +1,117 @@ +--- +title: Worker +description: Worker protocol schemas +--- + +Worker System Protocol + +Background task processing system with queues, priorities, and retry logic. + +Provides a robust foundation for async task execution similar to: + +- Sidekiq (Ruby) + +- Celery (Python) + +- Bull/BullMQ (Node.js) + +- AWS SQS/Lambda + +Features: + +- Task queues with priorities + +- Task scheduling and retry logic + +- Batch processing + +- Dead letter queues + +- Task monitoring and logging + +@example Basic task + +```typescript + +const task: Task = { + +id: 'task-123', + +type: 'send_email', + +payload: { to: 'user@example.com', subject: 'Welcome' }, + +queue: 'notifications', + +priority: 5 + +}; + +``` + + +**Source:** `packages/spec/src/system/worker.zod.ts` + + +## TypeScript Usage + +```typescript +import { BatchProgress, BatchTask, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerConfig, WorkerStats } from '@objectstack/spec/system'; +import type { BatchProgress, BatchTask, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerConfig, WorkerStats } from '@objectstack/spec/system'; + +// Validate data +const result = BatchProgress.parse(data); +``` + +--- + +## BatchProgress + + +--- + +## BatchTask + + +--- + +## QueueConfig + + +--- + +## Task + + +--- + +## TaskExecutionResult + + +--- + +## TaskPriority + + +--- + +## TaskRetryPolicy + + +--- + +## TaskStatus + + +--- + +## WorkerConfig + + +--- + +## WorkerStats + + +--- + diff --git a/content/docs/references/ui/action.mdx b/content/docs/references/ui/action.mdx new file mode 100644 index 000000000..f677b2b74 --- /dev/null +++ b/content/docs/references/ui/action.mdx @@ -0,0 +1,35 @@ +--- +title: Action +description: Action protocol schemas +--- + +Action Parameter Schema + +Defines inputs required before executing an action. + + +**Source:** `packages/spec/src/ui/action.zod.ts` + + +## TypeScript Usage + +```typescript +import { Action, ActionParam } from '@objectstack/spec/ui'; +import type { Action, ActionParam } from '@objectstack/spec/ui'; + +// Validate data +const result = Action.parse(data); +``` + +--- + +## Action + + +--- + +## ActionParam + + +--- + diff --git a/content/docs/references/ui/app.mdx b/content/docs/references/ui/app.mdx new file mode 100644 index 000000000..0ad611cde --- /dev/null +++ b/content/docs/references/ui/app.mdx @@ -0,0 +1,83 @@ +--- +title: App +description: App protocol schemas +--- + +Base Navigation Item Schema + +Shared properties for all navigation types. + +**NAMING CONVENTION:** + +Navigation item IDs are used in URLs and configuration and must be lowercase snake_case. + +@example Good IDs + +- 'menu_accounts' + +- 'page_dashboard' + +- 'nav_settings' + +@example Bad IDs (will be rejected) + +- 'MenuAccounts' (PascalCase) + +- 'Page Dashboard' (spaces) + + +**Source:** `packages/spec/src/ui/app.zod.ts` + + +## TypeScript Usage + +```typescript +import { App, AppBranding, DashboardNavItem, GroupNavItem, NavigationItem, ObjectNavItem, PageNavItem, UrlNavItem } from '@objectstack/spec/ui'; +import type { App, AppBranding, DashboardNavItem, GroupNavItem, NavigationItem, ObjectNavItem, PageNavItem, UrlNavItem } from '@objectstack/spec/ui'; + +// Validate data +const result = App.parse(data); +``` + +--- + +## App + + +--- + +## AppBranding + + +--- + +## DashboardNavItem + + +--- + +## GroupNavItem + + +--- + +## NavigationItem + + +--- + +## ObjectNavItem + + +--- + +## PageNavItem + + +--- + +## UrlNavItem + + +--- + diff --git a/content/docs/references/ui/chart.mdx b/content/docs/references/ui/chart.mdx new file mode 100644 index 000000000..e04f2b071 --- /dev/null +++ b/content/docs/references/ui/chart.mdx @@ -0,0 +1,57 @@ +--- +title: Chart +description: Chart protocol schemas +--- + +Unified Chart Type Taxonomy + +Shared by Dashboard and Report widgets. + +Provides a comprehensive set of chart types for data visualization. + + +**Source:** `packages/spec/src/ui/chart.zod.ts` + + +## TypeScript Usage + +```typescript +import { ChartAnnotation, ChartAxis, ChartConfig, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui'; +import type { ChartAnnotation, ChartAxis, ChartConfig, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui'; + +// Validate data +const result = ChartAnnotation.parse(data); +``` + +--- + +## ChartAnnotation + + +--- + +## ChartAxis + + +--- + +## ChartConfig + + +--- + +## ChartInteraction + + +--- + +## ChartSeries + + +--- + +## ChartType + + +--- + diff --git a/content/docs/references/ui/component.mdx b/content/docs/references/ui/component.mdx new file mode 100644 index 000000000..28f73b6c5 --- /dev/null +++ b/content/docs/references/ui/component.mdx @@ -0,0 +1,53 @@ +--- +title: Component +description: Component protocol schemas +--- + +Empty Properties Schema + + +**Source:** `packages/spec/src/ui/component.zod.ts` + + +## TypeScript Usage + +```typescript +import { PageCardProps, PageHeaderProps, PageTabsProps, RecordDetailsProps, RecordHighlightsProps, RecordRelatedListProps } from '@objectstack/spec/ui'; +import type { PageCardProps, PageHeaderProps, PageTabsProps, RecordDetailsProps, RecordHighlightsProps, RecordRelatedListProps } from '@objectstack/spec/ui'; + +// Validate data +const result = PageCardProps.parse(data); +``` + +--- + +## PageCardProps + + +--- + +## PageHeaderProps + + +--- + +## PageTabsProps + + +--- + +## RecordDetailsProps + + +--- + +## RecordHighlightsProps + + +--- + +## RecordRelatedListProps + + +--- + diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx new file mode 100644 index 000000000..4f6e644a9 --- /dev/null +++ b/content/docs/references/ui/dashboard.mdx @@ -0,0 +1,35 @@ +--- +title: Dashboard +description: Dashboard protocol schemas +--- + +Dashboard Widget Schema + +A single component on the dashboard grid. + + +**Source:** `packages/spec/src/ui/dashboard.zod.ts` + + +## TypeScript Usage + +```typescript +import { Dashboard, DashboardWidget } from '@objectstack/spec/ui'; +import type { Dashboard, DashboardWidget } from '@objectstack/spec/ui'; + +// Validate data +const result = Dashboard.parse(data); +``` + +--- + +## Dashboard + + +--- + +## DashboardWidget + + +--- + diff --git a/content/docs/references/ui/meta.json b/content/docs/references/ui/meta.json new file mode 100644 index 000000000..d177bd776 --- /dev/null +++ b/content/docs/references/ui/meta.json @@ -0,0 +1,15 @@ +{ + "title": "UI Protocol", + "pages": [ + "action", + "app", + "chart", + "component", + "dashboard", + "page", + "report", + "theme", + "view", + "widget" + ] +} \ No newline at end of file diff --git a/content/docs/references/ui/page.mdx b/content/docs/references/ui/page.mdx new file mode 100644 index 000000000..8b3f24757 --- /dev/null +++ b/content/docs/references/ui/page.mdx @@ -0,0 +1,50 @@ +--- +title: Page +description: Page protocol schemas +--- + +Page Region Schema + +A named region in the template where components are dropped. + + +**Source:** `packages/spec/src/ui/page.zod.ts` + + +## TypeScript Usage + +```typescript +import { Page, PageComponent, PageComponentType, PageRegion, PageVariable } from '@objectstack/spec/ui'; +import type { Page, PageComponent, PageComponentType, PageRegion, PageVariable } from '@objectstack/spec/ui'; + +// Validate data +const result = Page.parse(data); +``` + +--- + +## Page + + +--- + +## PageComponent + + +--- + +## PageComponentType + + +--- + +## PageRegion + + +--- + +## PageVariable + + +--- + diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx new file mode 100644 index 000000000..1cd148a6a --- /dev/null +++ b/content/docs/references/ui/report.mdx @@ -0,0 +1,48 @@ +--- +title: Report +description: Report protocol schemas +--- + +Report Type Enum + + +**Source:** `packages/spec/src/ui/report.zod.ts` + + +## TypeScript Usage + +```typescript +import { Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui'; +import type { Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui'; + +// Validate data +const result = Report.parse(data); +``` + +--- + +## Report + + +--- + +## ReportChart + + +--- + +## ReportColumn + + +--- + +## ReportGrouping + + +--- + +## ReportType + + +--- + diff --git a/content/docs/references/ui/theme.mdx b/content/docs/references/ui/theme.mdx new file mode 100644 index 000000000..7994c94ed --- /dev/null +++ b/content/docs/references/ui/theme.mdx @@ -0,0 +1,75 @@ +--- +title: Theme +description: Theme protocol schemas +--- + +Color Palette Schema + +Defines brand colors and their variants. + + +**Source:** `packages/spec/src/ui/theme.zod.ts` + + +## TypeScript Usage + +```typescript +import { Animation, BorderRadius, Breakpoints, ColorPalette, Shadow, Spacing, Theme, ThemeMode, Typography, ZIndex } from '@objectstack/spec/ui'; +import type { Animation, BorderRadius, Breakpoints, ColorPalette, Shadow, Spacing, Theme, ThemeMode, Typography, ZIndex } from '@objectstack/spec/ui'; + +// Validate data +const result = Animation.parse(data); +``` + +--- + +## Animation + + +--- + +## BorderRadius + + +--- + +## Breakpoints + + +--- + +## ColorPalette + + +--- + +## Shadow + + +--- + +## Spacing + + +--- + +## Theme + + +--- + +## ThemeMode + + +--- + +## Typography + + +--- + +## ZIndex + + +--- + diff --git a/content/docs/references/ui/view.mdx b/content/docs/references/ui/view.mdx new file mode 100644 index 000000000..9b2badce3 --- /dev/null +++ b/content/docs/references/ui/view.mdx @@ -0,0 +1,103 @@ +--- +title: View +description: View protocol schemas +--- + +HTTP Method Enum + + +**Source:** `packages/spec/src/ui/view.zod.ts` + + +## TypeScript Usage + +```typescript +import { CalendarConfig, FormField, FormSection, FormView, GanttConfig, HttpMethod, HttpRequest, KanbanConfig, ListColumn, ListView, NavigationConfig, NavigationMode, PaginationConfig, SelectionConfig, View, ViewData } from '@objectstack/spec/ui'; +import type { CalendarConfig, FormField, FormSection, FormView, GanttConfig, HttpMethod, HttpRequest, KanbanConfig, ListColumn, ListView, NavigationConfig, NavigationMode, PaginationConfig, SelectionConfig, View, ViewData } from '@objectstack/spec/ui'; + +// Validate data +const result = CalendarConfig.parse(data); +``` + +--- + +## CalendarConfig + + +--- + +## FormField + + +--- + +## FormSection + + +--- + +## FormView + + +--- + +## GanttConfig + + +--- + +## HttpMethod + + +--- + +## HttpRequest + + +--- + +## KanbanConfig + + +--- + +## ListColumn + + +--- + +## ListView + + +--- + +## NavigationConfig + + +--- + +## NavigationMode + + +--- + +## PaginationConfig + + +--- + +## SelectionConfig + + +--- + +## View + + +--- + +## ViewData + + +--- + diff --git a/content/docs/references/ui/widget.mdx b/content/docs/references/ui/widget.mdx new file mode 100644 index 000000000..8dae68648 --- /dev/null +++ b/content/docs/references/ui/widget.mdx @@ -0,0 +1,83 @@ +--- +title: Widget +description: Widget protocol schemas +--- + +Widget Lifecycle Hooks Schema + +Defines lifecycle callbacks for custom widgets inspired by Web Components and React. + +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 https://react.dev/reference/react/Component#component-lifecycle + +@example + +```typescript + +const widget = { + +lifecycle: { + +onMount: "console.log('Widget mounted')", + +onUpdate: "if (prevProps.value !== props.value) { updateUI() }", + +onUnmount: "cleanup()", + +onValidate: "return value.length > 0 ? null : 'Required field'" + +} + +} + +``` + + +**Source:** `packages/spec/src/ui/widget.zod.ts` + + +## TypeScript Usage + +```typescript +import { FieldWidgetProps, WidgetEvent, WidgetLifecycle, WidgetManifest, WidgetProperty, WidgetSource } from '@objectstack/spec/ui'; +import type { FieldWidgetProps, WidgetEvent, WidgetLifecycle, WidgetManifest, WidgetProperty, WidgetSource } from '@objectstack/spec/ui'; + +// Validate data +const result = FieldWidgetProps.parse(data); +``` + +--- + +## FieldWidgetProps + + +--- + +## WidgetEvent + + +--- + +## WidgetLifecycle + + +--- + +## WidgetManifest + + +--- + +## WidgetProperty + + +--- + +## WidgetSource + + +--- + From 0f5ab4d8f1193e940bef5f7cdeb5ed1e9797412a Mon Sep 17 00:00:00 2001 From: Jack Zhuang <50353452+hotlong@users.noreply.github.com> Date: Tue, 10 Feb 2026 10:43:59 +0800 Subject: [PATCH 5/6] fix: remove unused zod-to-json-schema dependency and update JSON schema conversion to use Zod v4's built-in method --- packages/spec/package.json | 3 +-- packages/spec/scripts/build-schemas.ts | 8 +++----- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/packages/spec/package.json b/packages/spec/package.json index f65591166..d0b8f935b 100644 --- a/packages/spec/package.json +++ b/packages/spec/package.json @@ -112,8 +112,7 @@ "@vitest/coverage-v8": "^4.0.18", "tsx": "^4.21.0", "typescript": "^5.3.0", - "vitest": "^4.0.18", - "zod-to-json-schema": "^3.25.1" + "vitest": "^4.0.18" }, "dependencies": { "zod": "^4.3.6" diff --git a/packages/spec/scripts/build-schemas.ts b/packages/spec/scripts/build-schemas.ts index 81ba471cb..3e91b4216 100644 --- a/packages/spec/scripts/build-schemas.ts +++ b/packages/spec/scripts/build-schemas.ts @@ -3,7 +3,6 @@ import fs from 'fs'; import path from 'path'; import { z } from 'zod'; -import { zodToJsonSchema } from 'zod-to-json-schema'; import * as Protocol from '../src/index'; const OUT_DIR = path.resolve(__dirname, '../json-schema'); @@ -118,10 +117,9 @@ for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) { const schemaName = key.endsWith('Schema') ? key.replace('Schema', '') : key; try { - // Convert to JSON Schema - const jsonSchema = zodToJsonSchema(value, { - name: schemaName, - $refStrategy: "none" // We want self-contained schemas for now + // Convert to JSON Schema using Zod v4's built-in toJSONSchema() + const jsonSchema = z.toJSONSchema(value, { + target: 'draft-2020-12', }); const fileName = `${schemaName}.json`; From 58832764df259c10e6d0f985dea12fb36a2a8998 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <50353452+hotlong@users.noreply.github.com> Date: Tue, 10 Feb 2026 10:52:35 +0800 Subject: [PATCH 6/6] fix: enhance JSON schema generation with unsupported type handling and remove zod-to-json-schema dependency --- packages/spec/scripts/build-schemas.ts | 36 +++++++++++++++++++++----- pnpm-lock.yaml | 12 --------- 2 files changed, 30 insertions(+), 18 deletions(-) diff --git a/packages/spec/scripts/build-schemas.ts b/packages/spec/scripts/build-schemas.ts index 3e91b4216..f159c1975 100644 --- a/packages/spec/scripts/build-schemas.ts +++ b/packages/spec/scripts/build-schemas.ts @@ -91,8 +91,20 @@ ensureDir(OUT_DIR); console.log(`Generating JSON Schemas to ${OUT_DIR}...`); let count = 0; +let skippedCount = 0; let errorCount = 0; +// Error messages for schema types that inherently cannot be represented in JSON Schema. +// These are expected warnings, not build-breaking errors. +const KNOWN_UNSUPPORTED_PATTERNS = [ + 'cannot be represented in JSON Schema', +]; + +function isKnownUnsupported(error: unknown): boolean { + const msg = error instanceof Error ? error.message : String(error); + return KNOWN_UNSUPPORTED_PATTERNS.some((p) => msg.includes(p)); +} + // Protocol now exports namespaces (Data, UI, System, AI, API) // We need to iterate through each namespace for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) { @@ -126,21 +138,33 @@ for (const [namespaceName, namespaceExports] of Object.entries(Protocol)) { const filePath = path.join(categoryDir, fileName); writeFileWithRetry(filePath, JSON.stringify(jsonSchema, null, 2)); - console.log(`✓ ${namespaceName.toLowerCase()}/${fileName}`); + console.log(` ✓ ${namespaceName.toLowerCase()}/${fileName}`); count++; } catch (error) { - console.error(`Failed to generate schema for ${namespaceName}.${key}:`, error); - errorCount++; + if (isKnownUnsupported(error)) { + // Functions, transforms, Date types etc. have no JSON Schema representation — skip gracefully + const msg = error instanceof Error ? error.message : String(error); + console.warn(` ⊘ ${namespaceName}.${key}: ${msg} (skipped)`); + skippedCount++; + } else { + console.error(` ✗ Failed to generate schema for ${namespaceName}.${key}:`, error); + errorCount++; + } } } } } } +console.log(`\n─── Summary ───`); +console.log(` Generated: ${count}`); +if (skippedCount > 0) { + console.log(` Skipped: ${skippedCount} (unsupported types: function, transform, date)`); +} + if (errorCount > 0) { - console.error(`\n❌ Completed with ${errorCount} error(s). ${count} schemas generated successfully.`); - console.error(`\nNote: Partial schema generation occurred. Some schemas may be missing.`); - console.error(`This typically indicates a Zod schema definition error or file system issue.`); + console.error(` Errors: ${errorCount}`); + console.error(`\n❌ Build failed with ${errorCount} unexpected error(s).`); process.exit(1); } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0e585c7a5..1665cb78a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -737,9 +737,6 @@ importers: vitest: specifier: ^4.0.18 version: 4.0.18(@types/node@25.2.2)(happy-dom@20.5.3)(jiti@2.6.1)(lightningcss@1.30.2)(msw@2.12.9(@types/node@25.2.2)(typescript@5.9.3))(tsx@4.21.0) - zod-to-json-schema: - specifier: ^3.25.1 - version: 3.25.1(zod@4.3.6) packages/types: dependencies: @@ -4625,11 +4622,6 @@ packages: resolution: {integrity: sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw==} engines: {node: '>=18'} - zod-to-json-schema@3.25.1: - resolution: {integrity: sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==} - peerDependencies: - zod: ^3.25 || ^4 - zod@4.3.6: resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==} @@ -8668,10 +8660,6 @@ snapshots: yoctocolors-cjs@2.1.3: {} - zod-to-json-schema@3.25.1(zod@4.3.6): - dependencies: - zod: 4.3.6 - zod@4.3.6: {} zwitch@2.0.4: {}